CSS Houdini 自定义属性：从 Paint Worklet 到属性动画的底层扩展

一、CSS 的扩展瓶颈：为什么"等规范"不是工程选项

CSS 的演进速度远慢于前端框架。一个 CSS 特性从提案到浏览器全面支持通常需要 3-5 年。当工程需求超出 CSS 现有能力时——如自定义的绘制效果、类型化的自定义属性、基于布局的动画——开发者只能通过 JavaScript 或预处理器绕过，但这些方案要么性能差（JS 操作 DOM），要么无法运行时动态调整（预处理器编译时生成）。

CSS Houdini 是 W3C 的底层扩展机制，允许开发者通过 JavaScript 定义 CSS 的解析、布局和绘制行为，并将这些自定义行为注册为原生 CSS 属性。这意味着开发者不再需要"等规范"，可以自行扩展 CSS 的能力边界。

二、Houdini API 体系：从属性注册到自定义绘制

flowchart TD
    A[CSS Houdini API] --> B[Properties & Values API<br/>类型化自定义属性]
    A --> C[Paint API<br/>自定义绘制]
    A --> D[Layout API<br/>自定义布局]
    A --> E[AnimationWorklet<br/>高性能动画]
    A --> F[Typed OM<br/>类型化对象模型]

    B --> G[CSS.registerProperty<br/>定义属性类型与初始值]
    C --> H[registerPaint<br/>Canvas 2D 绘制]
    D --> I[registerLayout<br/>自定义布局算法]
    E --> J[registerAnimator<br/>Worklet 线程动画]
    F --> K[CSS.number() / CSS.px()<br/>类型安全的样式操作]

Properties & Values API 是 Houdini 的基础，它允许注册类型化的自定义属性，使浏览器能够正确解析、插值和继承这些属性。Paint API 允许在元素的绘制阶段通过 Canvas 2D API 自定义渲染效果。AnimationWorklet 将动画计算移到独立线程，避免主线程阻塞。

三、工程实现：类型化属性、自定义绘制与高性能动画

3.1 类型化自定义属性

// 注册类型化自定义属性
CSS.registerProperty({
  name: '--ripple-radius',
  syntax: '<length>',
  initialValue: '0px',
  inherits: false,
});

CSS.registerProperty({
  name: '--gradient-angle',
  syntax: '<angle>',
  initialValue: '0deg',
  inherits: false,
});

CSS.registerProperty({
  name: '--highlight-color',
  syntax: '<color>',
  initialValue: '#0066ff',
  inherits: true,
});

// 注册后，浏览器可以自动插值这些属性
// 这意味着它们可以用于 transition 和 animation
.ripple-button {
  --ripple-radius: 0px;
  transition: --ripple-radius 0.6s ease-out;
}

.ripple-button:active {
  --ripple-radius: 200px;
}

3.2 Paint Worklet 自定义绘制

// ripple-paint.js — Paint Worklet 文件
class RipplePainter {
  // 声明依赖的输入属性
  static get inputProperties() {
    return ['--ripple-radius', '--ripple-color', '--ripple-x', '--ripple-y'];
  }

  paint(ctx, size, properties) {
    const radius = properties.get('--ripple-radius').value;
    const color = properties.get('--ripple-color').toString();
    const x = properties.get('--ripple-x').value || size.width / 2;
    const y = properties.get('--ripple-y').value || size.height / 2;

    // 清除之前的绘制
    ctx.clearRect(0, 0, size.width, size.height);

    if (radius <= 0) return;

    // 绘制涟漪效果
    const gradient = ctx.createRadialGradient(x, y, 0, x, y, radius);
    gradient.addColorStop(0, color);
    gradient.addColorStop(1, 'transparent');

    ctx.fillStyle = gradient;
    ctx.beginPath();
    ctx.arc(x, y, radius, 0, Math.PI * 2);
    ctx.fill();
  }
}

// 注册 Paint Worklet
registerPaint('ripple', RipplePainter);

<!-- 使用自定义绘制 -->
<script>
  // 加载 Paint Worklet（必须在单独的 JS 文件中）
  CSS.paintWorklet.addModule('/worklets/ripple-paint.js');
</script>

<style>
  .ripple-button {
    --ripple-radius: 0px;
    --ripple-color: rgba(0, 102, 255, 0.3);
    --ripple-x: 50%;
    --ripple-y: 50%;
    background: paint(ripple);
    transition: --ripple-radius 0.6s ease-out;
  }

  .ripple-button:active {
    --ripple-radius: 200px;
  }
</style>

3.3 AnimationWorklet 高性能动画

// spring-animator.js — AnimationWorklet 文件
class SpringAnimator {
  constructor() {
    this.stiffness = 100;
    this.damping = 10;
    this.mass = 1;
    this.velocity = 0;
    this.position = 0;
  }

  // 声明可动画的输入
  static get inputProperties() {
    return ['--spring-stiffness', '--spring-damping'];
  }

  animate(currentTime, effect) {
    const target = effect.localTime;
    const dt = 1 / 60; // 假设 60fps

    // 弹簧物理模拟
    const displacement = this.position - target;
    const springForce = -this.stiffness * displacement;
    const dampingForce = -this.damping * this.velocity;
    const acceleration = (springForce + dampingForce) / this.mass;

    this.velocity += acceleration * dt;
    this.position += this.velocity * dt;

    // 判断是否收敛
    if (Math.abs(displacement) < 0.01
        && Math.abs(this.velocity) < 0.01) {
      this.position = target;
      this.velocity = 0;
    }

    return this.position;
  }
}

registerAnimator('spring', SpringAnimator);

// 主线程中使用 AnimationWorklet
await CSS.animationWorklet.addModule('/worklets/spring-animator.js');

const element = document.querySelector('.spring-element');
const animation = new WorkletAnimation(
  'spring',
  new KeyframeEffect(
    element,
    [
      { transform: 'translateY(0px)' },
      { transform: 'translateY(-100px)' },
    ],
    { duration: 1000 }
  ),
  document.timeline
);

animation.play();

四、Houdini 的兼容性陷阱与性能边界

浏览器支持的碎片化：Paint API 在 Chrome 65+ 和 Edge 79+ 中支持，但 Safari 直到 15.4 才部分支持，Firefox 仍在实验阶段。AnimationWorklet 仅在 Chrome 和 Edge 中支持。生产环境使用 Houdini 需要完善的降级方案——检测 API 可用性，不支持时回退到 CSS 或 JS 实现。

Paint Worklet 的执行限制：Paint Worklet 运行在独立的 Worklet 线程中，无法访问 DOM、网络和大部分 Web API。这意味着 Paint Worklet 不能加载图片（除非通过 inputArguments 传入），不能发起网络请求，也不能读取 DOM 属性。这些限制确保了安全性，但也约束了绘制能力。

类型化属性的注册时机：CSS.registerProperty 必须在样式表解析之前调用，否则已使用该属性的样式声明可能被忽略。在实践中，注册代码需要放在 <head> 中的 <script> 标签内，且不能使用 defer 或 async 属性。

AnimationWorklet 的调试困难：Worklet 运行在独立线程中，无法使用 console.log 或断点调试。调试 AnimationWorklet 需要将逻辑移到主线程验证，确认无误后再迁移到 Worklet。这增加了开发和维护成本。

五、总结

CSS Houdini 的核心价值在于"将 CSS 的扩展权交给开发者"——通过类型化属性、自定义绘制和 Worklet 动画，突破 CSS 规范的演进速度限制。本文方案的核心模式为：registerProperty 定义类型化属性 → registerPaint 自定义绘制 → AnimationWorklet 高性能动画。落地时需重点关注三个原则：渐进增强（检测 API 可用性，不支持时降级）、性能优先（Paint Worklet 适合轻量绘制，复杂场景仍需 Canvas）、调试友好（Worklet 逻辑先在主线程验证）。建议从类型化自定义属性开始使用（兼容性最好），逐步引入 Paint API 和 AnimationWorklet。