TypeScript报错不识别IntersectionObserver v2的delay与trackVisibility选项求助

错误信息 #

Object literal may only specify known properties, and 'trackVisibility' does not exist in type 'IntersectionObserverInit'.ts(2353)

我的代码 #

const observer = new IntersectionObserver(handleIntersection, {
  root: containerRef.current,
  threshold: 1.0,
  trackVisibility: true,
  delay: 300,
});

问题说明 #

trackVisibility和delay是IntersectionObserver v2规范中的配置项，且当前浏览器已支持这些特性，但TypeScript仍报错提示这些属性不存在于IntersectionObserverInit类型中。

项目tsconfig配置 #

{
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": true,
    "skipLibCheck": true,
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "strict": true,
    "forceConsistentCasingInFileNames": true,
    "noFallthroughCasesInSwitch": true,
    "module": "esnext",
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,
    "noUnusedParameters": false,
    "noUnusedLocals": false,
    "jsx": "react-jsx",
    "experimentalDecorators": true,
    "types": ["node", "googlemaps"],
    "baseUrl": "."
  },
  "include": ["src"]
}

解决办法 #

1. 升级TypeScript版本

新版本的TypeScript（4.8及以上）已更新DOM类型定义，包含了IntersectionObserver v2的属性。执行以下命令升级：

npm install typescript@latest --save-dev
# 或使用yarn
yarn add typescript@latest --dev

2. 手动扩展类型定义

如果暂时无法升级TypeScript，可在项目中创建一个类型声明文件（如src/types/intersection-observer.d.ts），添加以下内容扩展IntersectionObserverInit接口：

interface IntersectionObserverInit {
  trackVisibility?: boolean;
  delay?: number;
}

3. 使用类型断言（临时方案）

若需要快速跳过类型检查，可使用类型断言，但不建议长期依赖这种方式：

const observer = new IntersectionObserver(handleIntersection, {
  root: containerRef.current,
  threshold: 1.0,
  trackVisibility: true,
  delay: 300,
} as IntersectionObserverInit);

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