CSS 绘制 API

可用性有限

此功能不是基线功能，因为它在一些最广泛使用的浏览器中不起作用。

实验性： 这是一种 实验性技术
在生产环境中使用此功能之前，请仔细查看 浏览器兼容性表。

CSS 绘制 API（作为 CSS Houdini API 集的一部分）允许开发人员编写 JavaScript 函数，这些函数可以直接绘制到元素的背景、边框或内容中。

概念和用法

本质上，CSS 绘制 API 包含允许开发人员为 paint()（一个 CSS <image> 函数）创建自定义值的功能。然后，您可以将这些值应用于诸如 background-image 之类的属性，以在元素上设置复杂的自定义背景。

例如

css
aside {
  background-image: paint(myPaintedImage);
}

该 API 定义了一个 worklet，可用于以编程方式生成对计算样式更改做出响应的图像。要详细了解如何使用它，请参阅 使用 CSS 绘制 API。

接口

PaintWorkletGlobalScope

绘制工作区的全局执行上下文。

PaintRenderingContext2D

实现了 CanvasRenderingContext2D API 的一个子集。它有一个输出位图，其大小与其渲染到的对象的大小相同。

PaintSize

返回输出位图宽度和高度的只读值。

示例

以下示例创建了一个项目列表，其背景图像在三种不同的颜色和三种宽度之间旋转。在支持的浏览器中，您将看到类似于下图的图像。

The width and color of the background image changes based on the custom properties

为此，我们将定义两个自定义 CSS 属性，--boxColor 和 --widthSubtractor。

绘制工作区

在我们的工作区中，我们可以引用这些自定义属性。

js
registerPaint(
  "boxbg",
  class {
    static get contextOptions() {
      return { alpha: true };
    }

    /*
     use this function to retrieve any custom properties (or regular properties, such as 'height')
     defined for the element, return them in the specified array
  */
    static get inputProperties() {
      return ["--boxColor", "--widthSubtractor"];
    }

    paint(ctx, size, props) {
      /*
       ctx -> drawing context
       size -> paintSize: width and height
       props -> properties: get() method
    */

      ctx.fillStyle = props.get("--boxColor");
      ctx.fillRect(
        0,
        size.height / 3,
        size.width * 0.4 - props.get("--widthSubtractor"),
        size.height * 0.6,
      );
    }
  },
);

我们在 registerPaint() 类中使用了 inputProperties() 方法来获取应用了 boxbg 的元素上设置的两个自定义属性的值，然后在我们的 paint() 函数中使用这些值。inputProperties() 方法可以返回影响元素的所有属性，而不仅仅是自定义属性。

使用绘制工作区

HTML

html
<ul>
  <li>item 1</li>
  <li>item 2</li>
  <li>item 3</li>
  <li>item 4</li>
  <li>item 5</li>
  <li>item 6</li>
  <li>item 7</li>
  <li>item 8</li>
  <li>item 9</li>
  <li>item 10</li>
  <li>item 11</li>
  <li>item 12</li>
  <li>item 13</li>
  <li>item 14</li>
  <li>item 15</li>
  <li>item 16</li>
  <li>item 17</li>
  <li>item</li>
</ul>

CSS

在我们的 CSS 中，我们定义了 --boxColor 和 --widthSubtractor 自定义属性。

css
li {
  background-image: paint(boxbg);
  --boxColor: hsl(55 90% 60% / 100%);
}

li:nth-of-type(3n) {
  --boxColor: hsl(155 90% 60% / 100%);
  --widthSubtractor: 20;
}

li:nth-of-type(3n + 1) {
  --boxColor: hsl(255 90% 60% / 100%);
  --widthSubtractor: 40;
}

JavaScript

在我们的 <script> 中，我们注册了工作区

js
CSS.paintWorklet.addModule("boxbg.js");

结果

虽然您无法使用工作区的脚本，但您可以在 DevTools 中更改自定义属性值以更改背景图像的颜色和宽度。

规范

规范
CSS 绘制 API 级别 1
# paintworkletglobalscope

浏览器兼容性

BCD 表格仅在启用了 JavaScript 的浏览器中加载。

另请参阅