Property 'fullscreenElement' 不存在于 Document 类型

Question

在使用 TypeScript 开发全屏功能时，开发者常遇到“Property 'fullscreenElement' does not exist on type 'Document'”的编译错误。这是因为 TypeScript 的 DOM 类型定义中，默认未包含某些实验性或非标准的全屏 API 属性。尽管现代浏览器支持 `document.fullscreenElement` 用于获取当前全屏元素，但 TypeScript 编译器可能因类型定义缺失而报错。常见于较旧版本的 TypeScript 或未启用相应 DOM lib 的项目中。解决方法包括升级 TypeScript 版本、在 `tsconfig.json` 中确保包含 `"dom"` 和 `"dom.iterable"` 类型库，或通过模块扩展手动补充 `FullscreenElement` 类型定义，以绕过类型检查错误。

Answer 1

1. 问题背景与常见表现

在使用 TypeScript 开发前端应用时，实现全屏功能是常见的交互需求。开发者通常会调用 document.fullscreenElement 来判断当前是否有元素处于全屏状态。然而，在编译阶段，TypeScript 可能抛出如下错误：

Property 'fullscreenElement' does not exist on type 'Document'

该错误表明 TypeScript 的类型系统无法识别此属性，尽管现代浏览器（如 Chrome、Firefox、Edge）均已支持该 API。这种不一致主要源于 TypeScript 的 DOM 类型定义文件未包含某些较新或仍在演进中的 Web API。

2. 深层原因分析

• TypeScript 的 DOM 类型库基于 W3C 标准和主流浏览器实现进行建模，但更新存在一定滞后性。
• fullscreenElement 属于 Fullscreen API 的一部分，虽然已被广泛支持，但在旧版本 TypeScript（如 3.x 或早期 4.x）中可能未被纳入默认的 DOM 类型定义。
• 项目中的 tsconfig.json 若未正确配置 "lib" 字段，可能导致缺少必要的 DOM 接口支持。
• 某些构建工具链（如 Create React App 的旧模板）可能锁定特定版本的 TypeScript 和类型库，限制了对新 API 的访问。

3. 解决方案汇总表

方案	适用场景	实施难度	长期维护性
升级 TypeScript 版本	项目可接受版本升级	低	高
检查并配置 tsconfig.json	配置缺失导致问题	低	高
手动扩展 Document 接口	需兼容旧版 TS 或定制环境	中	中

4. 具体解决方法详解

1. 升级 TypeScript 至最新稳定版

   推荐使用 TypeScript 4.4+，其内置了完整的 Fullscreen API 类型定义。可通过以下命令升级：

   npm install typescript@latest --save-dev

2. 确认 tsconfig.json 配置完整性

   确保 compilerOptions.lib 包含 "dom" 和 "dom.iterable"：

   {
     "compilerOptions": {
       "lib": ["es2020", "dom", "dom.iterable"]
     }
   }

3. 通过模块扩展补充类型定义

   创建 types/fullscreen.d.ts 文件，并添加以下内容：

   interface Document {
     readonly fullscreenElement: Element | null;
     readonly webkitFullscreenElement?: Element | null;
     readonly mozFullScreenElement?: Element | null;
     readonly msFullscreenElement?: Element | null;
   }

   然后在 tsconfig.json 中包含该路径：

   "include": ["src/**/*", "types/**/*"]

5. 实际代码示例与跨浏览器兼容处理

function getFullscreenElement(): Element | null {
  return (
    document.fullscreenElement ||
    document.webkitFullscreenElement ||
    document.mozFullScreenElement ||
    document.msFullscreenElement ||
    null
  );
}

function isFullscreen(): boolean {
  return getFullscreenElement() !== null;
}

上述代码结合了标准与厂商前缀属性，确保在不同浏览器中均可正常运行。配合正确的类型扩展后，TypeScript 将不再报错。

6. 流程图：全屏状态检测逻辑与类型修复路径

graph TD A[开始] --> B{TypeScript 编译报错?} B -->|是| C[检查 tsconfig.json lib 配置] C --> D[是否包含 dom/dom.iterable?] D -->|否| E[添加至 lib 数组] D -->|是| F[检查 TypeScript 版本] F --> G[低于 4.4?] G -->|是| H[升级 TypeScript] G -->|否| I[手动扩展 Document 接口] B -->|否| J[正常编译] I --> K[创建全局类型声明文件] K --> L[重新编译] L --> M[问题解决]