CSS Houdini 能突破传统布局限制，但需选对 API、运行于支持环境（Chrome/Edge ≥128）、避开主线程陷阱；Layout API 可实现瀑布流等原生不支持的布局，Paint API 适用于动态背景生成，二者均依赖 @property 声明自定义属性且不支持 DOM 操作。
CSS Houdini 不是“让 CSS 更好用”的增强包，而是把浏览器渲染流水线的控制权部分交还给开发者。它真能突破传统布局限制，但前提是选对 API、跑在支持环境、避开主线程陷阱。
Layout API 能写瀑布流，但 Chrome 128+ 才稳定启用
Layout API 是唯一能真正接管元素排版逻辑的接口，比如实现原生不支持的 Masonry 布局或环形排列。但它不是 `display: masonry` 一键开关，而是一套需注册、加载、声明、调用的完整链路：
- 必须通过
CSS.layoutWorklet.addModule()加载 JS 模块，且该模块只能在安全上下文（HTTPS 或 localhost）中执行 - 自定义 layout class 必须实现
layout()方法，接收children、constraintSpace和styleMap，不能访问 DOM 或调用getComputedStyle() - 使用时需声明
display: layout(my-masonry)，且父容器必须设container-type: inline-size（否则 layout worklet 不触发） - 当前仅 Chromium 系列（Chrome ≥128、Edge ≥128）默认启用；Firefox 和 Safari 仍标记为“实验性”，需手动开启 flag 或完全不可用
常见错误：直接在 layout() 函数里写 document.querySelector() —— 这会报 ReferenceError: document is not defined，因为 layout worklet 运行在隔离的渲染线程，没有 DOM 全局对象。
Paint API 替换背景图最实用，但参数传递有隐式规则
Paint API 是目前落地最成熟、兼容性最好的 Houdini 模块（Chrome/Edge 已稳定，Firefox 部分支持）。它不改布局，但能用 JS 动态生成背景、边框甚至遮罩层，绕过图片资源和 SVG 的体积与维护成本：
-
registerPaint()注册的类，其paint()方法第三个参数properties只能读取通过CSS.registerProperty()显式声明过的自定义属性 - 未注册的
--foo在properties.get('--foo')中返回undefined，不会 fallback 到 computed value -
size参数是当前元素的 content box 尺寸（不含 padding/border），不是 clientWidth/clientHeight - 支持传入
CSSUnitValue、CSSKeywordValue等 Typed OM 类型，但若传字符串（如'10px'），需手动 parse，否则绘图坐标会错乱
示例场景：一个响应式波纹背景，随容器宽度自动缩放频率：.ripple { --ripple-scale: 1; background: paint(ripple); }，worklet 内用 properties.get('--ripple-scale').value 获取数值，再乘以 size.width 控制波纹密度——这里漏掉 .value 就会画出一片黑。
@property 声明自定义属性是 Paint/Layout 协同的前提
@property（或 CSS.registerProperty()）不是可选配件，而是 Paint API 和 Layout API 之间参数通信的契约：
-
syntax字段必须精确匹配，比如写成'<length-percentage>'，就不能传'red'，否则properties.get()返回null -
inherits: true时，子元素 worklet 才能读取到继承值；若布局算法依赖层级关系（如树形展开），这点极易被忽略 -
initialValue在 worklet 初始化阶段就生效，但若 CSS 中未显式设置该变量，properties.get()仍返回initialValue，不是空字符串或 undefined - 动画过渡只对注册过的属性生效：
transition: --my-angle 0.3s有效，transition: --unregistered 0.3s完全无效，且无任何 warning
容易踩的坑：在 CSS 中写了 --item-gap: 12px，却没用 @property 声明，结果 layout worklet 里 properties.get('--item-gap') 拿不到值，所有间距坍缩为 0——这种 bug 不报错，只静默失效。
立即学习“前端免费学习笔记（深入）”；
Worklet 加载失败时，CSS 回退行为极难调试
CSS.paintWorklet.addModule() 和 CSS.layoutWorklet.addModule() 是 Promise，但失败时既不抛异常，也不触发 CSS 的 background: none 回退，而是让对应样式规则彻底“消失”：
- 模块 404 或语法错误 → 对应
paint(x)或layout(x)声明被浏览器忽略，元素按默认 display 渲染（如 block），而非降级为background: transparent - 本地开发用 file:// 协议 → worklet 加载直接被拒绝，Chrome 控制台只显示
Failed to load module，无堆栈、无行号 - 模块内引用了未 polyfill 的 API（如
ResizeObserver）→ worklet 启动失败，但主页面 JS 完全感知不到
实操建议：始终在模块入口加 console.log('paint worklet loaded')，并在 CSS 中配一条兜底规则，例如 .card { background: #f5f5f5; background: paint(card-bg); }，确保 worklet 失效时视觉不崩。
Houdini 的能力边界很清晰：它不解决“怎么设计 UI”，而是解决“浏览器不允许你这么干”时的硬性卡点。真正麻烦的从来不是写 layout class，而是判断某个布局需求是否值得引入 worklet——毕竟多一层构建、多一重兼容性检查、多一个调试维度。
