Vite React项目中TypeScript不识别div的name属性如何解决？

问题原因 #

TypeScript严格遵循HTML标准规范，<div>标签原生并不支持name属性，因此TS会对该属性抛出类型不匹配的错误。

解决方案 #

1. 使用data-*自定义属性（推荐）

HTML允许通过data-*格式定义自定义属性，TypeScript完全支持这类属性，不会触发类型错误：

<div
  data-name='contact'
  className='w-full h-screen bg-dark text-white flex justify-center items-center p-4'
>
  ...
</div>

后续需要读取该属性值时，可通过element.dataset.name获取。

2. 类型断言跳过检查（临时方案）

如果必须使用name属性，可以通过类型断言关闭TypeScript的类型检查：

// 方式1：对整个div标签断言
<div
  name='contact'
  className='w-full h-screen bg-dark text-white flex justify-center items-center p-4'
>
  ...
</div> as any

// 方式2：仅对name属性断言
<div
  {...({ name: 'contact' } as React.HTMLAttributes<HTMLDivElement>)}
  className='w-full h-screen bg-dark text-white flex justify-center items-center p-4'
>
  ...
</div>

注意：这种方法会绕过TS的类型校验，可能隐藏潜在问题，仅建议在特殊场景下临时使用。

3. 全局扩展HTMLDivElement类型（长期方案）

如果项目中多个地方需要给<div>添加name属性，可以通过全局类型声明扩展TS的类型定义：

1. 在项目src目录下创建global.d.ts文件
2. 添加以下内容：

declare global {
  namespace JSX {
    interface IntrinsicElements {
      div: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement> & {
        name?: string;
      };
    }
  }
}

export {};

添加后，TypeScript会自动识别<div>标签的name属性，无需再做额外处理。

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