background-image: paint() 必须配合 css.paintworklet.addmodule() 动态加载同源 js 模块，且模块中需注册属性、声明 inputproperties 并实现纯函数式绘制逻辑，否则背景为空白。
background-image: paint() 必须配合 addModule() 才生效
直接在 CSS 里写 background-image: paint(gridPattern)，但没调用 CSS.paintWorklet.addModule()，背景一定为空白——浏览器不报错，也不渲染，DevTools 的 Rendering 面板里完全看不到绘制痕迹。这是最常踩的坑。
必须用 JS 动态加载一个独立的 worklet 文件，且满足三个硬性条件：
- 文件需同源，MIME 类型为
application/javascript - 不能访问
document、window或任何 DOM API -
addModule()是 Promise，得等它 resolve 后再注入含paint()的 CSS 规则，否则样式被忽略
示例正确加载方式：
if ('paintWorklet' in CSS) {
CSS.paintWorklet.addModule('./grid-painter.js')
.then(() => {
const style = document.createElement('style');
style.textContent = `
.grid-bg { background-image: paint(gridPattern); }
`;
document.head.appendChild(style);
});
}
paint() 函数里只能用 geometry 和 properties 做响应式计算
Grid 背景要随容器尺寸或主题色变化，不能靠 JS 定时重绘，也不能读 clientWidth 或监听 resize——worklet 环境里没有这些。
真正可用的输入只有三个参数：ctx（受限的绘图上下文）、geometry（当前绘制区域宽高，已适配 DPR）、properties（只读 CSS 自定义属性值）。你要做的就是把网格逻辑写成纯函数：
- 用
geometry.width和geometry.height算格子数量和间距，别硬编码20px - 用
properties.get('--grid-size')读取格子边长，前提是注册时已在inputProperties列表里声明过 - 用
properties.get('--grid-color')拿颜色值，返回的是CSSStyleValue，需调用.toString()转字符串再传给ctx.strokeStyle
错误写法：ctx.strokeStyle = 'var(--grid-color)' —— 不会解析变量，直接失效。
registerProperty() 是响应式更新的前提，不是可选项
如果 CSS 中写了 --grid-size: 16px，但在 worklet 注册时没声明 inputProperties: ['--grid-size']，那 properties.get('--grid-size') 永远返回 undefined，网格就画不出来。
注册代码必须包含这两部分：
registerProperty({
name: '--grid-size',
syntax: '<length>',
inherits: false,
initialValue: '16px'
});
registerPaint('gridPattern', class {
static get inputProperties() {
return ['--grid-size', '--grid-color'];
}
paint(ctx, geometry, properties) {
const size = parseFloat(properties.get('--grid-size').value);
const color = properties.get('--grid-color').toString();
// … 绘制逻辑
}
});</length>
注意：syntax 必须匹配实际值类型，写成 '<number>'</number> 却传 16px，解析失败；initialValue 不能缺，否则某些浏览器 fallback 行为不可控。
Grid 绘制必须轻量，避免 fillRect 循环生成密集线
Paint Worklet 运行在独立线程，但每帧绘制耗时超过几毫秒就会卡顿。常见错误是用 for 循环画几百条线：
// ❌ 危险：100x100 网格 = 20000 次 fillRect 调用 for (let x = 0; x <p>更优解是用 <code>strokeRect()</code> + <code>setLineDash()</code> 模拟虚线网格，或用单次 <code>fill()</code> 绘制路径再 stroke，大幅减少调用次数。Chrome 115+ 支持 <code>clip()</code>，可先 clip 出格子区域再批量绘制，但兼容性需查实。</p> <p>真正容易被忽略的点：<code>geometry</code> 是实时尺寸，但 <code>paint()</code> 可能被高频调用（比如滚动时），所有数学运算必须 O(1) 或 O(n) 且 n 极小。别在里头做 <code>Math.sin()</code>、<code>getComputedStyle()</code> 或任何非确定性操作。</p>
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
