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);
Отредактируйте код ниже и посмотрите, как ваши изменения отражаются на холсте:
Понимание размеров изображения-источника
Метод 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); // Размер изображения
image.onload = drawImageActualSize; // Рисуем изображение, когда оно будет загружено
// 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' в этой спецификации. |
Живой стандарт |
Совместимость с браузерами
Функция | 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()
для ее корректировки.
См. также
- Родительский интерфейс метода
CanvasRenderingContext2D
.