CSS @property 怎样让自定义属性支持平滑动画

如果你把颜色、角度或进度值放进 CSS 自定义属性，再直接给它写 transition 或 animation，经常会发现效果不是平滑变化，而是从旧值突然跳到新值。原因通常不是动画时长，而是浏览器不知道这个自定义属性究竟是颜色、数字还是一段任意文本。

官方地址：https://developer.mozilla.org/en-US/docs/Web/CSS/%40property

@property 的作用是把自定义属性注册成有类型的 CSS 属性。给它声明 syntax、inherits 和 initial-value 后，浏览器才有机会按颜色、数字等类型计算中间值，动画也就能真正插值。

普通自定义属性为什么容易出现跳变

以 --progress 为例，普通写法只告诉浏览器“这里有一段变量值”，并没有规定它只能是数字。对浏览器来说，从 0 变成 100 可能只是两个离散 token，不能像 opacity 那样计算中间帧。

所以要先把问题拆开：自定义属性负责保存值，var() 负责取值，而 @property 负责告诉 CSS 这个值的语法类型、是否继承以及没有显式赋值时的初始值。

用 @property 注册一个可插值的数值变量

先声明进度变量为数字，再让关键帧改变它。下面的例子把数字映射到环形渐变和缩放效果，重点是 syntax: ""：它给变量增加了明确的计算类型。

/* 先声明变量的类型、继承规则和默认值，避免它被当成任意文本。 */
@property --progress {
  syntax: "";
  inherits: false;
  initial-value: 0;
}

.meter {
  /* 让组件从声明的初始数字开始渲染。 */
  --progress: 0;
  width: 180px;
  aspect-ratio: 1;
  border-radius: 50%;
  background: conic-gradient(#3b82f6 calc(var(--progress) * 1%), #e5e7eb 0);
  transform: scale(calc(0.9 + var(--progress) / 1000));
  animation: fill-meter 1.2s ease-out forwards;
}

/* 关键帧只改变数字变量，渐变和缩放会读取它的中间值。 */
@keyframes fill-meter {
  to {
    --progress: 100;
  }
}

这里的 inherits: false 表示子元素不会自动继承这个变量；如果组件需要从父级接收主题或进度，就应改成 true，同时重新检查初始值是否符合组件边界。initial-value 则让变量在没有显式赋值时仍有确定起点。

颜色变量也要声明成对应类型

颜色是另一个常见场景。普通的 --accent 可能只能离散切换，但注册为 后，颜色值就有了可计算的类型。示例使用 transition，不需要额外的 JavaScript。

/* 颜色变量必须声明为 ，浏览器才知道怎样计算中间颜色。 */
@property --accent {
  syntax: "";
  inherits: true;
  initial-value: #2563eb;
}

.button {
  /* 过渡的是已注册的自定义属性，而不是一段未知文本。 */
  --accent: #2563eb;
  color: white;
  background: var(--accent);
  transition: --accent 240ms ease;
}

.button:hover {
  /* 颜色会在旧值和新值之间连续变化。 */
  --accent: #9333ea;
}

如果你希望动画由关键帧驱动，也可以把 --accent 放到 @keyframes 里。不要同时用一个名字声明为颜色又在另一个组件里期待它表示数字；注册规则应和变量在当前组件中的语义保持一致。

syntax、inherits 和 initial-value 怎么选

最容易忽略的是三者必须互相匹配。比如 syntax 写成 ，却把 initial-value 写成颜色，整个声明就不适合作为可靠的组件基础；把 inherits 设为 true 后，也要确认子元素不会意外读取父级状态。

兼容处理和排查重点

先确认目标浏览器对 CSS Properties and Values API 的支持范围，再决定是否采用。对不支持 @property 的环境，普通自定义属性仍可作为静态值或离散切换的降级方案，但不要把它描述成等价的平滑动画。

排查时按这个顺序看：第一，变量名是否在 @property 和使用处完全一致；第二，syntax 是否与实际值匹配；第三，initial-value 是否为同类型合法值；第四，动画是否真的修改了这个变量，而不是只修改了引用它的另一条声明。若是颜色动画，还要确认最终呈现属性确实使用了 var(--accent)。

小结

CSS 自定义属性能否平滑动画，关键不在变量名，而在浏览器是否知道它的值类型。使用 @property 时记住三点：用 syntax 描述可计算类型，用 inherits 控制组件边界，用 initial-value 提供合法起点。数值、颜色和长度等场景都应先注册，再让 transition 或 animation 改变变量。

相关问题

只写 transition 不写 @property 可以吗？

可以得到静态切换，但对任意自定义属性不能默认期待连续中间帧。需要颜色、数字或长度平滑变化时，应先注册对应类型。

inherits 应该一直写 false 吗？

不是。组件内部状态通常适合禁止继承，主题色等跨层共享的变量则可能需要继承。选择时要看变量是否属于父子组件共同语义。

@property 能替代所有 JavaScript 动画吗？

不能。它只解决 CSS 自定义属性的声明和插值问题；复杂的交互状态、物理计算和需要脚本控制的时间线仍应由合适的 JavaScript 或 Web Animations API 负责。