CSS @property 实战：让 CSS 变量支持 transition 平滑动画

1. 问题现场transition 写在 CSS 变量上为什么瞬间跳变1.1 一段最典型的翻车代码先说我前几天遇到的事。当时我在调一个卡片 hover 效果想让背景色从蓝色平滑过渡到橙色很自然的写法是定义两个 CSS 变量再给transition加上去代码如下.card { --accent: #2563eb; background: var(--accent); transition: --accent 0.4s ease; } .card:hover { --accent: #f59e0b; }这段代码一眼看过去完全没毛病变量名没有拼错选择器优先级也没问题transition的时长、缓动函数都写了。但实际跑起来鼠标悬停的一瞬间背景色直接“啪”地换掉完全没有过渡动画。我把transition从--accent换成background-color再试动画立刻正常了。也就是说问题出在变量身上而不是 transition 身上。这个现象其实很多前端都踩过CSS 变量默认是不能被过渡的除非你给变量补上类型信息。这就是property要解决的问题。1.2 表面上是不生效根子是“没有类型”先别急着写代码我们得搞清楚一件事transition的工作原理到底是什么。transition的本质是浏览器在“开始值”和“结束值”之间做连续插值。比如宽度从100px变到200px浏览器要算出每一帧的中间值100px、110px、120px……然后一帧一帧画出来。要做到这一点浏览器必须先知道这个值是什么类型长度可以算差值颜色可以拆成 RGBA 四个通道分别插值角度可以按数字大小平滑增长。但一个没有注册过的 CSS 变量比如--accent: #2563eb在浏览器内部只是一段“原始字符流”。浏览器不知道它是一串颜色文本、一个长度、还是一个数字。既然不知道是什么类型就没有办法对它做插值运算transition写上去相当于白写——值变了就是变了只能瞬间切换。更细节一点说普通 CSS 属性都是有“语法定义”的。width接受length-percentagecolor接受coloropacity接受number浏览器解析这些属性时知道拿哪套规则去理解值。而--accent这种自定义属性在设计之初就是“任意值的容器”空格、逗号、括号、数字、颜色怎么写都行浏览器不做任何类型判断。这种灵活性确实好用但代价就是它无法参与动画计算。2. 原理拆解没有类型信息浏览器拿什么做插值2.1 自定义属性天然就是“无类型”的很多人对 CSS 变量有个误解觉得--accent: #2563eb这个值看上去是个颜色浏览器就应该认识它。但实际上浏览器只有在执行var(--accent)进行替换的时候才会去判断这个值放在当前属性里合不合法。举个例子.demo { --size: 16px; font-size: var(--size); }--size本身不声明自己是长度是font-size这个属性在拿到替换结果后发现16px符合自己的语法要求才把它当长度用。也就是说变量的“类型”不是它自己说了算而是每次被引用时由消费它的属性临时判断的。这种设计在普通的静态样式里没有任何问题但一到动画场景就露馅了。transition需要的是变量自身的计算值具备稳定的类型而不是等到最后替换时才去猜。对未注册的变量来说它的计算值始终是一串 token浏览器不认为它发生了变化或者更准确地说不认为这种变化是可插值的。2.2 transition 必须建立在“可插值”的类型之上我们再往深挖一步。CSS 的动画系统里每个属性都有自己的“动画类型”animation type。比如长度、百分比、数字这些是按计算值插值颜色是按颜色分量插值字符串、关键字、URL 这些是离散型只能瞬间切换不能平滑过渡而一个未注册的自定义属性它的动画类型就是“没有”——既不按数值也不按颜色什么都不是。这就能解释很多奇怪现象你给--accent写transition没用但如果你把变量注册成颜色类型transition立刻就能跑起来。因为浏览器终于知道这个变量的值可以从#2563eb的 RGB 通道平滑插值到#f59e0b的 RGB 通道了。顺带一提keyframes动画也是同一个道理。未注册的变量放进keyframes里同样不会有逐帧过渡效果只有注册过类型的变量才能配合动画使用。2.3 一个接地气的类比这个原理如果觉得抽象可以拿导航软件打比方。你给导航两个地址它才能规划路线让你看到小车沿着道路平滑移动。但如果你丢给它两张写着乱码的纸条它根本不知道这是门牌号还是经纬度只能放弃路线规划瞬间把你从 A 点传送到 B 点。property就是给变量补上那句关键说明“这是经纬度坐标请按坐标规划路线”或者“这是颜色值请按 RGBA 通道插值”。有了这张“类型身份证”浏览器才愿意帮你做中间每一帧的计算。3. 给变量补类型property 三条描述符一次讲透3.1 syntax、inherits、initial-value 三件套property是一个 CSS at-rule作用是把一个自定义属性正式“注册”成有类型的属性。它的核心语法长这样property --accent { syntax: color; inherits: true; initial-value: #2563eb; }三条描述符各有各的用处一个都不能少syntax声明变量值的类型。这里写color就表示这个变量只能存颜色。类型写错或者值不匹配变量会直接失效回退到初始值。inherits布尔值控制这个变量是否被子元素继承。true表示继承false表示不继承。这个值要按实际需求仔细设因为它影响的不只是动画还有整个样式继承链。initial-value变量的兜底值。当元素本身没有给这个变量赋值时就用这个值。它必须和syntax声明类型一致否则整条规则无效。Safari 对这个字段要求尤其严格漏写会直接导致注册失败。注意property只能注册自定义属性也就是以--开头的属性。你不能用它去把width、color这种普通属性重新注册一遍。另外CSS 里要用initial-value连字符写法如果走 JavaScript 的CSS.registerPropertyAPI参数则要写成驼峰形式的initialValue这个细节后面还会再说。3.2 常用的 syntax 类型清单syntax支持的值类型挺多我把常用的整理成一张表方便对照syntax 取值说明能否平滑过渡number数字如0.5、42可以integer整数如1、100可以length长度如10px、2em可以percentage百分比如50%可以length-percentage长度或百分比都行可以color颜色如#fff、rgb(0,0,0)可以angle角度如45deg、0.5turn可以time时间如0.3s、500ms可以custom-ident标识符如auto、ease不可以离散string字符串如hello不可以离散url资源地址不可以离散从表里能看出来凡是能参与数值或颜色运算的类型基本都可以拿来过渡字符串和标识符这类没法拆分的类型就只能瞬间切换。另外syntax还支持用|写组合类型比如color | image或者length | auto但组合越复杂过渡行为越依赖具体值的匹配情况能用单一类型解决就尽量别搞组合后面我会在坑位部分细说。3.3 注册之后浏览器到底发生了什么变化注册的行为变化可以分成三层理解。第一变量有了稳定的计算值类型。浏览器在解析样式时会按syntax里声明的类型去解析变量值解析成功后就以这个类型的内部表示来存储而不是当字符串存着。第二transition 和 animation 可以对它做插值了。因为计算值已经是可插值的类型浏览器在动画系统中能够计算出每一帧的中间值动画自然就跑起来了。第三变量有了“类型校验”副作用。如果赋值不符合 syntax比如syntax: number但给了10px这个变量会直接失效回退到initial-value或者继承值。这其实是个很好的防御机制能帮你提前发现类型不一致的 bug。4. 三个高频场景从按钮变色到渐变转圈直接抄4.1 场景一hover 时让颜色平滑过渡回到开头的卡片案例。正确的做法是先注册变量再在业务代码里使用property --accent { syntax: color; inherits: true; initial-value: #2563eb; } .card { --accent: #2563eb; background: var(--accent); transition: --accent 0.4s ease; } .card:hover { --accent: #f59e0b; }这里inherits: true是因为我可能希望.card的子元素也能读取到这个变量比如标题文字上也用color: var(--accent)。注册之后hover 时背景色就会从蓝色平滑滑到橙色。有一个细节值得注意property里的initial-value和.card里的--accent: #2563eb写的是同一个值。这不是重复而是双保险。initial-value保证了“即使没有显式赋值变量也始终有一个合法类型值”而.card里的赋值则是业务上的默认值。两者一致的话整个状态切换链路非常干净不会出现拿不到值的情况。4.2 场景二conic-gradient 角度动画渐变更丝滑第二个场景是我个人最喜欢的property玩法——给渐变背景做旋转动画。渐变本身是不能直接过渡的你没法让一个conic-gradient从 0 度平滑转到 360 度因为渐变图像在浏览器内部是不可插值的。但角度可以。property --angle { syntax: angle; inherits: false; initial-value: 0deg; } .loader { --angle: 0deg; background: conic-gradient(from var(--angle), #22d3ee, #a78bfa); transition: --angle 1s linear; } .loader:hover { --angle: 360deg; }这个做法的思路很巧妙渐变图像本身不动动的是它里面的from角度参数。因为--angle被注册成了angle类型浏览器知道怎么从0deg插值到360deg于是每一帧都会重新计算渐变背景视觉上就是一个平滑旋转的彩色圆环。这个技巧用来做 loading 动画、按钮光晕、边框流光都特别合适。同样的方案也适用于linear-gradient的角度以及transform: rotate()这类场景。只要把变量注册成angle然后让属性的值引用var(--angle)动画就能跑起来。4.3 场景三用百分比做进度条用数字做精细化控制再来看两个偏“工程化”的用法。第一个是进度条我想让进度条的宽度按百分比平滑变化同时希望这个百分比本身也能被 JS 动态控制。property --progress { syntax: percentage; inherits: false; initial-value: 0%; } .bar { --progress: 0%; width: var(--progress); transition: --progress 0.8s ease; } .bar.is-active { --progress: 100%; }注册成percentage之后transition会帮我们把宽度从当前的百分比平滑过渡到目标百分比。相比直接改width这种做法的好处是状态变更只需要改一个变量多个依赖这个变量的属性比如宽度、背景渐变位置可以同时联动代码更集中。第二个用法是number类型的变量。注册number后它可以被calc()引用也可以直接传给opacity、z-index这类接受数字的属性property --level { syntax: number; inherits: false; initial-value: 0; } .panel { --level: 0; opacity: var(--level); transform: scale(calc(1 var(--level) * 0.1)); transition: --level 0.3s ease; } .panel.is-open { --level: 1; }弹层打开时opacity从 0 渐变到 1transform也会从scale(1)平滑变到scale(1.1)。一个变量同时驱动两个属性的动画这在没有property的时代很难写得这么简洁。5. 兼容性现状与踩坑速查表5.1 兼容性现状与降级策略先说大家最关心的兼容性。property目前已经是现代浏览器的标配Chrome 和 Edge 从 85 版本开始支持Safari 从 16.4 开始支持Firefox 在 128 版本之后也默认支持了。也就是说现在的主流浏览器基本都能用不需要再像前几年那样担心大面积不支持的问题。那老浏览器怎么办实际上property的降级非常优雅——老浏览器遇到不认识的 at-rule会直接把整条规则忽略掉变量就退化成普通的未注册 CSS 变量。这时引用了var(--x)的属性依然正常显示只是没有动画过渡而已。换句话说最坏情况也就是损失动效不会导致页面样式崩坏。如果你的项目确实需要做特性检测可以用 JavaScript 判断if (typeof CSS.registerProperty function) { CSS.registerProperty({ name: --accent, syntax: color, inherits: true, initialValue: #2563eb }); }注意这里的参数名是驼峰格式initialValue不是 CSS 里的initial-value。另外CSS.registerProperty注册的规则和 CSS 里写property是等价的但只能在 JavaScript 运行时注册适合做更精细的条件控制。我的建议是能写在 CSS 里就写在 CSS 里语义清晰维护方便还能享受浏览器原生的优雅降级。5.2 常见问题速查表我把实际开发中容易踩的坑整理成一张速查表碰到类似症状直接对着查症状原因解决办法颜色/尺寸瞬间跳变没有过渡变量没注册或 syntax 类型与实际值不匹配补上property确认 syntax 正确变量突然不生效回退成初始值赋值的类型不符合 syntax比如number却给了10px检查赋值类型必要时在 DevTools 里看计算值Safari 中注册无效或变量异常缺少initial-value或inherits没写三件套syntax、inherits、initial-value都写上子元素读取不到变量inherits: false且子元素没有自己赋值确认继承需求改成true或子元素单独赋值写了transition: all但变量不过渡部分浏览器对all是否包含自定义属性的处理不一致不要依赖all显式写transition: --xxxkeyframes 里的变量不逐帧变化变量未注册动画系统无法插值同样先用property注册类型5.3 我的调试小技巧最后分享几个实操里很有用的调试习惯。第一注册变量后优先打开 DevTools 的 Computed 面板看这个变量显示的值。如果它显示成一段原始字符串说明注册没生效如果显示成解析后的颜色值或长度值说明注册成功并且值是合法的。比如--accent注册成color后Computed 面板里通常能看到一个格式化好的颜色值。第二syntax 的类型关键词必须全小写。Color、COLOR这种写法是无效的浏览器会忽略整条property规则。这个坑看起来低级但真的很容易犯尤其是从文档里复制的时候大小写被改掉。第三initial-value的写法要和 syntax 严格匹配。length就写0px别写0percentage就写0%color就写具体的颜色值不要写initial这种关键字。匹配不上时我见过很多情况是变量表现不稳定一会儿生效一会儿不生效排查起来非常费劲。第四如果你在写团队组件库建议把property集中放到一个公共的base.css或tokens.css里。因为这些注册规则是全局生效的分散写在各个组件里很容易出现重复注册或者命名冲突。统一放一处后续查看和维护都省心。我在实际项目中用过一段时间property之后最大的感受是它把 CSS 动画的边界又往外推了一大截。以前要实现渐变旋转、颜色联动这种效果要么上 JavaScript 去逐帧改样式要么用 Houdini 的 Paint API 写一堆代码。现在几行property加一个transition就搞定了而且性能是纯合成器级别的比 JS 逐帧操作要稳得多。如果你最近也被“transition 写在 CSS 变量上不生效”这个问题卡住照着上面的方法注册一下变量类型大概率立刻就能跑起来。