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);

drawImage

Параметры

image
Элемент для отображения в контексте. Функция принимает любой источник изображения, пригодный для отображения на холсте (CanvasImageSource), конкретнее, CSSImageValueHTMLImageElement, 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);

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

Playable code
<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);
}

Результат

 

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

 

Спецификация Статус Комментарий
HTML Living Standard
Определение 'CanvasRenderingContext2D.drawImage' в этой спецификации.
Живой стандарт  

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

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!

Функция Chrome Edge Firefox (Gecko) Internet Explorer Opera Safari
Базовая поддержка (Да) (Да) (Да) (Да) (Да) (Да)
ImageBitmap как источник (Да) Нет 42 (42) ? ? ?
SVGImageElement как источник 59 ? 56 (56) ? ? ?
Сглаживание при сжатии (Да) ? 56 (56)[1] ? (Да) ?
Функция Android Webview Chrome for Android Edge Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Базовая поддержка (Да) (Да) (Да) (Да) (Да) (Да) (Да)
ImageBitmap как источник (Да) (Да) Нет 42.0 (42) ? ? ?
SVGImageElement как источник 59 59 ? 56.0 (56) ? ? ?
Сглаживание при сжатии (Да) (Да) ? 56.0 (56)[1] ? (Да) ?

[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() для ее корректировки.

См. также

Метки документа и участники

Внесли вклад в эту страницу: nkizza
Обновлялась последний раз: nkizza,