为何基于@property的CSS变量动画在Web Components中无法正常生效

这不是你Web Component的实现有问题，是Chromium系浏览器当前版本的已知bug。

@property的设计规范要求自定义属性注册和所在样式表的作用域绑定，写在Shadow DOM内部样式里的@property理应只在当前shadow树内生效，但现在Chrome、Edge、Opera的实现没有正确处理这个逻辑：只有主文档解析到的@property规则才会被完整注册、识别为可动画的类型属性，Shadow DOM内部写的@property规则不会被正确挂载到对应作用域，直接表现就是属性值跳变没有过渡动画、初始动画状态不生效，必须手动触发一次样式更新（比如拖动滑块改值、在:host上显式写属性默认值）才会临时生效。你把样式复制到主DOM后动画正常，就是因为这时候@property被主文档解析完成注册了。

临时绕开方案 #

两种写法都可以解决问题：

• 方案一：把所有@property规则从组件的shadow内部样式移到全局样式表里注册。全局注册完的自定义属性，在Shadow DOM内部使用、修改、做动画都不会有问题，缺点是自定义属性会变成全局可用，可能存在命名冲突风险，命名时加组件专属前缀即可规避。
• 方案二：不用CSS写法的@property，在组件初始化时用JS原生API CSS.registerProperty 注册自定义属性，示例代码放在组件constructor里即可：

// 注册工具函数，避免重复注册抛错
const registerCssProp = (name, syntax, initialValue, inherits = false) => {
  if (!window.CSS?.registerProperty) return;
  try {
    CSS.registerProperty({ name, syntax, initialValue, inherits });
  } catch (err) { /* 已注册过的属性直接跳过 */ }
};

// 注册需要动画的三个自定义属性
registerCssProp('--web-component-background-color', '<color>', '#00ff00');
registerCssProp('--web-component-rotate', '<angle>', '0deg');
registerCssProp('--web-component-scale', '<number>', '1');

这种方式不需要额外给:host加默认值，组件加载完动画就能直接正常运行，属性修改的过渡效果也和普通DOM场景下表现一致。

补充说明 #

@property目前仍处于实验阶段，除了Chromium系浏览器外，Firefox、Safari的正式版本还没有默认支持该特性，生产环境使用需要做好不支持场景下的样式降级。上述Shadow DOM兼容问题已经被提交到Chromium官方问题库，后续版本会修复，不需要永久保留兼容代码。

内容的提问来源于stack exchange，提问作者Marcello di Simone