CSS Houdini 到底能不能用？我把它的四个 API 全玩了一遍，给你一份实在的答案

CSS Houdini 到底能不能用？我把它的四个 API 全玩了一遍，给你一份实在的答案

CSS Houdini 这个名字太唬人了。第一次听说的时候，什么”直接操作浏览器渲染引擎”、”自定义 CSS 属性”、”让开发者拥有浏览器的能力”——听着像是前端界的魔法学院。

但真敢往项目里上的人，不多。

我这几个月把 Houdini 的四组主要 API 全试了一遍，Paint、Properties & Values、Typed OM、Layout，还顺手测了它们的浏览器兼容性和实际性能。今天就给你说人话聊聊：这东西到底能干什么、现在能不能用、踩了哪些坑。

先说结论：别把 Houdini 当成一个东西来问

Houdini 不是一个大功能，而是一组浏览器底层 API 的统称。你真正该问的是：我想用的到底是哪一类。

目前比较成熟、能落地的，一个是 @property（Properties & Values API），一个是 Paint API。其他像 Layout API 和 Animation Worklet 还太早，生产环境站不住。

下面我一个个拆开说。

1. @property：让 CSS 变量真正”有类型”

先看个场景。

你写了一个进度条组件，想用 CSS 变量控制进度值：

.bar {
  --progress: 50%;
  width: var(--progress);
  background: skyblue;
  transition: width 0.3s;
}

然后你通过 JS 更新 --progress，发现 transition 动画并没有生效。为什么？

因为浏览器不知道 --progress 到底是什么类型。对它来说，这只是一个字符串，它没法对”未知类型”的值做插值动画。

@property 就是解决这个问题的：

@property --progress {
  syntax: '<percentage>';
  inherits: false;
  initial-value: 0%;
}

加了这个声明之后，浏览器就知道了：哦，这个值是百分比类型。于是你再更新 --progress 时，transition 动画就丝滑跑起来了。

除了百分比，它还支持 、、、 这些类型。这意味着你可以让渐变动画变得极其简单：

@property --angle {
  syntax: '<angle>';
  inherits: false;
  initial-value: 0deg;
}

.box {
  --angle: 0deg;
  background: linear-gradient(var(--angle), red, blue);
  transition: --angle 1s;
}

.box:hover {
  --angle: 180deg;
}

这段代码在普通 CSS 里是做不到的——渐变的角度没法直接用 CSS 过渡。但 @property 注册了 --angle 为角度类型后，浏览器就会自动帮你完成插值。

Chrome 85+（2020 年 8 月）、Firefox 128+（2024 年 7 月）、Safari 15.4+（2022 年 3 月）。覆盖率很不错了，尤其是 Chrome 系。

有几个点要注意：

• @property 必须写在 CSS 文件顶层，不能嵌套在 @media 或选择器里
• 自定义属性的 syntax 不支持 这类组合类型——如果你既想传 px 又想传 %，得写两个属性
• inherits: false 记得显式指定，默认值每个浏览器处理不一致

2. Paint API：用 JS 画 CSS 背景

这是 Houdini 里最”酷”的 API。你能写一个 JavaScript 函数，然后在 CSS 里像调用函数一样用它画背景、边框、遮罩。

先注册一个 Paint Worklet：

// checkerboard.js
registerPaint('checkerboard', class {
  paint(ctx, size) {
    const colors = ['#f00', '#00f'];
    const size = 20;
    for (let x = 0; x < size.width; x += size) {
      for (let y = 0; y < size.height; y += size) {
        ctx.fillStyle = colors[(x + y) / size % 2];
        ctx.fillRect(x, y, size, y + size);
      }
    }
  }
});

然后在页面中加载 Worklet：

CSS.paintWorklet.addModule('checkerboard.js');

最后在 CSS 中使用：

.board {
  background-image: paint(checkerboard);
  width: 200px;
  height: 200px;
}

Worklet 的 inputProperties 可以接收 CSS 自定义属性，让图案动态变化：

registerPaint('smooth-corners', class {
  static get inputProperties() { return ['--smooth-level']; }
  paint(ctx, size, properties) {
    const level = parseFloat(properties.get('--smooth-level')) || 4;
    // 绘制超椭圆圆角...
  }
});

CSS 里你这样用：

.card {
  --smooth-level: 4;
  mask-image: paint(smooth-corners);
}

鼠标悬停时改变 --smooth-level，圆角的曲率就会平滑变化——纯 CSS 动画，JS 不参与每一帧。

• 自定义背景纹理：条纹、圆点、网格、波形
• 动态边框：加载动画、渐变边框
• 自定义圆角：谷歌 Material 按钮的水波纹、超椭圆圆角

> 举个真实的官方例子：百度首页的彩蛋背景，就用了 Paint API 来做粒子动画背景，比 Canvas 方案性能更好，因为渲染在合成线程中进行。

Paint API 目前在 Chrome 系（Edge、Opera、Android WebView）上已经支持，但 Safari 和 Firefox 还不支持。

这意味着你只能用渐进增强的方式去用：

.card {
  border-radius: 12px;
  /* 优雅降级 */
}

@supports (background-image: paint(smooth-corners)) {
  .card {
    border-radius: 0;
    mask-image: paint(smooth-corners);
  }
}

用 @supports 兜底，不支持的浏览器回退到常规圆角，支持的浏览器解锁更高级的效果。

3. Typed OM：摆脱字符串拼接

如果你写过这样的代码，一定是笑着哭的：

el.style.width = '200px';
el.style.transform = 'translateX(100px)';

每个值都是字符串，加减乘除全靠手拼。Typed OM 解决了这个问题——它为 CSS 值提供了类型化的 JS API：

// 传统方式
el.style.width = '200px';

// Typed OM
el.attributeStyleMap.set('width', CSS.px(200));
el.attributeStyleMap.set('transform', CSS.translate(CSS.px(100), 0));

这样你就能对值做数学运算了：

const width = el.attributeStyleMap.get('width');
const newWidth = width.value + 50;
el.attributeStyleMap.set('width', CSS.px(newWidth));

性能也有提升，因为 Typed OM 获取值的时候不需要重新计算和序列化——对频繁读写的场景（比如动画循环）来说，能省不少时间。

我写了个测试，在 60fps 的动画循环里反复读写元素的 left 和 top：

差距还是挺明显的。如果你的页面有大量 JS 驱动 CSS 动画的场景（比如拖拽、滚动驱动的 Canvas 交互），Typed OM 值得用。

不过目前 Typed OM 的 API 设计对新手不太友好，CSS.px()、CSS.percent() 这类工厂函数需要学一下。而且 Firefox 对它支持不够全，生产环境需要 polyfill。

4. Layout API：能自定义 display 属性？（现在别碰）

Layout API 允许你写一个自定义布局算法，然后用 display: layout(myLayout) 来使用。

理论上你可以实现瀑布流布局、环形布局、甚至是完全自定义的排版方式。

但现实是：目前只有 Chrome 支持，而且需要开启实验特性。Safari 和 Firefox 根本不在 road map 上。

所以这个 API 短期内在生产环境中不可用。如果你真的很想玩瀑布流，还是老老实实用 CSS Grid + JS 计算吧。

总结一下：哪些 Houdini API 现在能用

我的建议是：

1. @property 可以直接上。它没有兼容性风险（覆盖率足够了），而且解决的是很实际的动画和过渡问题。你项目里如果有 CSS 变量驱动的动画效果，加上 @property 几乎是零成本提升体验。 2. Paint API 当成”锦上添花”。用它做视觉效果、装饰性元素，用 @supports 兜底。不要让它成为功能依赖。 3. Typed OM 适合有性能要求的场景。比如游戏 UI、实时数据仪表盘。一般业务项目可以用但不急。 4. Layout API 再等两年看看。

前端技术就是这样。有的东西你看着很酷，但它确实还没到全面落地的时候。Houdini 给我的感觉是——它不是一个让你”非用不可”的东西，但如果你理解了它的原理，你写 CSS 的时候思维就不一样了。

你知道浏览器底层到底怎么运作，知道哪些地方其实可以”插一脚”。这种理解力，比那些花哨的 demo 值钱得多。