CSS Houdini 的 registerProperty 不提供真正类型保护，syntax 仅影响动画解析，无法阻止非法值赋值或实现静态/运行时类型检查，类型安全需 JS 封装或构建工具链保障。
CSS Houdini 的自定义属性（CSS Custom Properties）本身不支持类型保护，所谓“受类型保护的变量”在原生 CSS 中并不存在；Houdini 的 registerProperty API 仅提供有限的解析提示（如 syntax），无法实现运行时类型检查或 TypeScript 式的静态保障。
为什么 registerProperty 看起来像有类型，其实没有
你可能会看到类似这样的代码：
CSS.registerProperty({
name: '--my-length',
syntax: '<length>',
inherits: false,
initialValue: '0px'
});
这里 syntax: '<length>' 只影响浏览器是否接受该值用于动画或 transition，并不阻止传入 'red' 或 '12' —— 浏览器会静默忽略非法值，且不会报错。它不是类型系统，也不参与构建时校验。
-
syntax值仅用于启用部分 Houdini 特性（如属性动画、@property动画插值），对 CSSOM 读写、JavaScript 赋值完全无约束 - JavaScript 中通过
element.style.setProperty('--my-length', 'invalid')依然成功，只是后续计算值为unset或 fallback - 没有类型定义能被 TypeScript 捕获，
getComputedStyle(el).getPropertyValue('--my-length')返回的永远是string
真正能落地的“类型保护”只能靠 JS 层封装
如果你需要确保 --my-length 总是合法长度值，必须在 JavaScript 中拦截赋值逻辑：
立即学习“前端免费学习笔记（深入）”；
class TypedCSSProperty {
constructor(name, syntax = '<length>') {
this.name = name;
this.syntax = syntax;
}
set(el, value) {
if (!this.isValid(value)) {
throw new TypeError(`Invalid value for ${this.name}: ${value}`);
}
el.style.setProperty(this.name, value);
}
isValid(value) {
const temp = document.createElement('div');
temp.style.cssText = `${this.name}: ${value}`;
return getComputedStyle(temp).getPropertyValue(this.name) !== '';
}
}
- 这个验证是启发式的：依赖浏览器实际解析结果，不能覆盖所有边缘 case（如单位别名、calc 表达式嵌套）
- 不要在循环或高频渲染中调用
isValid()，性能开销明显 - 若搭配 TypeScript，可加一层泛型约束（如
TypedCSSProperty<'length'>），但仍是运行时 + 开发者约定，非强制类型系统
和 PostCSS / CSS-in-JS 工具链配合更现实
想获得接近“类型安全”的体验，与其硬啃 Houdini 的语法提示，不如换到工具链层面：
- 用
postcss-custom-properties+ 自定义 lint 规则，在构建时校验--foo: 42是否符合预设类型（需提前声明--foo应为<angle>） - 在 CSS-in-JS 库（如 Linaria、Vanilla Extract）中，把变量定义为 TS 类型对象：
const vars = { size: px(16), color: '#fff' } as const，再生成对应--size属性 - VS Code 插件（如
css-var-autocomplete）可基于@property声明提供补全，但不防错
记住：Houdini 的 registerProperty 是为浏览器渲染管线服务的，不是为开发者类型系统设计的。任何“类型保护”都得自己在 JS 层兜底，或交给构建工具处理——浏览器不会替你拦住一个错写的 '2rempx'。
