JavaScript CSS.registerProperty 怎样声明可动画自定义属性

如果你把颜色、角度或长度放进 CSS 自定义属性，再直接写 transition: --theme-color 300ms，动画可能不会按预期插值。原因不是变量不能使用，而是普通自定义属性默认只被当作一段未解析的值，浏览器不知道它属于颜色、长度还是别的类型。

CSS.registerProperty() 的作用，就是把自定义属性的名称、语法类型、继承策略和初始值交给浏览器。注册成功后，浏览器才有机会按类型处理它，例如把两个颜色值或两个长度值连续过渡。下面只围绕“怎样声明可动画自定义属性”展开。

官方资料：https://developer.mozilla.org/en-US/docs/Web/API/CSS/registerProperty_static

先确定注册解决的问题

普通自定义属性适合保存主题色、间距或组件参数，但它的值在 CSSOM 中通常以未解析的 token 保存。对渐变、颜色或长度做动画时，浏览器需要知道值的类型和初始值；只写变量名并不会自动补上这些信息。

注册后，下面四个节点形成一个完整声明：JavaScript 里的 CSS.registerProperty() 接收定义对象，定义对象提供 name、syntax、inherits 和 initialValue，CSS 再通过 var() 读取这个属性。图中只表达这些静态关系，不代表浏览器运行截图。

按四个字段声明属性

最小可用写法如下。例子把 --accent-color 声明为颜色，不从父元素继承，并给出一个初始值。

// 把 --accent-color 注册成可被浏览器识别的颜色属性
CSS.registerProperty({
  name: "--accent-color",       // 自定义属性必须以两个短横线开头
  syntax: "",            // 告诉浏览器该值按颜色语法解析
  inherits: false,               // 组件内部使用时不从父元素继承
  initialValue: "#4f46e5"        // 未显式赋值时使用的初始颜色
});

name 是必须字段，名称要符合自定义属性命名规则，例如 --accent-color。syntax 可以写成 、 等类型；省略时默认是通配语法 *，这通常不能帮助浏览器判断如何插值。inherits 也是必须字段，true 表示继承，false 表示不继承。initialValue 是可选字段，但对非通配类型的声明，给出与语法匹配的初始值更容易得到稳定结果。

这个 API 的返回值是 undefined，它不是用来读取或设置属性值的。真正的值仍通过 CSS 规则、内联样式或 element.style.setProperty() 写入。

把属性接到 transition

完成注册后，CSS 只需要像使用普通自定义属性一样读取它。下面的卡片把自定义颜色用于渐变，并在悬停或聚焦时改变颜色。

/* 让背景和自定义颜色都由组件自身控制 */
.card {
  --accent-color: #4f46e5; /* 注册后的颜色变量可以参与插值 */
  background: linear-gradient(135deg, white, var(--accent-color));
  transition: --accent-color 300ms ease-in-out;
}

/* 悬停与键盘聚焦共用同一个动效状态 */
.card:hover,
.card:focus-visible {
  --accent-color: #06b6d4;
}

这时需要区分两个概念：注册定义“值是什么类型、是否继承、默认是什么”，CSS 规则定义“何时写入什么值”。如果只改了 transition，没有注册属性，浏览器未必能从旧颜色过渡到新颜色；如果注册了属性却没有在 CSS 中改变它，也不会凭空产生动画。

长度、角度也可以采用相同思路。例如声明 --lift 为 ，再把它用于 transform: translateY(var(--lift))。需要注意的是，语法类型必须和实际写入的值匹配，不要用颜色语法承载长度或把带单位的长度写成裸数字。

处理重复注册与兼容性

注册动作通常放在模块初始化阶段，而且同一个名称只能成功注册一次。不要在每次渲染组件时无条件调用，否则第二次执行可能抛出 InvalidModificationError。

// 只在当前浏览器提供 API 时注册，并把重复注册当作初始化问题处理
function registerAccentColor() {
  if (!window.CSS || typeof window.CSS.registerProperty !== "function") {
    return false; // 不支持时交给普通变量或静态样式降级
  }

  try {
    window.CSS.registerProperty({
      name: "--accent-color", // 名称必须与 CSS 中使用的名称完全一致
      syntax: "",       // 写入值保持为合法颜色
      inherits: false,          // 避免组件从外层意外继承
      initialValue: "#4f46e5"   // 提供可渲染的默认值
    });
    return true;
  } catch (error) {
    // 重复注册或参数错误都应终止本次增强，不阻塞基础样式
    if (error.name === "InvalidModificationError" || error.name === "SyntaxError" || error.name === "TypeError") {
      return false;
    }
    throw error; // 非预期错误继续抛出，方便定位初始化故障
  }
}

const motionReady = registerAccentColor();

三类常见异常分别对应不同问题：名称已经注册时是 InvalidModificationError；名称不是以两个短横线开头等命名错误通常是 SyntaxError；缺少必须的 name 或 inherits 时可能是 TypeError。这些异常不是“动画不流畅”的性能问题，而是声明阶段就没有建立成功。

兼容性处理的重点是能力检测。检查失败时仍可保留静态背景和普通 CSS 变量，只是不把“自定义属性本身的平滑插值”作为必需功能。不要把浏览器版本号硬编码成唯一判断条件，因为实际能力检测比版本字符串更直接。

按场景做落地检查

可以用下面这份清单快速复查：

如果动画仍然没有变化，先确认属性确实在状态切换时被重新赋值，再检查 syntax 是否允许这两个值之间插值，最后才去看 transition 时长和缓动函数。这样可以把“没有注册”“没有改值”和“改值不可插值”三个问题分开。

常见问题

CSS.registerProperty() 能直接设置属性值吗？

不能。它只注册属性定义；属性值仍由 CSS 声明、内联样式或脚本设置。

为什么 name 必须写成 --accent-color？

因为它必须是合法的 CSS 自定义属性名。少写一个短横线会在注册阶段触发名称错误。

inherits 写 true 还是 false？

看属性是否应该跨组件边界传递。主题配置可以考虑继承，组件自身的动画参数通常更适合显式设为不继承。

普通自定义属性一定不能动画吗？

关键区别在于浏览器能否解析并插值该值。需要稳定的类型化动画时，显式注册通常更清楚，也更容易排查。

总结一下：先用 CSS.registerProperty() 声明名称、语法、继承和初始值，再在 CSS 中改变该变量并把它接入具体属性。把注册放在一次性初始化位置，同时保留能力检测和静态降级，就能把可动画自定义属性控制在清晰、可维护的边界内。