CanvasRenderingContext2D: метод drawImage()

Метод CanvasRenderingContext2D.drawImage() API Canvas 2D предоставляет различные способы отрисовки изображения на холсте.

image

Элемент для отрисовки в контексте. Спецификация допускает любые источники изображения холста, в частности, HTMLImageElement, SVGImageElement, HTMLVideoElement, HTMLCanvasElement, ImageBitmap, OffscreenCanvas или VideoFrame.

sx Необязательно

Координата x левого верхнего угла подпрямоугольника источника image для отрисовки в целевом контексте. Используйте синтаксис с 3 или 5 аргументами, чтобы опустить этот аргумент.

sy Необязательно

Координата y левого верхнего угла подпрямоугольника источника image для отрисовки в целевом контексте. Используйте синтаксис с 3 или 5 аргументами, чтобы опустить этот аргумент.

sWidth Необязательно

Ширина подпрямоугольника источника image для отрисовки в целевом контексте. Если не указано, используется вся прямоугольная область от координат, указанных sx и sy до правого нижнего угла изображения. Используйте синтаксис с 3 или 5 аргументами, чтобы опустить этот аргумент. Отрицательное значение перевернёт изображение.

sHeight Необязательно

Высота подпрямоугольника источника image для отрисовки в целевом контексте. Используйте синтаксис с 3 или 5 аргументами, чтобы опустить этот аргумент. Отрицательное значение перевернёт изображение.

dx

Координата x в целевом холсте, где нужно разместить левый верхний угол источника image.

dy

Координата y в целевом холсте, где нужно разместить левый верхний угол источника image.

dWidth

Ширина для отрисовки image на целевом холсте. Это позволяет масштабировать отрисовываемое изображение. Если не указано, изображение не масштабируется по ширине при отрисовке. Обратите внимание, что этот аргумент не включён в синтаксис с 3 аргументами.

dHeight

Высота для отрисовки image на целевом холсте. Это позволяет масштабировать отрисовываемое изображение. Если не указано, изображение не масштабируется по высоте при отрисовке. Обратите внимание, что этот аргумент не включён в синтаксис с 3 аргументами.

None (undefined).

InvalidStateError DOMException

Выбрасывается, когда изображение не содержит данных изображения или если ширина или высота холста или области источника равны нулю.

TypeMismatchError DOMException

Выбрасывается, когда в качестве параметра передано изображение типа null или undefined.

В этом примере изображение отрисовывается на холсте с помощью метода drawImage().

HTML

<canvas id="canvas"></canvas>
<div style="display:none;">
  <img
    id="source"
    src="https://mdn.github.io/shared-assets/images/examples/rhino.jpg"
    width="300"
    height="227" />
</div>

JavaScript

Исходное изображение взято из координат (33, 71), с шириной 104 и высотой 124. Оно отрисовывается на холсте в (21, 20), где получает ширину 87 и высоту 104.

const canvas = document.getElementById("canvas");
const ctx = canvas.getContext("2d");
const image = document.getElementById("source");

image.addEventListener("load", (e) => {
  ctx.drawImage(image, 33, 71, 104, 124, 21, 20, 87, 104);
});

Результат

Метод drawImage() использует внутренние размеры исходного элемента в CSS пикселях при отрисовке.

Например, если вы загружаете Image и задаёте необязательные параметры размера в его конструкторе, вам придётся использовать свойства naturalWidth и naturalHeight созданного экземпляра для правильного расчёта таких областей, как обрезка и масштабирование, а не element.width и element.height. То же самое касается videoWidth и videoHeight если элемент является элементом <video>, и так далее.

HTML

<canvas id="canvas"></canvas>

JavaScript

const canvas = document.getElementById("canvas");
const ctx = canvas.getContext("2d");

const image = new Image(60, 45); // Using optional size for image
image.onload = drawImageActualSize; // Draw when image has loaded

// Load an image of intrinsic size 300x227 in CSS pixels
image.src = "https://mdn.github.io/shared-assets/images/examples/rhino.jpg";

function drawImageActualSize() {
  // Use the intrinsic size of image in CSS pixels for the canvas element
  canvas.width = this.naturalWidth;
  canvas.height = this.naturalHeight;

  // Will draw the image as 300x227, ignoring the custom size of 60x45
  // given in the constructor
  ctx.drawImage(this, 0, 0);

  // To use the custom size we'll have to specify the scale parameters
  // using the element's width and height properties - lets draw one
  // on top in the corner:
  ctx.drawImage(this, 0, 0, this.width, this.height);
}

Результат

• drawImage() корректно работает с элементом HTMLVideoElement только когда его свойство HTMLMediaElement.readyState больше 1 (т.е. событие seek сработало после установки свойства currentTime).
• drawImage() всегда будет использовать внутренние размеры исходного элемента в CSS пикселях при отрисовке, обрезке и/или масштабировании.
• В некоторых старых версиях браузеров drawImage() игнорирует всю метаданные EXIF в изображениях, включая ориентацию. Это поведение особенно проблематично на устройствах iOS. Вы должны самостоятельно определить ориентацию и использовать rotate() для корректной отрисовки.

• Интерфейс, определяющий этот метод: CanvasRenderingContext2D