HTML | Элемент canvas

Данная публикация является переводом на русский язык официальной версии стандарта HTML, расположенного по адресу https://html.spec.whatwg.org/multipage/canvas.html#the-canvas-element

На 02.01.2022 раздел называется «4.12.5 The canvas element»

Категории:

• Поточное содержание.
• Фразовое содержание.
• Встроенное содержание.
• Ощутимое содержание.

Контексты, в которых можно использовать этот элемент:

• Где ожидается встроенное содержание.

Модель контента:

• Прозрачный, но без интерактивных потомков содержимого, за исключением элементов ссылок a, элементов изображений img с атрибутами usemap, элементов кнопок button, элементов ввода input, атрибут type которых находится в состояниях Checkbox или Radio Button, элементами ввода input, которые являются кнопками, и элементами выбора select с несколькими атрибутами или размер дисплея больше чем 1.

Пропуск тега в text/html:

• Ни один из тегов не может быть пропущен.

Атрибуты контента:

• Глобальные атрибуты
• width — Горизонтальный размер
• height — Вертикальный размер

Соображения доступности:

• Для авторов.
• Для разработчиков.

Интерфейс DOM:

typedef (CanvasRenderingContext2D or ImageBitmapRenderingContext or WebGLRenderingContext or WebGL2RenderingContext or GPUCanvasContext) RenderingContext;

[Exposed=Window]
interface HTMLCanvasElement : HTMLElement {
  [HTMLConstructor] constructor();

  [CEReactions] attribute unsigned long width;
  [CEReactions] attribute unsigned long height;

  RenderingContext? getContext(DOMString contextId, optional any options = null);

  USVString toDataURL(optional DOMString type = "image/png", optional any quality);
  undefined toBlob(BlobCallback _callback, optional DOMString type = "image/png", optional any quality);
  OffscreenCanvas transferControlToOffscreen();
};

callback BlobCallback = undefined (Blob? blob);

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

Авторам не следует использовать элемент холста canvas в документе, если доступен более подходящий элемент. Например, нецелесообразно использовать элемент холста canvas для визуализации заголовка страницы: если желаемое представление заголовка является графически насыщенным, оно должно быть размечено с использованием соответствующих элементов (обычно h1), а затем стилизовано с использованием CSS и вспомогательных технологий, таких как теневые деревья.

Когда авторы используют элемент холста canvas, они также должны предоставлять контент, который при представлении пользователю передает по существу ту же функцию или цель, что и растровое изображение холста canvas. Это содержимое может быть размещено как содержимое элемента холста canvas. Содержимое элемента холста canvas, если оно есть, является резервным содержимым элемента.

В интерактивных визуальных средах, если для элемента холста canvas включены сценарии и включена поддержка элементов холста canvas, то элемент холста canvas представляет встроенное содержимое, состоящее из динамически создаваемого изображения, растрового изображения элемента.

В НЕ-интерактивных, статических, визуальных средах, если элемент холста canvas был ранее связан с контекстом визуализации (например, если страница просматривалась в интерактивном визуальном носителе и теперь печатается, или если какой-либо сценарий, который запускался во время макета страницы процесс, нарисованный на элементе), тогда элемент холста canvas представляет встроенное содержимое с текущим растровым изображением и размером элемента. В противном случае элемент вместо этого представляет свое резервное содержимое.

На НЕ-визуальных носителях и на визуальных носителях, если сценарии отключены для элемента холста canvas или если отключена поддержка элементов холста canvas, элемент холста canvas вместо этого представляет свое резервное содержимое.

Когда элемент холста canvas представляет внедрённое содержимое, пользователь по-прежнему может фокусировать потомков элемента холста canvas (в резервном содержимом). Когда элемент находится в фокусе, он становится целью событий взаимодействия с клавиатурой (даже если сам элемент не виден). Это позволяет авторам сделать интерактивный холст доступным с клавиатуры: у авторов должно быть взаимно однозначное сопоставление интерактивных областей с фокусируемыми областями в резервном содержимом. (Фокус не влияет на события взаимодействия с мышью.) [UIEVENTS]

Элемент, ближайший предок элемента холста canvas которого визуализируется и представляет внедрённое содержимое, является элементом, который используется в качестве соответствующего резервного содержимого холста (being used as relevant canvas fallback content).

Элемент холста canvas имеет два атрибута для управления размером растрового изображения элемента: width (ширину) и height (высоту). Эти атрибуты, если они указаны, должны иметь значения, которые являются действительными неотрицательными целыми числами. Правила синтаксического анализа неотрицательных целых чисел должны использоваться для получения их числовых значений (obtain their numeric values). Если атрибут отсутствует или если анализ его значения возвращает ошибку, то вместо него должно использоваться значение по умолчанию. Атрибут ширины width по умолчанию равен 300, а атрибут высоты height по умолчанию равен 150.

При установке значения атрибута ширины width или высоты height, если контекстный режим элемента холста canvas установлен на заполнитель (placeholder), пользовательский агент должен выдать исключение DOMException «InvalidStateError» и оставить значение атрибута неизменным.

Внутренние размеры элемента холста canvas, когда он представляет внедрённое содержимое, равны размерам растрового изображения элемента.

Пользовательский агент должен использовать квадратную плотность пикселей, состоящую из одного пикселя данных изображения на единицу координатного пространства для растровых изображений холста canvas и его контекстов визуализации.

Растровые изображения элементов холста canvas, растровые изображения объектов ImageBitmap, а также некоторые растровые изображения контекстов визуализации, такие как те, что описаны в разделах об объектах CanvasRenderingContext2D и ImageBitmapRenderingContext ниже, имеют флаг очистки источника (origin-clean), для которого можно установить значение true (правда) или false (ложь). Первоначально, когда создается элемент холста canvas или объект ImageBitmap, его флаг очистки источника растрового изображения должен быть установлен в значение true (истина).

К элементу холста canvas может быть привязан контекст визуализации (rendering context). Изначально у него нет привязанного контекста визуализации (рендеринга). Чтобы отслеживать, есть ли у него контекст визуализации или нет, и какой это контекст визуализации, холст canvas также имеет «режим контекста холста» (canvas context mode), который изначально отсутствует — none, но может быть изменен на placeholder, 2d, bitmaprenderer, webgl, webgl2 или webgpu с помощью алгоритмов, определенных в этой спецификации.

Когда его «режим контекста холста» отсутствует, элемент холста canvas не имеет контекста визуализации, а его растровое изображение должно быть прозрачным чёрным с внутренней шириной, равной числовому значению атрибута ширины width элемента, и внутренней высотой, равной числовому значению атрибута высоты height элемента, эти значения интерпретируются в пикселях CSS и обновляются по мере установки, изменения или удаления атрибутов.

Когда его режим контекста холста является заполнителем (placeholder), элемент холста canvas не имеет контекста визуализации. Он служит заполнителем для объекта OffscreenCanvas, а содержимое элемента холста canvas обновляется путем вызова метода commit() контекста визуализации объекта OffscreenCanvas.

Когда элемент холста canvas представляет встроенное содержимое, он предоставляет источник рисования, ширина которого является внутренней шириной элемента, высота которого является внутренней высотой элемента, а внешний вид — растровым изображением элемента.

Каждый раз, когда атрибуты содержимого ширины width и высоты height устанавливаются, удаляются, изменяются или избыточно устанавливаются на уже имеющееся значение, пользовательский агент должен выполнить действие из строки следующей таблицы, которая соответствует контекстному режиму элемента холста canvas.

IDL-атрибуты ширины width и высоты height должны отражать соответствующие атрибуты содержимого с одинаковыми именами и теми же значениями по умолчанию.

Метод getContext(contextId, options) элемента canvas при вызове должен выполнять следующие шаги:

1. Если options не является объектом, установите для options значение null.
2. Задайте options в результат преобразования options в значение JavaScript.
3. Выполните шаги в ячейке следующей таблицы, заголовок столбца которой соответствует контекстному режиму холста этого элемента холста canvas, а заголовок строки - contextId:

* Например, значение «webgl» или «webgl2» в случае, если пользовательский агент исчерпал возможности графического оборудования и не имеет программной резервной реализации.

Метод toDataURL(type, quality) при вызове должен выполнить следующие шаги:

1. Если для флага очистки источника растрового изображения этого элемента холста canvas установлено значение false, генерируется исключение DOMException «SecurityError».
2. Если в растровом изображении этого элемента холста canvas нет пикселей (т.е. либо его горизонтальный размер, либо его вертикальный размер равен нулю), то верните строку «data:,». (Это самый короткий data: URL; он представляет собой пустую строку в "text/plain" ресурсе.)
3. Пусть файл file будет сериализацией растрового изображения этого элемента холста canvas в виде файла, передавая тип type и качество quality, если они указаны.
4. Если файл file является null, верните «data:,».
5. Вернуть data: URL, представляющий файл file. [RFC2397]

Метод toBlob(callback, type, quality) при вызове должен выполнять следующие шаги:

1. Если для флага очистки источника растрового изображения этого элемента холста canvas установлено значение false, генерируется исключение DOMException «SecurityError».
2. Пусть результат result будет null.
3. Если в растровом изображении этого элемента холста canvas есть пиксели (т.е. ни его горизонтальный размер, ни его вертикальный размер не равны нулю), то установите результат result на копию растрового изображения этого элемента холста canvas.
4. Выполните эти шаги параллельно:
  4.1. Если результат result не равен null, то установите результат result на сериализацию результата result в виде файла с типом type и качеством quality, если он задан.
  4.2. Поставьте задачу элемента в очередь в источнике задачи сериализации больших двоичных объектов холста (canvas blob serialization task source) с учетом элемента холста canvas, чтобы выполнить следующие шаги:
    4.2.1. Если результат result не равен null, установите результат result в новый объект Blob, созданный в соответствующей Области этого элемента холста canvas, представляющий результат result. [FILEAPI]
    4.2.2. Вызвать обратный вызов callback с « result ».

Метод transferControlToOffscreen() при вызове должен выполнять следующие шаги:

1. Если для режима контекста этого элемента холста canvas не задано значение «none», вызовите исключение DOMException «InvalidStateError».
2. Пусть offscreenCanvas будет новым объектом OffscreenCanvas с шириной и высотой, равными значениям атрибутов содержимого ширины width и высоты height этого элемента холста canvas.
3. Установите элемент холста canvas заполнителя для offscreenCanvas как слабую ссылку на этот элемент холста canvas.
4. Установите контекстный режим этого элемента холста canvas на заполнитель.
5. Верните offscreenCanvas.

Контекст 2D визуализации

typedef (HTMLImageElement or
         SVGImageElement) HTMLOrSVGImageElement;

typedef (HTMLOrSVGImageElement or
         HTMLVideoElement or
         HTMLCanvasElement or
         ImageBitmap or
         OffscreenCanvas or
         VideoFrame) CanvasImageSource;

enum PredefinedColorSpace { "srgb", "display-p3" };

enum CanvasFillRule { "nonzero", "evenodd" };

dictionary CanvasRenderingContext2DSettings {
  boolean alpha = true;
  boolean desynchronized = false;
  PredefinedColorSpace colorSpace = "srgb";
  boolean willReadFrequently = false;
};

enum ImageSmoothingQuality { "low", "medium", "high" };

[Exposed=Window]
interface CanvasRenderingContext2D {
  // back-reference to the canvas
  readonly attribute HTMLCanvasElement canvas;

  CanvasRenderingContext2DSettings getContextAttributes();
};
CanvasRenderingContext2D includes CanvasState;
CanvasRenderingContext2D includes CanvasTransform;
CanvasRenderingContext2D includes CanvasCompositing;
CanvasRenderingContext2D includes CanvasImageSmoothing;
CanvasRenderingContext2D includes CanvasFillStrokeStyles;
CanvasRenderingContext2D includes CanvasShadowStyles;
CanvasRenderingContext2D includes CanvasFilters;
CanvasRenderingContext2D includes CanvasRect;
CanvasRenderingContext2D includes CanvasDrawPath;
CanvasRenderingContext2D includes CanvasUserInterface;
CanvasRenderingContext2D includes CanvasText;
CanvasRenderingContext2D includes CanvasDrawImage;
CanvasRenderingContext2D includes CanvasImageData;
CanvasRenderingContext2D includes CanvasPathDrawingStyles;
CanvasRenderingContext2D includes CanvasTextDrawingStyles;
CanvasRenderingContext2D includes CanvasPath;

interface mixin CanvasState {
  // state
  undefined save(); // push state on state stack
  undefined restore(); // pop state stack and restore state
  undefined reset(); // reset the rendering context to its default state
  boolean isContextLost(); // return whether context is lost
};

interface mixin CanvasTransform {
  // transformations (default transform is the identity matrix)
  undefined scale(unrestricted double x, unrestricted double y);
  undefined rotate(unrestricted double angle);
  undefined translate(unrestricted double x, unrestricted double y);
  undefined transform(unrestricted double a, unrestricted double b, unrestricted double c, unrestricted double d, unrestricted double e, unrestricted double f);

  [NewObject] DOMMatrix getTransform();
  undefined setTransform(unrestricted double a, unrestricted double b, unrestricted double c, unrestricted double d, unrestricted double e, unrestricted double f);
  undefined setTransform(optional DOMMatrix2DInit transform = {});
  undefined resetTransform();

};

interface mixin CanvasCompositing {
  // compositing
  attribute unrestricted double globalAlpha; // (default 1.0)
  attribute DOMString globalCompositeOperation; // (default source-over)
};

interface mixin CanvasImageSmoothing {
  // image smoothing
  attribute boolean imageSmoothingEnabled; // (default true)
  attribute ImageSmoothingQuality imageSmoothingQuality; // (default low)

};

interface mixin CanvasFillStrokeStyles {
  // colors and styles (see also the CanvasPathDrawingStyles and CanvasTextDrawingStyles interfaces)
  attribute (DOMString or CanvasGradient or CanvasPattern) strokeStyle; // (default black)
  attribute (DOMString or CanvasGradient or CanvasPattern) fillStyle; // (default black)
  CanvasGradient createLinearGradient(double x0, double y0, double x1, double y1);
  CanvasGradient createRadialGradient(double x0, double y0, double r0, double x1, double y1, double r1);
  CanvasGradient createConicGradient(double startAngle, double x, double y);
  CanvasPattern? createPattern(CanvasImageSource image, [LegacyNullToEmptyString] DOMString repetition);

};

interface mixin CanvasShadowStyles {
  // shadows
  attribute unrestricted double shadowOffsetX; // (default 0)
  attribute unrestricted double shadowOffsetY; // (default 0)
  attribute unrestricted double shadowBlur; // (default 0)
  attribute DOMString shadowColor; // (default transparent black)
};

interface mixin CanvasFilters {
  // filters
  attribute (DOMString or CanvasFilter) filter; // (default "none")
};

typedef record<DOMString, any> CanvasFilterInput;

[Exposed=(Window,Worker,PaintWorklet)]
interface CanvasFilter {
  constructor(optional (CanvasFilterInput or sequence<CanvasFilterInput>) filters);
};

interface mixin CanvasRect {
  // rects
  undefined clearRect(unrestricted double x, unrestricted double y, unrestricted double w, unrestricted double h);
  undefined fillRect(unrestricted double x, unrestricted double y, unrestricted double w, unrestricted double h);
  undefined strokeRect(unrestricted double x, unrestricted double y, unrestricted double w, unrestricted double h);
};

interface mixin CanvasDrawPath {
  // path API (see also CanvasPath)
  undefined beginPath();
  undefined fill(optional CanvasFillRule fillRule = "nonzero");
  undefined fill(Path2D path, optional CanvasFillRule fillRule = "nonzero");
  undefined stroke();
  undefined stroke(Path2D path);
  undefined clip(optional CanvasFillRule fillRule = "nonzero");
  undefined clip(Path2D path, optional CanvasFillRule fillRule = "nonzero");
  boolean isPointInPath(unrestricted double x, unrestricted double y, optional CanvasFillRule fillRule = "nonzero");
  boolean isPointInPath(Path2D path, unrestricted double x, unrestricted double y, optional CanvasFillRule fillRule = "nonzero");
  boolean isPointInStroke(unrestricted double x, unrestricted double y);
  boolean isPointInStroke(Path2D path, unrestricted double x, unrestricted double y);
};

interface mixin CanvasUserInterface {
  undefined drawFocusIfNeeded(Element element);
  undefined drawFocusIfNeeded(Path2D path, Element element);
  undefined scrollPathIntoView();
  undefined scrollPathIntoView(Path2D path);
};

interface mixin CanvasText {
  // text (see also the CanvasPathDrawingStyles and CanvasTextDrawingStyles interfaces)
  undefined fillText(DOMString text, unrestricted double x, unrestricted double y, optional unrestricted double maxWidth);
  undefined strokeText(DOMString text, unrestricted double x, unrestricted double y, optional unrestricted double maxWidth);
  TextMetrics measureText(DOMString text);
};

interface mixin CanvasDrawImage {
  // drawing images
  undefined drawImage(CanvasImageSource image, unrestricted double dx, unrestricted double dy);
  undefined drawImage(CanvasImageSource image, unrestricted double dx, unrestricted double dy, unrestricted double dw, unrestricted double dh);
  undefined drawImage(CanvasImageSource image, unrestricted double sx, unrestricted double sy, unrestricted double sw, unrestricted double sh, unrestricted double dx, unrestricted double dy, unrestricted double dw, unrestricted double dh);
};

interface mixin CanvasImageData {
  // pixel manipulation
  ImageData createImageData([EnforceRange] long sw, [EnforceRange] long sh, optional ImageDataSettings settings = {});
  ImageData createImageData(ImageData imagedata);
  ImageData getImageData([EnforceRange] long sx, [EnforceRange] long sy, [EnforceRange] long sw, [EnforceRange] long sh, optional ImageDataSettings settings = {});
  undefined putImageData(ImageData imagedata, [EnforceRange] long dx, [EnforceRange] long dy);
  undefined putImageData(ImageData imagedata, [EnforceRange] long dx, [EnforceRange] long dy, [EnforceRange] long dirtyX, [EnforceRange] long dirtyY, [EnforceRange] long dirtyWidth, [EnforceRange] long dirtyHeight);
};

enum CanvasLineCap { "butt", "round", "square" };
enum CanvasLineJoin { "round", "bevel", "miter" };
enum CanvasTextAlign { "start", "end", "left", "right", "center" };
enum CanvasTextBaseline { "top", "hanging", "middle", "alphabetic", "ideographic", "bottom" };
enum CanvasDirection { "ltr", "rtl", "inherit" };
enum CanvasFontKerning { "auto", "normal", "none" };
enum CanvasFontStretch { "ultra-condensed", "extra-condensed", "condensed", "semi-condensed", "normal", "semi-expanded", "expanded", "extra-expanded", "ultra-expanded" };
enum CanvasFontVariantCaps { "normal", "small-caps", "all-small-caps", "petite-caps", "all-petite-caps", "unicase", "titling-caps" };
enum CanvasTextRendering { "auto", "optimizeSpeed", "optimizeLegibility", "geometricPrecision" };

interface mixin CanvasPathDrawingStyles {
  // line caps/joins
  attribute unrestricted double lineWidth; // (default 1)
  attribute CanvasLineCap lineCap; // (default "butt")
  attribute CanvasLineJoin lineJoin; // (default "miter")
  attribute unrestricted double miterLimit; // (default 10)

  // dashed lines
  undefined setLineDash(sequence<unrestricted double> segments); // default empty
  sequence<unrestricted double> getLineDash();
  attribute unrestricted double lineDashOffset;
};

interface mixin CanvasTextDrawingStyles {
  // text
  attribute DOMString font; // (default 10px sans-serif)
  attribute CanvasTextAlign textAlign; // (default: "start")
  attribute CanvasTextBaseline textBaseline; // (default: "alphabetic")
  attribute CanvasDirection direction; // (default: "inherit")
  attribute double letterSpacing; // (default: 0)
  attribute CanvasFontKerning fontKerning; // (default: "auto")
  attribute CanvasFontStretch fontStretch; // (default: "normal")
  attribute CanvasFontVariantCaps fontVariantCaps; // (default: "normal")
  attribute CanvasTextRendering textRendering; // (default: "auto")
  attribute double wordSpacing; // (default: 0)
};

interface mixin CanvasPath {
  // shared path API methods
  undefined closePath();
  undefined moveTo(unrestricted double x, unrestricted double y);
  undefined lineTo(unrestricted double x, unrestricted double y);
  undefined quadraticCurveTo(unrestricted double cpx, unrestricted double cpy, unrestricted double x, unrestricted double y);
  undefined bezierCurveTo(unrestricted double cp1x, unrestricted double cp1y, unrestricted double cp2x, unrestricted double cp2y, unrestricted double x, unrestricted double y);
  undefined arcTo(unrestricted double x1, unrestricted double y1, unrestricted double x2, unrestricted double y2, unrestricted double radius); 
  undefined rect(unrestricted double x, unrestricted double y, unrestricted double w, unrestricted double h);
  undefined roundRect(unrestricted double x, unrestricted double y, unrestricted double w, unrestricted double h, sequence<(unrestricted double or DOMPointInit)> radii);
  undefined arc(unrestricted double x, unrestricted double y, unrestricted double radius, unrestricted double startAngle, unrestricted double endAngle, optional boolean counterclockwise = false); 
  undefined ellipse(unrestricted double x, unrestricted double y, unrestricted double radiusX, unrestricted double radiusY, unrestricted double rotation, unrestricted double startAngle, unrestricted double endAngle, optional boolean counterclockwise = false); 
};

[Exposed=(Window,Worker)]
interface CanvasGradient {
  // opaque object
  undefined addColorStop(double offset, DOMString color);
};

[Exposed=(Window,Worker)]
interface CanvasPattern {
  // opaque object
  undefined setTransform(optional DOMMatrix2DInit transform = {});
};

[Exposed=(Window,Worker)]
interface TextMetrics {
  // x-direction
  readonly attribute double width; // advance width
  readonly attribute double actualBoundingBoxLeft;
  readonly attribute double actualBoundingBoxRight;

  // y-direction
  readonly attribute double fontBoundingBoxAscent;
  readonly attribute double fontBoundingBoxDescent;
  readonly attribute double actualBoundingBoxAscent;
  readonly attribute double actualBoundingBoxDescent;
  readonly attribute double emHeightAscent;
  readonly attribute double emHeightDescent;
  readonly attribute double hangingBaseline;
  readonly attribute double alphabeticBaseline;
  readonly attribute double ideographicBaseline;
};

dictionary ImageDataSettings {
  PredefinedColorSpace colorSpace;
};

[Exposed=(Window,Worker),
 Serializable]
interface ImageData {
  constructor(unsigned long sw, unsigned long sh, optional ImageDataSettings settings = {});
  constructor(Uint8ClampedArray data, unsigned long sw, optional unsigned long sh, optional ImageDataSettings settings = {});

  readonly attribute unsigned long width;
  readonly attribute unsigned long height;
  readonly attribute Uint8ClampedArray data;
  readonly attribute PredefinedColorSpace colorSpace;
};

[Exposed=(Window,Worker)]
interface Path2D {
  constructor(optional (Path2D or DOMString) path);

  undefined addPath(Path2D path, optional DOMMatrix2DInit transform = {});
};
Path2D includes CanvasPath;

Объект CanvasRenderingContext2D имеет выходное растровое изображение (output bitmap), которое инициализируется при создании объекта.

Выходное растровое изображение имеет флаг очистки источника, который может иметь значение true или false. Первоначально, когда создаётся одно из этих растровых изображений, его флаг очистки источника должен быть установлен в значение true.

Объект CanvasRenderingContext2D также имеет альфа (alpha) — логическое значение. Когда альфа объекта CanvasRenderingContext2D имеет значение false, его альфа-канал должен быть зафиксирован на 1.0 (полностью непрозрачный) для всех пикселей, а попытки изменить альфа-компонент любого пикселя должны игнорироваться.

Объект CanvasRenderingContext2D также имеет десинхронизированное (desynchronized) логическое значение. Когда десинхронизация объекта CanvasRenderingContext2D имеет значение true, тогда пользовательский агент может оптимизировать визуализацию холста, чтобы уменьшить задержку, измеряемую от входных событий до растеризации, путем десинхронизации цикла рисования холста из цикла событий, минуя обычный алгоритм визуализации (рендеринга) пользовательского агента, или оба. Поскольку этот режим включает обход обычных механизмов рисования, растеризации или того и другого, он может вызвать видимые артефакты разрыва изображения.

Объект CanvasRenderingContext2D также имеет логическое значение «будет часто читать» (will read frequently). Когда объект CanvasRenderingContext2D «будет часто читать» является true, пользовательский агент может оптимизировать холст для операций чтения.

Объект CanvasRenderingContext2D также имеет параметр цветового пространства (color space) типа PredefinedColorSpace. Цветовое пространство объекта CanvasRenderingContext2D указывает цветовое пространство для выходного растрового изображения.

Шаги метода getContextAttributes() должны вернуть «[«alpha» → альфа этого this, «desynchronized» → десинхронизированный этого this, «colorSpace» → цветовое пространство этого this, «willReadFrequently» → будет часто читать этого this]».

Контекст 2D-рендеринга объекта CanvasRenderingContext2D представляет собой плоскую линейную декартову поверхность, начало координат (0,0) которой находится в верхнем левом углу, причем в координатном пространстве значения x увеличиваются при движении вправо, а значения y увеличиваются при движении вниз. Координата x самого правого края равна ширине выходного растрового изображения контекста рендеринга в пикселях CSS; аналогично, координата y самого нижнего края равна высоте выходного растрового изображения контекста рендеринга в пикселях CSS.

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

<canvas width=200 height=200 style=width:100px;height:100px>

Алгоритм создания 2D-контекста (2D context creation algorithm), которому передаются цель target (элемент холста canvas) и параметры options, состоит из выполнения следующих шагов:

1. Пусть настройки settings будут результатом преобразования параметров options в словарь типа CanvasRenderingContext2DSettings. (Это может вызвать исключение.)
2. Пусть context будет новым объектом CanvasRenderingContext2D.
3. Инициализируйте атрибут canvas контекста context, чтобы он указывал на цель target.
4. Установите для выходного растрового изображения контекста context то же растровое изображение, что и для растрового изображения цели target (чтобы они были общими).
5. Установите размеры растрового изображения равными числовым значениям атрибутов содержимого ширины width и высоты height цели target.
6. Установите альфа контекста context на settings["alpha"].
7. Установите десинхронизированный контекста context на settings["desynchronized"].
8. Установите цветовое пространство контекста context на settings["colorSpace"].
9. Установите будет часто читать контекста context на settings["willReadFrequently"].
10. Вернуть контекст context.

Когда пользовательский агент должен установить размеры растрового изображения (set bitmap dimensions) равными ширине и высоте, он должен выполнить следующие шаги:

1. Сбросьте контекст визуализации в состояние по умолчанию.
2. Измените размер выходного растрового изображения до новой ширины width и высоты height.
3. Пусть холст canvas будет элементом холста canvas, для которого был инициализирован атрибут canvas контекста визуализации.
4. Если числовое значение атрибута содержимого ширины width холста canvas отличается от ширины width, установите для атрибута содержимого ширины холста самую короткую строку, представляющую ширину как допустимое неотрицательное целое число.
5. Если числовое значение атрибута содержимого высоты height холста canvas отличается от высоты height, установите для атрибута содержимого высоты холста самую короткую строку, представляющую высоту как допустимое неотрицательное целое число.

Атрибут холста canvas должен возвращать значение, которым он был инициализирован при создании объекта.

Перечисление PredefinedColorSpace используется для указания цветового пространства резервного хранилища холста.

Значение «srgb» указывает цветовое пространство ‘srgb’.

Значение «display-p3» указывает цветовое пространство ‘display-p3’.

Перечисление CanvasFillRule используется для выбора алгоритма правила заполнения (fill rule), с помощью которого можно определить, находится ли точка внутри или за пределами пути.

Значение «nonzero» значение указывает на правило ненулевой намотки, при котором точка считается находящейся за пределами формы, если количество раз, когда полубесконечная прямая линия, проведенная из этой точки, пересекает путь формы, идущий в одном направлении, равно числу иногда он пересекает путь, идущий в другом направлении.

Значение «evenodd» указывает правило четности/нечётности, согласно которому точка считается находящейся за пределами формы, если количество раз, когда полубесконечная прямая линия, проведенная из этой точки, пересекает путь формы, является четным.

Если точка не находится вне фигуры, она находится внутри фигуры.

Перечисление ImageSmoothingQuality используется для выражения предпочтения качества интерполяции, используемого при сглаживании изображений.

Значение «low» указывает на предпочтение низкого уровня качества интерполяции изображения. Интерполяция изображений низкого качества может быть более эффективной с точки зрения вычислений, чем более высокие настройки.

Значение «medium» указывает предпочтение среднего уровня качества интерполяции изображения.

Значение «high» указывает на предпочтение высокого уровня качества интерполяции изображения. Высококачественная интерполяция изображений может быть более затратной с точки зрения вычислений, чем более низкие настройки.

Замечания по реализации

Этот раздел не является нормативным.

Выходное растровое изображение, когда оно не отображается непосредственно пользовательским агентом, реализации могут вместо обновления этого растрового изображения просто запоминать последовательность операций рисования, которые были применены к нему до тех пор, пока не потребуются фактические данные растрового изображения (например, из-за вызова drawImage() или фабричного метода createImageBitmap()). Во многих случаях это будет более эффективным с точки зрения памяти.

Растровое изображение элемента холста canvas — это единственное растровое изображение, которое почти всегда будет необходимо на практике. Выходное растровое изображение контекста визуализации, если оно есть, всегда является просто псевдонимом растрового изображения элемента холста canvas.

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

Состояние холста

Объекты, реализующие интерфейс CanvasState, поддерживают стек состояний рисования. Состояния чертежа (Drawing states) состоят из:

• Текущая матрица преобразования.
• Текущая область отсечения.
• Текущие значения следующих атрибутов: strokeStyle, fillStyle, globalAlpha, lineWidth, lineCap, lineJoin, miterLimit, lineDashOffset, shadowOffsetX, shadowOffsetY, shadowBlur, shadowColor, filter, globalCompositeOperation, font, textAlign, textBaseline, direction, letterSpacing, fontKerning, fontStretch, fontVariantCaps, textRendering, wordSpacing, imageSmoothingEnabled, imageSmoothingQuality.
• Текущий список тире.

Объекты, реализующие миксин CanvasState, имеют логическое значение потери контекста (context lost), которое инициализируется значением false при создании объекта. Значение потерянного контекста обновляется в шагах, связанных с потерей контекста.

Шаги метода save() заключаются в том, чтобы поместить копию текущего состояния рисования в стек состояний рисования.

Шаги метода restore() заключаются в том, чтобы вывести верхнюю запись в стек состояний рисования и сбросить состояние рисования, которое она описывает. Если сохранённого состояния нет, метод ничего не должен делать.

Шаги метода reset() заключаются в сбросе контекста визуализации в состояние по умолчанию.

Чтобы сбросить контекст рендеринга в состояние по умолчанию (reset the rendering context to its default state):

1. Очистить растровое изображение холста до прозрачного чёрного.
2. Очистите список подпути в текущем пути по умолчанию для контекста.
3. Очистите стек состояний рисования контекста.
4. Сбросьте всё, из чего состоит состояние рисования, к их начальным значениям.

Шаги метода isContextLost() должны вернуть потерянный контекст этого this.

Стили линий

Объекты, реализующие интерфейс CanvasPathDrawingStyles, имеют атрибуты и методы (определенные в этом разделе), которые управляют обработкой строк объектом.

Атрибут lineWidth даёт ширину линий в единицах координатного пространства. При получении он должен вернуть текущее значение. При настройке следует игнорировать нулевые, отрицательные, бесконечные и NaN значения, оставляя значение неизменным; другие значения должны изменить текущее значение на новое значение.

Когда создается объект, реализующий интерфейс CanvasPathDrawingStyles, атрибут lineWidth должен изначально иметь значение 1.0.

Атрибут lineCap определяет тип окончаний, которые UA будут размещать в конце строк. Три допустимых значения: «butt» (стык), «round» (круглый) и «square» (квадратный).

При получении он должен вернуть текущее значение. При настройке текущее значение должно быть изменено на новое значение.

Когда создаётся объект, реализующий интерфейс CanvasPathDrawingStyles, атрибут lineCap должен изначально иметь значение «butt» (стык).

Атрибут lineJoin определяет тип углов, которые UA будут размещать на стыке двух линий. Три допустимых значения: «bevel» (скос), «round» (скругление) и «miter» (митра).

При получении он должен вернуть текущее значение. При настройке текущее значение должно быть изменено на новое значение.

Когда создаётся объект, реализующий интерфейс CanvasPathDrawingStyles, атрибут lineJoin должен изначально иметь значение «miter» (митра).

Когда атрибут lineJoin имеет значение «miter» (митра), штрихи используют предельное значение угла наклона, чтобы решить, как визуализировать соединения. Коэффициент ограничения митры может быть явно установлен с помощью атрибута miterLimit. При получении он должен вернуть текущее значение. При настройке следует игнорировать нулевые, отрицательные, бесконечные и NaN значения, оставляя значение неизменным; другие значения должны изменить текущее значение на новое значение.

Когда создается объект, реализующий интерфейс CanvasPathDrawingStyles, атрибут miterLimit должен изначально иметь значение 10.0.

Каждый объект CanvasPathDrawingStyles имеет список тире, который либо пуст, либо состоит из чётного числа неотрицательных чисел. Изначально список тире должен быть пустым.

Метод setLineDash(segments) при вызове должен выполнить следующие шаги:

1. Если какое-либо значение в сегментах segments не является конечным (например, значение Infinity или NaN), или если какое-либо значение отрицательно (меньше нуля), то возвратите (без генерации исключения; пользовательские агенты могут отображать сообщение на консоли разработчика, хотя, так как это было бы полезно для отладки).
2. Если количество элементов в сегментах segments нечётное, пусть сегменты segments будут объединением двух копий сегментов segments.
3. Пусть в тире-списке объекта будут сегменты segments.

Когда вызывается метод getLineDash(), он должен возвращать последовательность, значения которой являются значениями тире-списка объекта в том же порядке.

Иногда бывает полезно изменить «фазу» штрихового рисунка, например для достижения эффекта «марширующих муравьев». Фазу можно установить с помощью атрибута lineDashOffset. При получении он должен вернуть текущее значение. При настройке следует игнорировать бесконечные значения и значения NaN, оставляя значение неизменным; другие значения должны изменить текущее значение на новое значение.

Когда создается объект, реализующий интерфейс CanvasPathDrawingStyles, атрибут lineDashOffset должен изначально иметь значение 0.0.

Когда пользовательский агент должен отслеживать путь (trace a path), учитывая стиль style объекта, реализующий интерфейс CanvasPathDrawingStyles, он должен запустить следующий алгоритм. Этот алгоритм возвращает новый путь.

1. Пусть путь path будет копией отслеживаемого пути.
2. Удалите из контура все линейные сегменты нулевой длины.
3. Удалите из пути path все подпути, не содержащие строк (т. е. подпути с одной точкой).
4. Замените каждую точку в каждом подпути пути path, кроме первой и последней точки каждого подпути, соединением join, которое соединяет линию, ведущую к этой точке, с линией, ведущей из этой точки, так что все подпути состояли из двух точек ( начальная точка с линией, выходящей из нее, и конечная точка с линией, ведущей в нее), одна или несколько линий (соединяющих точки и соединения) и ноль или более соединений (каждая соединяющая одну линию с другой), соединены вместе так, что каждый подпуть представляет собой серию из одной или нескольких линий с соединением между каждой из них и точкой на каждом конце.
5. Добавьте прямую замыкающую линию к каждому замкнутому подпутью в пути path, соединяющем последнюю точку и первую точку этого подпути; измените последнюю точку на соединение (с предыдущей последней строки на новую добавленную закрывающую строку) и измените первую точку на соединение (с недавно добавленной закрывающей строки на первую строку).
6. Если список тире стиля style пуст, перейдите к шагу с пометкой convert.
7. Пусть ширина шаблона pattern width будет объединением всех записей списка штрихов стиля style в единицах координатного пространства.
8. Для каждого подпути subpath в пути path выполните следующие подшаги. Эти подшаги изменяют подпути в пути в естественных условиях path in vivo.
8.1. Пусть ширина подпути subpath width равняется длине всех строк подпути subpath в единицах координатного пространства.
8.2. Пусть смещение offset будет значением lineDashOffset стиля style в единицах координатного пространства.
8.3. Если смещение offset больше ширины шаблона pattern width, уменьшите его на ширину шаблона pattern width. Пока смещение offset меньше нуля, увеличивайте его на ширину шаблона pattern width.
8.4. Определите L как линию линейных координат, определенную вдоль всех линий в подпути subpath, так что начало первой строки в подпути определяется как координата 0, а конец последней строки в подпути определяется как координата ширины подпути subpath width.
8.5. Пусть позиция position равна нулю минус смещение offset.
8.6. Пусть index равен 0.
8.7. Пусть текущее состояние current state будет выключено off (другие состояния будут включенными on и нулевыми zero-on).
8.8. Dash on: пусть длина сегмента segment length будет значением индексной записи тире списка в стиле style.
8.9. Увеличить позицию position на длину сегмента segment length.
8.10. Если позиция position больше ширины подпути subpath width, то завершите эти подшаги для этого подпути и начните их снова для следующего подпути; если подпутей больше нет, то вместо этого перейдите к шагу с пометкой convert.
8.11. Если длина сегмента segment length отлична от нуля, пусть текущее состояние current state будет включено on.
8.12. Увеличить индекс index на единицу.
8.13. Dash off: пусть длина сегмента segment length будет значением индексной index записи в списке тире стиля style.
8.14. Пусть start будет положением смещения позиции position на L.
8.15. Увеличить позицию position на длину сегмента segment length.
8.16. Если позиция position меньше нуля, перейдите к шагу, обозначенному после обрезки post-cut.
8.17. Если start меньше нуля, пусть start будет нулем.
8.18. Если позиция position больше ширины подпути subpath width, тогда пусть end будет смещением ширины подпути subpath width на L. В противном случае пусть end будет смещением позиции position на L.
8.19. Перейти к первому подходящему шагу:

==> Если длина сегмента segment length равна нулю и текущее состояние current state выключено off

Ничего не делайте, просто перейдите к следующему шагу.

==> Если текущее состояние current state выключено off

Разрежьте линию, конец end которой окажется коротким, и поместите на ней точку, разрезав пополам подпуть, в которой она находилась; удалить все линейные сегменты, соединения, точки и подпути, которые находятся между началом start и концом end; и, наконец, поместите одну точку в начале start без соединяющихся с ней линий.

Точка имеет направленность directionality для рисования концов линий (см. Ниже). Направленность - это направление, которое исходная линия имела в этой точке (то есть, когда L была определена выше).

==> В противном случае

Разрежьте линию, на которой начало start находится в начале start, на две части и поместите там точку, разрезав пополам подпуть, в которой она находилась, и аналогичным образом разрежьте линию, на которой конец оказывается коротким в конце, и поместите там точку, разрезая пополам подпуть, в котором он находился, а затем удалите все линейные сегменты, соединения, точки и подпути, которые находятся между началом start и концом end.

Если начало start и конец end являются одной и той же точкой, тогда это приводит к тому, что линия разрезается на две и две точки вставляются туда, при этом ничего не удаляется, если только соединение не происходит в этой точке, и в этом случае соединение должно быть удаленный.

8.20. После обрезки Post-cut: если позиция position больше ширины подпути subpath width, перейдите к шагу, обозначенному как convert (преобразовать).
8.21. Если длина сегмента segment length больше нуля, пусть positioned-at-on-dash будет ложным false.
8.22. Увеличить индекс index на единицу. Если оно равно количеству записей в тире-списке стиля style, тогда пусть index будет 0.
8.23. Вернитесь к шагу, обозначенному dash on.

9. Convert (Преобразовать): это шаг, который преобразует путь в новый путь, представляющий его ход.

Создайте новый путь, который описывает край областей, которые будут охвачены, если прямая линия с длиной, равной lineWidth стиля style, будет проходить вдоль каждого подпути в пути path, сохраняя при этом такой угол, чтобы линия была ортогональна перемещаемому пути, заменяя каждую точку концевой заглушкой, необходимой для удовлетворения атрибута стиля lineCap, как описано ранее и подробно описано ниже, и заменяя каждое соединение объединением, необходимым для удовлетворения типа lineJoin стиля style, как определено ниже.

Caps (Заглушки): каждая точка имеет плоский край, перпендикулярный направлению линии, выходящей из неё. Затем он увеличивается в соответствии со значением lineCap стиля style. Значение "butt" (стыка) означает, что дополнительная граница строки не добавляется. Значение "round" означает, что полукруг с диаметром, равным ширине lineWidth стиля style, необходимо дополнительно разместить на линии, выходящей из каждой точки. Значение "square" означает, что в каждой точке должен быть добавлен прямоугольник с длиной ширины lineWidth стиля style и шириной ширины lineWidth половинного стиля style, расположенный ровно напротив края, перпендикулярного направлению линии, выходящей из точки.

Точки, из которых не выходят линии, должны иметь две заглушки, расположенные вплотную друг к другу, как если бы на самом деле это были две точки, соединённые друг с другом бесконечно короткой прямой линией в направлении направленности directionality точки (как определено выше).

Joins (Соединения): в дополнение к точке, где происходит соединение, к каждому соединению относятся две дополнительные точки, по одной для каждой линии: два угла, находящиеся на половине ширины линии от точки соединения, по одному перпендикулярно каждой линии, каждый сбоку дальше всего от другой линии.

Треугольник, соединяющий эти два противоположных угла прямой линией, при этом третья точка треугольника является точкой соединения, должен быть добавлен на всех соединениях. Атрибут lineJoin определяет, отображается ли что-нибудь еще. Три вышеупомянутых значения имеют следующие значения:

Значение "bevel" означает, что это всё, что отображается при соединениях.

Значение "round" означает, что дуга, соединяющая два вышеупомянутых угла соединения, примыкающая (но не перекрывающаяся) к вышеупомянутому треугольнику, с диаметром, равным ширине линии и исходной точкой в ​​точке соединения, должна быть добавлена ​​в присоединяется.

Значение "miter" (под углом) означает, что второй треугольник (если он может задавать длину под углом) должен быть добавлен в месте соединения, при этом одна линия является линией между двумя вышеупомянутыми углами, примыкая к первому треугольнику, а два других являются продолжением внешние края двух соединительных линий, если требуется, чтобы они пересекались, не выходя за пределы угла скоса.

Длина под углом - это расстояние от точки соединения до пересечения краев линии на внешней стороне соединения. Коэффициент предела скоса - это максимально допустимое отношение длины скоса к половине ширины линии. Если длина скоса приведет к превышению предельного отношения скоса (установленного атрибутом miterLimit стиля style), то этот второй треугольник нельзя добавлять.

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

10. Верните только что созданный путь.

Стили текста

Объекты, реализующие интерфейс CanvasTextDrawingStyles, имеют атрибуты (определенные в этом разделе), которые управляют размещением текста (растровым или контурным) объектом. Такие объекты также могут иметь исходный объект стиля шрифта (font style source object). Для объектов CanvasRenderingContext2D это элемент холста canvas, заданный значением атрибута canvas контекста. Для объектов OffscreenCanvasRenderingContext2D это связанный объект OffscreenCanvas.

Разрешение шрифта для исходного объекта стиля шрифта требует источника шрифта. Это определяется для данного объекта object, реализующего CanvasTextDrawingStyles, с помощью следующих шагов: [CSSFONTLOAD]

1. Если исходный объект стиля шрифта объекта object является элементом холста canvas, вернуть документ узла элемента.
2. В противном случае исходный объект стиля шрифта объекта object является объектом OffscreenCanvas:
   2.1. Пусть global будет соответствующим глобальным объектом объекта object.
   2.2. Если global является объектом Window, верните связанный с ним Document .
   2.3. Утверждено: global реализует WorkerGlobalScope.
   2.4. Вернуть global.

IDL-атрибут font при установке должен быть проанализирован как значение CSS <‘font‘> (но без поддержки независимого от свойства синтаксиса таблицы стилей, такого как ‘inherit‘), а результирующий шрифт должен быть назначен контексту с помощью ‘line-height‘ переведен в ‘normal‘, компонент ‘font-size‘ преобразован в пиксели CSS, а системные шрифты вычислены для явных значений. Если новое значение является синтаксически неправильным (включая использование независимого от свойств синтаксиса таблицы стилей, такого как ‘inherit‘ (наследовать) или ‘inherit‘ (начальный)), его следует игнорировать, не назначая новое значение шрифта. [CSS]

Имена семейств шрифтов должны интерпретироваться в контексте исходного объекта стиля шрифта, когда шрифт должен использоваться; поэтому любые шрифты, встроенные с помощью @font-face или загруженные с использованием объектов FontFace, которые видны исходному объекту стиля шрифта, должны быть доступны после их загрузки. (Каждый исходный объект стиля шрифта имеет источник шрифта, который определяет, какие шрифты доступны.) Если шрифт используется до его полной загрузки или если исходный объект стиля шрифта не имеет этого шрифта в области видимости во время использования шрифта, то его следует рассматривать так, как если бы это был неизвестный шрифт, возвращаясь к другому, как описано в соответствующих спецификациях CSS. [CSSFONTS] [CSSFONTLOAD]

При получении атрибут шрифта font должен возвращать сериализованную форму текущего шрифта контекста (с компонентом не ‘line-height’). [CSSOM]

При создании объекта, реализующего интерфейс CanvasTextDrawingStyles, шрифт контекста должен быть установлен на 10 пикселей без засечек.

Когда для компонента ‘font-size’ (размер шрифта) задана длина с использованием процентов, единиц ’em’ или ‘ex’ или ключевых слов ‘larger‘ (больше) или ‘smaller‘ (меньше), они должны интерпретироваться относительно вычисленного значения ‘font-size’ (размер шрифта) исходного объекта стиля шрифта во время установки атрибута, если это элемент.

Когда для компонента ‘font-weight’ установлены относительные значения ‘bolder‘ (жирнее) и ‘lighter‘ (стройнее), они должны интерпретироваться относительно вычисленного значения свойства ‘font-weight’ исходного объекта стиля шрифта в то время, когда атрибут установлен, если это элемент.

Если вычисленные значения не определены для конкретного случая (например, из-за того, что исходный объект стиля шрифта не является элементом или не визуализируется), тогда относительные ключевые слова должны интерпретироваться относительно стандартного шрифта без засечек размером 10 пикселей по умолчанию.

IDL-атрибут textAlign при получении должен возвращать текущее значение. При настройке текущее значение должно быть изменено на новое значение. Когда создается объект, реализующий интерфейс CanvasTextDrawingStyles, атрибут textAlign изначально должен иметь значение start.

IDL-атрибут textBaseline при получении должен возвращать текущее значение. При настройке текущее значение должно быть изменено на новое значение. При создании объекта, реализующего интерфейс CanvasTextDrawingStyles, атрибуту textBaseline изначально должно быть присвоено значение alphabetic.

IDL-атрибут direction при получении должен возвращать текущее значение. При настройке текущее значение должно быть изменено на новое значение. При создании объекта, реализующего интерфейс CanvasTextDrawingStyles, атрибут direction должен изначально иметь значение «inherit» (наследовать).

IDL-атрибут letterSpacing при получении должен возвращать текущее значение. При настройке текущее значение должно быть изменено на новое значение, где значения могут быть положительными или отрицательными. При создании объекта, реализующего интерфейс CanvasTextDrawingStyles, атрибут letterSpacing изначально должен иметь значение 0.

IDL-атрибут fontKerning при получении должен возвращать текущее значение. При настройке текущее значение должно быть изменено на новое значение. При создании объекта, реализующего интерфейс CanvasTextDrawingStyles, атрибут fontKerning изначально должен иметь значение «auto«.

IDL-атрибут fontStretch при получении должен возвращать текущее значение. При настройке текущее значение должно быть изменено на новое значение. При создании объекта, реализующего интерфейс CanvasTextDrawingStyles, атрибут fontStretch изначально должен иметь значение «normal«.

IDL-атрибут fontVariantCaps при получении должен возвращать текущее значение. При настройке текущее значение должно быть изменено на новое значение. При создании объекта, реализующего интерфейс CanvasTextDrawingStyles, атрибут fontVariantCaps изначально должен иметь значение «normal«.

IDL-атрибут textRendering при получении должен возвращать текущее значение. При настройке текущее значение должно быть изменено на новое значение. При создании объекта, реализующего интерфейс CanvasTextDrawingStyles, атрибут textRendering изначально должен иметь значение «auto«.

IDL-атрибут wordSpacing при получении должен возвращать текущее значение. При настройке текущее значение должно быть изменено на новое значение, где значения могут быть положительными или отрицательными. При создании объекта, реализующего интерфейс CanvasTextDrawingStyles, атрибуту wordSpacing изначально должно быть присвоено значение 0.

Допустимые ключевые слова атрибута textAlign:

start

Выравнивание по начальному краю текста (левая сторона при написании текста слева направо, правая сторона при написании справа налево).

end

Выравнивание по краю текста (правая сторона при написании текста слева направо, левая сторона при написании справа налево).

left

Выровнять по левому краю.

right

Выровняйте по правому краю.

center

Выровнять по центру.

Разрешённые ключевые слова атрибута textBaseline соответствуют точкам выравнивания в шрифте:

Ключевые слова сопоставляются с этими точками выравнивания следующим образом:

top

Верхняя часть квадрата em

hanging

Висящая базовая линия

middle

Середина квадрата em

alphabetic

Алфавитная базовая линия

ideographic

Идеографическая-нижняя базовая линия

bottom

Нижняя часть квадрата em

Допустимые ключевые слова атрибута direction:

ltr

Обрабатывайте входные данные для алгоритма подготовки текста как текст слева направо.

rtl

Обрабатывайте входные данные для алгоритма подготовки текста как текст с написанием справа налево.

inherit

По умолчанию используется направление элемента холста canvas или документа Document в зависимости от ситуации.

Допустимые ключевые слова атрибута fontKerning:

auto

Кернинг применяется по усмотрению пользовательского агента.

normal

Применяется кернинг.

none

Кернинг не применяется.

Допустимые ключевые слова атрибута fontStretch:

ultra-condensed

То же, что и параметр CSS ‘font-stretch’ ‘ultra-condensed’.

extra-condensed

То же, что и параметр CSS ‘font-stretch’ ‘extra-condensed’.

condensed

То же, что и параметр CSS ‘font-stretch’ ‘condensed’.

semi-condensed

То же, что и параметр CSS ‘font-stretch’ ‘semi-condensed’.

normal

Настройка по умолчанию, при которой ширина глифов равна 100%.

semi-expanded

То же, что и параметр CSS ‘font-stretch’ ‘semi-expanded’.

expanded

То же, что и параметр CSS ‘font-stretch’ ‘expanded’.

extra-expanded

То же, что и параметр CSS ‘font-stretch’ ‘extra-expanded’.

ultra-expanded

То же, что и параметр CSS ‘font-stretch’ ‘ultra-expanded’.

Допустимые ключевые слова атрибута fontVariantCaps:

normal

Ни одна из перечисленных ниже функций не включена.

small-caps

То же, что и параметр CSS ‘font-variant-caps’ ‘small-caps’.

all-small-caps

То же, что и параметр CSS  ‘font-variant-caps’ ‘all-small-caps’.

petite-caps

То же, что и параметр CSS ‘font-variant-caps’ ‘petite-caps’.

all-petite-caps

То же, что и параметр CSS ‘font-variant-caps’ ‘all-petite-caps’.

unicase

То же, что и параметр CSS ‘font-variant-caps’ ‘unicase’.

titling-caps

То же, что и параметр CSS ‘font-variant-caps’ ‘titling-caps’.

Допустимые ключевые слова атрибута textRendering:

auto

То же, что и ‘auto‘ в свойстве рендеринга текста SVG.

optimizeSpeed

То же, что и  ‘optimizeSpeed‘ в свойстве рендеринга текста SVG.

optimizeLegibility

То же, что и ‘optimizeLegibility‘ в свойстве рендеринга текста SVG.

geometricPrecision

То же, что и ‘geometricPrecision‘ в свойстве рендеринга текста SVG.

Алгоритм подготовки текста (text preparation algorithm) следующий. В качестве входных данных он принимает строку text, объект CanvasTextDrawingStyles target и необязательную длину maxWidth. Он возвращает массив форм глифов, каждая из которых расположена в общем координатном пространстве, physical alignment (физическое выравнивание), значение которого равно одному из left, right и center, а также встроенный блок. (Большинство вызывающих этот алгоритм игнорируют физическое выравнивание physical alignment и встроенный блок.)

1. Если параметр maxWidth был предоставлен, но он меньше или равен нулю или равен NaN, то возвращается пустой массив.

2. Замените все пробелы ASCII в тексте text символами U+0020 SPACE.

3. Пусть font будет текущим шрифтом цели target, заданным атрибутом font этого объекта.

4. Примените соответствующий шаг из следующего списка, чтобы определить значение направления direction:

Если атрибут direction целевого объекта target имеет значение «ltr»

Пусть направление direction будет ‘ltr‘.

Если атрибут direction целевого объекта target имеет значение «rtl»

Пусть направление direction будет ‘rtl‘.

Если исходный объект стиля шрифта целевого объекта target является элементом

Пусть направление direction будет направлением исходного объекта стиля шрифта целевого объекта target.

Если исходный объект стиля шрифта целевого объекта target является документом с ненулевым элементом документа

Пусть направление direction будет направлением элемента документа исходного объекта стиля шрифта целевого объекта target.

В противном случае

Пусть направление direction будет ‘ltr‘.

5. Сформируйте гипотетический бесконечно широкий линейный блок CSS, содержащий один встроенный блок, содержащий текст text, с его свойствами CSS, установленными следующим образом:

и со всеми другими свойствами, установленными в их начальные значения.

6. Если параметр maxWidth был предоставлен, а гипотетическая ширина встроенного блока в гипотетическом линейном блоке больше, чем maxWidth CSS-пиксели, измените шрифт на более сжатый (если он доступен или если достаточно читаемый шрифт может быть синтезирован путем применения коэффициента масштабирования по горизонтали к шрифту) или шрифт меньшего размера и вернитесь к предыдущему шагу.

7. Точка привязки (anchor point) — это точка на встроенном блоке, а physical alignment (физическое выравнивание) — одно из значений left, right и center. Эти переменные определяются значениями textAlign и textBaseline следующим образом:

Горизонтальное положение:

Если textAlign является left

Если textAlign является start, а направление direction является ‘ltr’

Если textAlign является end, а направление direction является ‘rtl’

Пусть точка привязки anchor point по горизонтали будет левым краем встроенного блока, а физическое выравнивание physical alignment будет left.

Если textAlign является right

Если textAlign является end, а направление direction является ‘ltr’

Если textAlign является start, а направление direction является ‘rtl’

Пусть точка привязки по горизонтали будет правым краем встроенного блока, и пусть физическое выравнивание будет right.

Если textAlign является

Пусть точка привязки anchor point по горизонтали будет посередине между левым и правым краями встроенного блока, а физическое выравнивание physical alignment будет center.

Вертикальное положение:

Если textBaseline является top (наверху)

Пусть точка привязки anchor point по вертикали будет верхней частью блока em первого доступного шрифта встроенного блока.

Если textBaseline является hanging (висит)

Пуст точка привязки anchor point по вертикали будет базовой линией первого доступного шрифта встроенного блока.

Если textBaseline является middle (средний)

Пусть точка привязки anchor point по вертикали будет на полпути между нижней и верхней частью поля em первого доступного шрифта встроенного блока.

Если textBaseline является alphabetic (алфавитным)

Пусть точка привязки anchor point по вертикали будет алфавитной базовой линией первого доступного шрифта встроенного блока.

Если textBaseline является ideographic (идеографическим)

Пусть точка привязки anchor point по вертикали будет идеографической нижней базовой линией первого доступного шрифта встроенного блока.

Если textBaseline является bottom (находится внизу)

Пусть точка привязки anchor point по вертикали будет нижней частью блока em первого доступного шрифта встроенного блока.

8. Пусть результатом result будет массив, созданный путем итерации по каждому глифу во встроенном поле слева направо (если есть), добавления к массиву для каждого глифа формы глифа, как он есть во встроенном поле, расположенного на координате пространство с использованием пикселей CSS с его источником находится в точке привязки anchor point.

9. Вернуть результат result, физическое выравнивание physical alignment и встроенный блок.

Информационные ссылки

HTML | Оглавление

Стандарт HTML — Раздел «4.12.5 The canvas element» — https://html.spec.whatwg.org/multipage/canvas.html