通过script标签引入带JSDoc的库无智能提示问题求助

你的猜想完全正确：TypeScript语言服务默认不会自动解析HTML中通过<script>标签引入的外部JS文件的类型信息——哪怕脚本是本地文件，它也不在TS的默认编译上下文范围内，自然无法读取其中的JSDoc标注提供智能提示。

要让通过script标签引入的库也能提供类型支持，有以下几种可行方案：

1. 生成并发布.d.ts声明文件（最可靠的方案） #

虽然你觉得.d.ts是给npm用户用的，但实际上它同样适用于script引入的场景，这也是TypeScript官方推荐的类型分发方式。

• 为你的库生成声明文件：
  1. 项目根目录创建tsconfig.json，配置如下：

     {
       "compilerOptions": {
         "declaration": true,
         "emitDeclarationOnly": true,
         "allowJs": true,
         "outDir": "./types"
       },
       "include": ["mylibrary.js"]
     }
     

  2. 运行tsc命令，会在types目录生成对应的.d.ts文件。
• 你的示例代码生成的声明文件大致如下：

  /**
   * @preserve
   * The main library object
   */
  export interface LibObj {
      /** The name of the library */
      name: string;
  }
  
  declare global {
      interface Window {
          LibObj: LibObj;
      }
  }
  

• 发布时将.d.ts文件和JS库文件放在同一目录，用户引入JS时，VSCode会自动识别同目录的声明文件，提供完整的类型提示和检查。

2. 让用户手动配置项目上下文（针对项目开发者） #

如果用户是在自己的JS/TS项目中通过script引入你的库，可以让他们修改项目的jsconfig.json或tsconfig.json，把你的库文件纳入TS服务的解析范围：

• 示例jsconfig.json配置：

  {
    "compilerOptions": {
      "target": "ESNext"
    },
    "include": ["./path/to/mylibrary.js", "./src/**/*"]
  }
  

  这样TS服务会解析库文件中的JSDoc标注，全局的LibObj就会有正确的类型提示。

3. 优化库的JSDoc写法（辅助增强） #

调整你的JSDoc标注方式，让类型信息更易被TS服务识别：

/**
 * @typedef {object} LibObj - The main library object
 * @property {string} name - The name of the library
 */

/**
 * @type {LibObj}
 * @preserve
 */
globalThis.LibObj = {
  name: "My Library's Name"
};

这种写法能让TS在解析文件时更明确地关联全局变量和类型定义，配合上述的配置方案，能进一步提升类型识别的准确性。

内容的提问来源于stack exchange，提问作者Jacob Runge