如何不覆盖openseadragon原有类型，扩展Viewer适配openseadragonselection

自定义类型覆盖openseadragon基础类型的本质，是写法触发了TypeScript的全局模块重声明规则，没有用原生的「模块增补（Module Augmentation）」能力实现对现有类型的扩展。
TypeScript对模块的类型操作分两种逻辑：

• 如果一个.d.ts文件是无顶层import/export的全局脚本，内部写declare module 'openseadragon' {}会完全替换原有同名模块的全部类型定义，哪怕内容是空的
• 如果一个.d.ts文件本身是ES模块（存在至少一个顶层import/export语句），内部写declare module 'openseadragon'时，会将内部定义的类型与原有模块的现有定义做声明合并，完全不会覆盖原有内容

正确实现步骤 #

1. 配置自定义类型目录
   • 在项目根目录新建./types/openseadragonselection目录，存放自定义类型文件
   • 调整项目tsconfig.json配置，确保TypeScript能同时加载官方@types包和自定义类型：

     {
       "compilerOptions": {
         // 同时包含两类类型的加载路径
         "typeRoots": ["node_modules/@types", "./types"],
         // 减少第三方类型文件本身语法问题带来的编译报错
         "skipLibCheck": true,
         // 确保模块解析规则能正确识别类型增补逻辑
         "moduleResolution": "bundler"
       }
     }
     

2. 编写类型定义
   • 在新建的目录下创建index.d.ts文件，必须在文件开头加入空的export {}将文件标记为ES模块，从根源上避免触发全局重声明逻辑。
   • 不需要照搬网上找到的第三方类型文件的全部内容，只需要提取selection方法相关的核心API结构，通过声明合并的方式挂载到openseadragon模块的Viewer接口上，参考写法：

     // *关键：空导出将文件标记为ES模块，切换为类型增补逻辑*
     export {};
     
     // 对现有openseadragon模块做类型扩展，而非重新定义整个模块
     declare module 'openseadragon' {
       // selection方法支持的入参结构
       interface SelectionOptions {
         element?: HTMLElement;
         keyboardShortcuts?: boolean;
         toggleButton?: HTMLElement;
         onSelection?: (event: SelectionBounds) => void;
         // 根据openseadragonselection的实际API补充剩余参数
       }
     
       // selection返回的选区边界结构
       interface SelectionBounds {
         x: number;
         y: number;
         width: number;
         height: number;
         viewportWidth: number;
         viewportHeight: number;
       }
     
       // selection实例返回的控制器方法
       interface SelectionController {
         enable(): void;
         disable(): void;
         clear(): void;
         getBounds(): SelectionBounds;
       }
     
       // *核心：通过声明合并给原有Viewer接口新增selection方法，完全不影响原有接口的定义*
       interface Viewer {
         selection(options?: SelectionOptions): SelectionController;
       }
     }
     

3. 效果验证
   配置完成后，可直接在代码中调用viewer.selection({...})方法，TypeScript会完整保留@types/openseadragon包中Viewer的所有原有方法类型提示，不会出现基础方法类型丢失的问题。

常见避坑点 #

• 不要在全局脚本类型文件里直接写空的declare module 'openseadragon'块，这种写法会直接把原有模块的所有类型替换掉，必须配合文件层面的export {}标记才能正常合并
• 网上找到的零散类型文件大多是早期TypeScript的全局脚本写法，本身没有做模块隔离，直接引入很容易触发类型覆盖，只需要提取核心API结构用增补写法重写即可
• 如果写完后仍出现类型丢失，检查moduleResolution配置，使用node或bundler解析模式才能正确识别模块增补逻辑

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