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
(en-US)), конкретнее,CSSImageValue
(en-US),HTMLImageElement
,SVGImageElement
(en-US),HTMLVideoElement
,HTMLCanvasElement
,ImageBitmap
илиOffscreenCanvas
(en-US). 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>
<img id="source" src="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 = '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' в этой спецификации. |
Живой стандарт |
Совместимость с браузерами
BCD tables only load in the browser
Дополнительно о совместимости
- Поддержка переворачивания изображения с использованием отрицательных значений
sw
иsh
была добавлена в Gecko 5.0. - Начиная с Gecko 5.0,
drawImage()
поддерживает отрицательные значения аргументов. Таким образом, можно переворачивать изображение вокруг разных осей. - Начиная с Gecko 7.0, передача
null
илиundefined
как источника дляdrawImage()
корректно выбрасывает исключениеTYPE_MISMATCH_ERR
. - Вплоть до Gecko 7.0 Firefox выбрасывал исключение в случае, если какая-то из координат равнялась нулю или бесконечности. Согласно спецификации, этого больше не происходит.
- Gecko 9.0 теперь корректно поддерживает CORS без необходимости "порчи" холста.
- Gecko 11.0 теперь поддерживает SVG как источник для
drawImage()
без необходимости "порчи" холста.
Дополнительно
drawImage()
корректно работает сHTMLVideoElement
только в том случае, когдаHTMLMediaElement.readyState
(en-US) больше единицы (т.е., событие seek корректно вызывается после установки свойстваcurrentTime
)drawImage()
будет использовать внутренний размер элемента-источника, выраженный в CSS-пикселях, при рисовании, фрагментировании или масштабировании.drawImage()
проигнорирует все EXIF-данные изображений, в том числе иOrientation
. Такое поведение метода особенно проблематично для iOS-устройств. Вам потребуется распознать ориентацию самостоятельно и использоватьrotate()
для её корректировки.
Смотрите также
- Родительский интерфейс метода
CanvasRenderingContext2D
.