如何为TypeScript标准库中的现有联合类型添加可选值？

问题背景 #

lib.dom.d.ts中声明的PermissionName是联合类型：

type PermissionName = "geolocation" | "notifications" | // 其他取值...

你尝试在app.d.ts中扩展该类型，但以下写法无法生效：

declare global {
    type PermissionName = PermissionName | "local-fonts";
}
export {}

目标是让await navigator.permissions.query({ name: "local-fonts" })正常通过类型检查，且不影响原有依赖该类型的API。

有效解决方案 #

方案1：扩充PermissionDescriptor接口 #

navigator.permissions.query接收的参数属于PermissionDescriptor类型，直接扩展该接口的name属性即可：

// app.d.ts
declare global {
  interface PermissionDescriptor {
    name: PermissionName | "local-fonts";
  }
}
export {};

此方案无需改动全局PermissionName本身，直接修改查询参数的类型定义，能快速满足需求。

方案2：重新定义全局PermissionName类型 #

通过import type引入原始PermissionName类型，合并新取值后重新声明全局类型：

// app.d.ts
declare global {
  type PermissionName = import("lib.dom").PermissionName | "local-fonts";
}
export {};

该方案直接更新全局PermissionName类型，所有依赖此类型的API都会自动识别新增的"local-fonts"取值。

原代码失效原因 #

你之前的写法会导致循环类型引用：PermissionName的定义依赖自身未解析的类型，TypeScript无法正确处理这种递归逻辑，因此无法生效。

注意事项 #

• 确保app.d.ts被包含在tsconfig.json的include数组中，让TypeScript编译器能识别该声明文件。
• 两种方案均无需使用<any>绕过类型检查，能保持代码的类型安全性。

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