paint worklet 必须通过 css.paintworklet.addmodule() 加载脚本才能生效，registerpaint() 单独执行会被忽略；需在 css 应用前完成异步加载，并在 inputproperties 中声明监听的自定义属性以响应变化。
Paint Worklet 为什么不能直接用 registerPaint 就生效
浏览器会直接忽略未启用 paintWorklet 的注册调用，哪怕代码没报错。根本原因是它属于「模块化能力」，必须显式加载到 document.paintWorklet 才能被 CSS 引用。常见错误是把 registerPaint 放在普通 JS 脚本里执行，但没走 addModule 流程——这时候 CSS 里的 paint(myPattern) 会被静默降级为透明背景。
正确做法是：
- 单独建一个
pattern-worklet.js文件，只写registerPaint和类定义，不引入任何外部依赖（ESM import 不被支持） - 主页面中用
document.paintWorklet.addModule('pattern-worklet.js')加载，且必须在设置 CSS 前完成 - 加载是异步的，需确保样式应用时机，比如在
addModule().then(...)里操作style或 class
如何让 paint() 函数响应元素尺寸与自定义属性变化
CSS Paint API 不自动监听元素宽高或自定义属性变动，paint(ctx, geom, props) 中的 geom.width/height 是当前绘制区域尺寸，但若容器 resize 后未触发重绘，就会卡在旧尺寸。同时，props.get('--my-color') 只读取初始值，后续 CSS 变量更新不会自动触发重绘。
解决方式很务实：
- 在
inputProperties静态字段中显式声明要监听的 CSS 变量，例如static get inputProperties() { return ['--cell-size', '--fg']; } - 使用
ctx.canvas.width/height而非缓存的geom值，因为 canvas 会随geom自动重置尺寸，但需注意：每次paint()调用都是全新 canvas，无需手动 clear - 避免在
paint()中做复杂计算或创建对象，高频调用下 GC 压力大；纹理逻辑尽量用整数运算 + 位操作，比如((x ^ y) & 1) * 255生成棋盘格
ctx 绘图上下文和 Canvas2D 的关键差异
Paint Worklet 的 ctx 并非完整 Canvas2D 实例：它删减了大量方法（如 getImageData、createPattern、setTransform），也不支持 canvas.toDataURL()。最易踩坑的是 ctx.fillStyle 接收 CSS 颜色字符串的能力有限——不支持 hsl()、color(display-p3 ...)，甚至部分十六进制简写（如 #abc）可能解析失败。
安全做法是：
- 用
props.get('--color').toString()获取变量后，优先转成rgb(r,g,b)格式再赋给fillStyle - 避免
ctx.font和文本测量，Paint Worklet 对字体回退、子像素渲染等支持不稳定 - 需要抗锯齿时，别依赖
ctx.imageSmoothingEnabled（无效），改用双线性采样逻辑在 JS 中预计算像素值 - 若需复杂图形，用
ctx.beginPath()+lineTo()+fill()是最稳路径，clip()可用但慎嵌套
调试 Paint Worklet 的真实错误信息从哪来
Paint Worklet 错误不会出现在主页面 console，而是藏在 DevTools 的「Rendering」面板 → 勾选「Paint flashing」后看闪烁异常，或更直接：打开 chrome://inspect → 点击「Configure...」→ 添加 localhost 端口 → 在「Remote Target」里找到 worklet 类型页签。这里能看到 registerPaint 语法错误、paint() 中的 throw、甚至内存超限的 RangeError。
几个硬核提示：
- 修改 worklet 文件后必须硬刷新页面（Ctrl+F5），DevTools 不会自动 reload worklet
-
console.log在 worklet 中有效，但输出在 worklet 专用控制台，不在页面 console - 若
paint()执行超过 16ms，Chrome 会强制中断并显示「Synchronous paint took too long」警告，此时得拆分逻辑或用requestIdleCallback（但注意：worklet 环境无该 API，只能精简算法）
真正难的不是写出第一个 paint()，而是让纹理在 60fps 下稳定复用——每个像素的计算都得落在 0.2ms 内，否则滚动时就掉帧。这要求你放弃通用抽象，直奔位运算和查表法。
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
