自定义属性：从html到react

在现代前端架构（尤其是像 Radix UI 和 Tailwind 这种组合）中， HTML 属性（Attributes）就是连接逻辑和视觉的唯一纽带。

JS (JavaScript) ：负责决定什么时候改属性。
HTML (DOM) ：负责存储这些属性。
CSS (Tailwind) ：负责根据属性的数值，实时变换演员的衣服和动作（动画）。

想象我们要实现：点击按钮，方块变红并旋转。

HTML：定义“演员” 复制代码

<!-- 方块默认状态是 data-active="false" -->
<div id="box" data-active="false"></div>
<button id="btn">切换状态</button>

CSS：定义“剧本”（根据属性变样）复制代码

#box {
  width: 100px;
  height: 100px;
  background: blue;
  transition: all 0.5s; /* 开启平滑动画 */
}

css 复制代码

/* 关键：当属性变为 true 时，剧本要求它变色并旋转 */
#box[data-active="true"] {
  background: red;
  transform: rotate(45deg);
}

JS：定义“导演”（只负责改属性）复制代码

const box = document.getElementById('box');
const btn = document.getElementById('btn');

btn.onclick = () => {
  // 导演只做一件事：把属性在 true 和 false 之间切换
  const currentState = box.getAttribute('data-active');
  box.setAttribute('data-active', currentState === 'true' ? 'false' : 'true');
};

JS 不直接操作样式：JS代码里没有写 box.style.color = 'red' 。它只是像拨动开关一样，改了一下 data-active 这个属性。
HTML 存储状态：此时，如果你去检查网页元素，你会看到 HTML 标签在<div data-active="true"> 和 <div data-active="false"> 之间跳变。HTML 成了状态的"记录本"。
CSS 自动响应：CSS 就像一个潜伏的哨兵，它一直盯着 [data-active="true"] 这个信号。只要信号一现，它立刻根据"剧本"让方块变红、旋转。

在 Web 开发中，任何"自定义属性"最终都必须通过某种方式与"原生能力"接轨，否则它就是一段死代码。所有精美的 UI 框架（React, Vue, Tailwind）本质上都是一套"翻译系统"。它们存在的唯一目的，就是帮你把那些符合人类逻辑的自定义属性，高效、准确地转化成浏览器真正听得懂的原生属性、关联到浏览器真正认识的原生属性和事件上。

我们可以把这种关联关系归纳为以下三种模式：

模式 1：直接关联（翻译模式）

场景：你设计了一个 MyInput 组件，想提供一个更简单的 onTextChange 属性，直接返回字符串。

ini 复制代码

// 1. 自定义属性：onTextChange
function MyInput({ onTextChange }) {
  return (
    <input 
      type="text" 
      // 2. 关联点：关联到原生的 onChange
      onChange={(e) => {
        // 3. 翻译过程：把复杂的原生 Event 对象，翻译成简单的字符串
        const text = e.target.value;
        onTextChange(text); 
      }}
    />
  );
}

// 使用时：
<MyInput onTextChange={(val) => console.log("输入了：", val)} />

本质： onTextChange 是虚构的，它只是原生 onChange 的一个过滤器。

模式 2：样式关联（信号模式）

场景：你设计了一个 Avatar （头像）组件，有一个 shape 属性来控制是圆的还是方的。

javascript 复制代码

// 1. 自定义属性：shape ("circle" | "square")
function Avatar({ shape }) {
  // 2. 关联点：通过属性计算出原生的 className
  const className = shape === 'circle' ? 'rounded-full' : 'rounded-none';

  return (
    <div className={`overflow-hidden ${className}`}>
      <img src="avatar.png" />
    </div>
  );
}

// 使用时：
<Avatar shape="circle" />

本质： shape="circle" 这个信号，最终被翻译成了原生的 CSS 属性 border-radius: 9999px 。浏览器并不懂什么是 shape ，它只懂 border-radius 。

模式 3：逻辑关联（驱动模式）

场景：你设计了一个 VideoPlayer 组件，有一个 isPaused 属性来控制视频的播放和暂停。

javascript 复制代码

// 1. 自定义属性：isPaused
function VideoPlayer({ isPaused }) {
  const videoRef = useRef<HTMLVideoElement>(null);

  useEffect(() => {
    // 2. 关联点：关联到浏览器的原生 JavaScript API
    if (isPaused) {
      videoRef.current?.pause(); // 调用浏览器原生暂停方法
    } else {
      videoRef.current?.play();  // 调用浏览器原生播放方法
    }
  }, [isPaused]);

  return <video ref={videoRef} src="movie.mp4" />;
}

// 使用时：
<VideoPlayer isPaused={true} />

本质： isPaused 属性在 HTML 标签上可能完全不存在，但它驱动了浏览器底层的功能引擎（视频解码器）。

总结

一句话理解：你定义的每一个 Props（属性），都是在给 React 发送一个"意图" 。React 和你的组件逻辑负责把这个意图"落地"到 HTML 属性、CSS 类名或 JS API 调用上。