如何在React TypeScript+Vite中使用Material Web3组件并解决TS报错？

DevOps 小满

2026-6-18

React TypeScript + Vite 中使用 Material Web 3 组件的可行性及报错解决

可行性结论

完全可以在 React TypeScript + Vite 项目中使用谷歌 Material Web 3 组件，二者适配性无问题，只需处理 TypeScript 的类型识别问题即可。

报错原因

TypeScript 默认仅识别标准 HTML 元素，md-checkbox 这类自定义 Web Component 不在其内置 JSX 类型定义范围内，因此会抛出 Property 'md-checkbox' does not exist on type 'JSX.IntrinsicElements' 错误。

解决方法

方法1：添加自定义元素类型声明（推荐）
在项目中新建一个 .d.ts 类型声明文件（例如 src/types/material-web.d.ts），写入以下内容：
```
declare namespace JSX {
  interface IntrinsicElements {
    'md-checkbox': React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> & {
      id?: string;
      // 可按需添加md-checkbox的其他属性，如checked、disabled等
    };
  }
}
```
若需使用多个 Material Web 3 组件，直接在 IntrinsicElements 接口内添加对应标签的类型声明即可，比如 'md-button'、'md-text-field' 等。
方法2：临时忽略类型检查（仅用于快速测试）
若只是临时验证组件功能，可在使用自定义元素时添加注释跳过类型检查：
```
// @ts-ignore
<md-checkbox id="checkbox1">Checkbox Material 3</md-checkbox>
```
此方法虽快捷，但会丢失 TypeScript 的类型校验优势，不建议在正式项目中使用。
方法3：使用官方类型定义（若有提供）
部分 Material Web 3 组件可能配套了官方 TypeScript 类型包，可查看组件文档，安装对应的 @types 包或官方类型文件，以获得更精准的类型支持。