本文讲解如何在 react + typescript 项目中安全、类型安全地支持自定义 html 属性（如 `color="red"`），并配合 css 属性选择器使用，同时避免违反 jsx 的类型约束。
在纯 HTML/CSS 中，我们可以直接使用自定义属性（如
）并配合属性选择器（如 div[color="red"]）实现样式控制。但在 React + TypeScript 环境下，JSX 对原生元素（如
）的 props 有严格的类型校验——直接传入非标准属性（如 color）会触发 TS 编译错误，因为 color 并不在 React.HTMLAttributes 的允许列表中。
不过，这并不意味着必须放弃语义化或声明式属性设计。正确做法是：通过类型扩展显式声明自定义属性，并保持与原生属性的兼容性。以下是推荐实现：
import React, { FC } from 'react';
// 扩展原生 div 属性类型，添加受控的 color 属性
type ColoredProps = {
color: 'red' | 'yellow';
} & React.HTMLAttributes<HTMLDivElement>;
const Colored: FC<ColoredProps> = ({ color, ...rest }) => (
<div {...rest} data-color={color}>
{color}
</div>
);
export default Colored;⚠️ 注意：我们不直接使用 color={color}（因 color 非标准 HTML 属性，TS 会报错），而是改用 data-color={color} —— 这是符合 HTML 规范的自定义数据属性（data-*），既可通过 CSS 属性选择器精准匹配，又能被 TypeScript 安全识别：
/* styles.css */
div[data-color='red'] {
color: red;
font-weight: bold;
}
div[data-color='yellow'] {
color: #ffcc00;
text-shadow: 1px 1px 2px rgba(0,0,0,0.3);
}使用时完全自然且类型安全：
立即学习“前端免费学习笔记（深入）”；
<Colored color="red" className="my-div" style={{ margin: '8px' }} />
<Colored color="yellow" id="highlight-item" />✅ 优势总结：
- ✅ 类型安全：color 是必填、枚举受限的字符串，IDE 支持自动补全与错误提示；
- ✅ 标准合规：data-color 符合 HTML5 自定义属性规范，无渲染副作用；
- ✅ CSS 可维护：保留了属性选择器的语义表达力，便于主题化、条件样式管理；
- ✅ 可扩展性强：后续可轻松增加 size="sm" | "lg" 等其他 data-* 属性，复用同一模式。
? 替代方案提醒：虽然也可用 className（如 className="color-red"）或内联 style 实现颜色控制，但它们牺牲了「属性驱动样式」的声明式逻辑，不利于 CSS-in-JS 解耦、设计系统抽象及动态主题切换。因此，*`data-` + 属性选择器仍是兼顾语义、类型安全与 CSS 灵活性的最佳实践**。
