API живописи CSS

API живописи CSS — часть набора API CSS Houdini — позволяет разработчикам писать функции JavaScript, которые могут рисовать непосредственно в фоновом изображении, границе или содержимом элемента.

По существу, API живописи CSS содержит функциональность, позволяющую разработчикам создавать пользовательские значения для paint(), функции CSS <image>. Затем вы можете применять эти значения к свойствам, таким как background-image, чтобы установить сложные пользовательские фоны на элементе.

Например:

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

API определяет worklet, который можно использовать для программирования генерации изображения, реагирующего на изменения вычисленного стиля. Чтобы узнать больше о том, как это используется, обратитесь к Использованию API живописи CSS.

PaintWorkletGlobalScope

Глобальный контекст выполнения модуля живописи.

PaintRenderingContext2D

Реализует подмножество API CanvasRenderingContext2D. Он имеет выходной растровый бит, размер которого соответствует объекту, в который он рендерится.

PaintSize

Возвращает только для чтения значения ширины и высоты выходного растрового бита.

Следующий пример создает список элементов с фоновым изображением, которое вращается между тремя различными цветами и тремя ширинами. В поддерживающем браузере вы увидите что-то вроде изображения ниже.

Для этого мы определим две пользовательские свойства CSS, --boxColor и --widthSubtractor.

Модуль — это внешний файл JavaScript (в данном случае мы назвали его boxbg.js), который определяет модуль живописи worklet. Используя модуль, мы можем получить доступ к свойствам CSS (и пользовательским свойствам) элементов:

registerPaint(
  "boxbg",
  class {
    static get contextOptions() {
      return { alpha: true };
    }
    /*
      Retrieve any custom properties (or regular properties,
      such as 'height') defined for the element, and return
      them as an 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,
      );
    }
  },
);

Мы использовали метод inputProperties() в классе registerPaint() для получения значений двух пользовательских свойств, установленных на элементе, которому применено boxbg, и затем использовали эти значения в нашей функции paint(). Метод inputProperties() может вернуть все свойства, влияющие на элемент, а не только пользовательские свойства.

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 N</li>
</ul>

CSS

В нашем CSS мы определяем пользовательские свойства --boxColor и --widthSubtractor.

body {
  font: 1.2em / 1.2 sans-serif;
}
li {
  background-image: paint(boxbg);
  --boxColor: hsl(55 90% 60%);
}

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

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

JavaScript

Настройка и логика модуля живописи находятся во внешнем скрипте. Для регистрации модуля нам нужно вызвать addModule() из нашего основного скрипта:

CSS.paintWorklet.addModule(
  "https://mdn.github.io/houdini-examples/cssPaint/intro/worklets/boxbg.js",
);

В этом примере модуль размещается по адресу https://mdn.github.io/, но ваш модуль может быть относительным ресурсом, как показано ниже:

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

Результат

Хотя вы не можете взаимодействовать со скриптом модуля, вы можете изменять значения пользовательских свойств в DevTools для изменения цветов и ширины фонового изображения.

• Использование API живописи CSS
• API типизированной объектной модели CSS
• API Houdini