CanvasRenderingContext2D.drawImage()

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

Синтаксис

void ctx.drawImage(image, dx, dy);
void ctx.drawImage(image, dx, dy, dWidth, dHeight);
void ctx.drawImage(image, sx, sy, sWidth, sHeight, dx, dy, dWidth, dHeight);

Параметры

image

Элемент для отображения в контексте. Функция принимает любой источник изображения, пригодный для отображения на холсте (CanvasImageSource), конкретнее, CSSImageValue,  HTMLImageElement, SVGImageElement, HTMLVideoElement, HTMLCanvasElement, ImageBitmap или OffscreenCanvas.

dx

Координата по оси Х, обозначающая стартовую точку холста-приемника, в которую будет помещен верхний левый угол исходного image.

dy

Координата по оси Y, обозначающая стартовую точку холста-приемника, в которую будет помещен верхний левый угол исходного image.

dWidth

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

dHeight

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

sx

Координата по оси X верхнего левого угла фрагмента, который будет вырезан из изображения-источника и помещен в контекст-приемник.

sy

Координата по оси Y верхнего левого угла фрагмента, который будет вырезан из изображения-источника и помещен в контекст-приемник.

sWidth

Ширина фрагмента, который будет вырезан из изображения источника и помещен в контекст-приемник. Если не задана, фрагмент от точки, заданной sx и sy до правого нижнего угла источника будет целиком скопирован в контекст-приемник.

sHeight

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

Исключения

INDEX_SIZE_ERR

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

INVALID_STATE_ERR

Источник не имеет данных изображения.

TYPE_MISMATCH_ERR

Тип данных источника не поддерживается.

Примеры

Использование метода drawImage

Вот простой пример использования drawImage.

HTML

<canvas id="canvas"></canvas>
<div style="display:none;">
  <img id="source" src="https://mdn.mozillademos.org/files/5397/rhino.jpg"
       width="300" height="227">
</div>

JavaScript

var canvas = document.getElementById('canvas');
var ctx = canvas.getContext('2d');
var image = document.getElementById('source');

ctx.drawImage(image, 33, 71, 104, 124, 21, 20, 87, 104);

Отредактируйте код ниже и посмотрите, как ваши изменения отражаются на холсте:

<canvas id="canvas" width="400" height="200" class="playable-canvas"></canvas>
<div style="display:none;">
  <img id="source" src="https://mdn.mozillademos.org/files/5397/rhino.jpg" width="300" height="227">
</div>
<div class="playable-buttons">
  <input id="edit" type="button" value="Edit" />
  <input id="reset" type="button" value="Reset" />
</div>
<textarea id="code" class="playable-code">
ctx.drawImage(image, 33, 71, 104, 124, 21, 20, 87, 104);</textarea>

var canvas = document.getElementById("canvas");
var ctx = canvas.getContext("2d");
var image = document.getElementById('source');
var textarea = document.getElementById("code");
var reset = document.getElementById("reset");
var edit = document.getElementById("edit");
var code = textarea.value;

function drawCanvas() {
  ctx.clearRect(0, 0, canvas.width, canvas.height);
  eval(textarea.value);
}

reset.addEventListener("click", function() {
  textarea.value = code;
  drawCanvas();
});

edit.addEventListener("click", function() {
  textarea.focus();
})

textarea.addEventListener("input", drawCanvas);
window.addEventListener("load", drawCanvas);

Понимание размеров изображения-источника

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

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

HTML

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

JavaScript

var canvas = document.getElementById('canvas');
var ctx = canvas.getContext('2d');

var 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.mozillademos.org/files/5397/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);
}

Результат

Спецификация

Совместимость с браузерами

We're converting our compatibility data into a machine-readable JSON format. This compatibility table still uses the old format, because we haven't yet converted the data it contains. Find out how you can help!

[1] См. баг 1360415

Дополнительно о совместимости

• Поддержка переворачивания изображения с использованием отрицательных значений sw и sh была добавлена в Gecko 5.0 (Firefox 5.0 / Thunderbird 5.0 / SeaMonkey 2.2).
• Начиная с (Firefox 5.0 / Thunderbird 5.0 / SeaMonkey 2.2), drawImage() поддерживает отрицательные значения аргументов. Таким образом, можно переворачивать изображение вокруг разных осей.
• Начиная с (Firefox 5.0 / Thunderbird 5.0 / SeaMonkey 2.2), передача null или undefined как источника для drawImage() корректно выбрасывает исключение TYPE_MISMATCH_ERR.
• Вплоть до Gecko 7.0 (Firefox 7.0 / Thunderbird 7.0 / SeaMonkey 2.4) Firefox выбрасывал исключение в случае, если какая-то из координат равнялась нулю или бесконечности. Согласно спецификации, этого больше не происходит.
• Gecko 9.0 (Firefox 9.0 / Thunderbird 9.0 / SeaMonkey 2.6) теперь корректно поддерживает CORS без необходимости "порчи" холста.
• Gecko 11.0 (Firefox 11.0 / Thunderbird 11.0 / SeaMonkey 2.8) теперь поддерживает SVG как источник для drawImage() без необходимости "порчи" холста.

Дополнительно

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

См. также

• Родительский интерфейс метода CanvasRenderingContext2D.