TypeScript给HTMLElement新增属性提示类型不存在的解决方法

TypeScript 中通过DOM API创建的HTML元素默认会被推导为HTMLElement（对应标签还会有更细分的类型，比如createElement('div')默认是HTMLDivElement），如果直接给元素挂载标准属性之外的自定义属性，静态类型校验会抛出属性不存在的错误，示例触发的报错如下：

Property 'info' does not exist on type 'HTMLElement'.

错误复现代码 #

function divModify():HTMLElement{
  const div:HTMLElement= document.createElement("div");
  div.id= "test";
  div.classList.add("d-flex");
  const info={text: "Hello word"}
  Object.defineProperty(div,"info",{value:info})
  console.log(div)
  console.log(div.info) // 此处抛出类型错误
  return div
}

divModify()

可行解决方案 #

1. 自定义扩展接口+类型断言（推荐，复用性、类型安全性最优） #

定义继承自对应原生元素类型的接口，声明新增的自定义属性，创建元素后通过类型断言指定为自定义类型即可，不会污染全局类型，还能获得完整的属性类型提示。

// 定义携带info属性的div元素类型
interface DivWithInfo extends HTMLDivElement {
  info: {
    text: string
  }
}

function divModify(): DivWithInfo {
  // 创建元素后断言为自定义类型
  const div = document.createElement("div") as DivWithInfo;
  div.id= "test";
  div.classList.add("d-flex");
  const info = {text: "Hello word"}
  Object.defineProperty(div,"info",{value: info})
  console.log(div)
  console.log(div.info.text) // 有完整类型提示，无校验错误
  return div
}

divModify()

2. 交叉类型临时断言（适合单次使用、自定义属性少的场景） #

如果自定义属性只在当前逻辑中使用，不需要复用类型定义，可以直接用交叉类型拼接原生类型和自定义属性做断言，写法更简洁。

function divModify(): HTMLElement & { info: {text: string} } {
  // 直接用交叉类型做断言
  const div = document.createElement("div") as HTMLElement & { info: {text: string} };
  div.id= "test";
  div.classList.add("d-flex");
  const info = {text: "Hello word"}
  Object.defineProperty(div,"info",{value:info})
  console.log(div)
  console.log(div.info) // 无校验错误
  return div
}

divModify()

3. 全局扩展原生元素类型（仅适合全局通用属性场景，不推荐局部使用） #

如果该自定义属性是项目中所有同类元素都会挂载的通用属性，可以在全局类型声明文件中扩展原生HTMLElement接口，但这种方式会污染全局类型，访问属性时需要额外做存在性校验，避免其他未挂载属性的元素访问时报错。

// 通常放在项目全局类型声明文件（如global.d.ts）中
declare global {
  interface HTMLElement {
    info?: {
      text: string
    }
  }
}

function divModify():HTMLElement{
  const div:HTMLElement= document.createElement("div");
  div.id= "test";
  div.classList.add("d-flex");
  const info={text: "Hello word"}
  Object.defineProperty(div,"info",{value:info})
  console.log(div)
  // 因为是可选属性，需要做存在判断才能安全访问
  if (div.info) {
    console.log(div.info.text)
  }
  return div
}

divModify()

注意事项 #

• 不推荐直接将元素断言为any绕过校验，会丢失所有类型提示，丧失TypeScript的类型安全保障
• 局部使用的自定义属性优先选择前两种方案，类型精准度更高，不会对全局类型造成影响

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