用途:把一个 Lightning Web Component 从 JavaScript 迁移到 TypeScript,交付物是完全类型化的 .ts 实现,外加一个只暴露 @api 成员的 .d.ts 公共接口文件。
适用场景:用户想把单个组件或一批组件从 .js 改为 .ts;需要为已有 LWC 生成 .d.ts 供其他组件或外部 TypeScript 宿主安全导入;为已改名但尚未类型化的 .ts LWC 补类型;把 JSDoc 风格类型提示升级为真实 TypeScript 类型。
前置条件:组件当前在 JavaScript 下能正常构建运行;可用 git;构建中已接入 TypeScript 编译器(SFDX TS 流水线或独立 tsc 步骤)。
工作流程:读取 bundle 中所有文件,确认继承 LightningElement 的类名、带 @api 的字段与方法、已有 JSDoc 及可推断的参数与返回类型。用 git mv 将 .js 重命名为 .ts,保留历史(不要用普通 mv)。在 .ts 中加类型:优先标注 @api 成员,复杂结构抽成 interface/type 别名,可选成员才加 ?,私有状态加 private 且不导出类型;事件处理器优先精确 DOM 类型,onclick 用 MouseEvent,onpointer* 用 PointerEvent,自定义事件用 CustomEvent<{ detail: ... }>,异步方法返回 Promise<T>,避免 any,必要时用 unknown 加类型守卫。随后生成同名 .d.ts:仅含 @api 成员,逐字保留 @api 的 JSDoc(含 @type、@required、@default、@param、@returns),声明 c/componentName 模块命名空间;无 @api 时仍生成带说明注释的模块声明。最后编译并测试。
验证:运行 tsc --noEmit 或构建等价命令,零错误、不使用 @ts-ignore;运行现有 Jest 测试,行为应保持一致;无条件运行消费方查找脚本查找导入该组件的其他组件: