CanvasRenderingContext2D: drawImage() 方法
Baseline 廣泛可用 *
CanvasRenderingContext2D.drawImage() 方法(Canvas 2D API)提供了在畫布上繪製圖像的多種方式。
語法
drawImage(image, dx, dy)
drawImage(image, dx, dy, dWidth, dHeight)
drawImage(image, sx, sy, sWidth, sHeight, dx, dy, dWidth, dHeight)

引數
圖片-
要在此上下文中繪製的元素。規範允許任何畫布影像源,具體來說,可以是
HTMLImageElement、SVGImageElement、HTMLVideoElement、HTMLCanvasElement、ImageBitmap、OffscreenCanvas或VideoFrame。 sx可選-
要繪製到目標上下文的源
image的子矩形的左上角的 x 軸座標。使用 3 個或 5 個引數的語法可以省略此引數。 sy可選-
要繪製到目標上下文的源
image的子矩形的左上角的 y 軸座標。使用 3 個或 5 個引數的語法可以省略此引數。 sWidth可選-
要繪製到目標上下文的源
image的子矩形的寬度。如果未指定,則使用從由sx和sy指定的座標到影像右下角的所有矩形。使用 3 個或 5 個引數的語法可以省略此引數。負值會在相反方向上擴充套件子矩形,但畫素始終會沿原始方向處理,影像不會翻轉。 sHeight可選-
要繪製到目標上下文的源
image的子矩形的高度。使用 3 個或 5 個引數的語法可以省略此引數。負值會在相反方向上擴充套件子矩形,但畫素始終會沿原始方向處理,影像不會翻轉。 dx-
在目標畫布上放置源
image左上角的 x 軸座標。 dy-
在目標畫布上放置源
image左上角的 y 軸座標。 dWidth-
在目標畫布上繪製
image的寬度。這允許縮放繪製的影像。如果未指定,則繪製時影像寬度不會縮放。請注意,此引數不包含在 3 個引數的語法中。負值會在相反方向上擴充套件子矩形,但畫素始終會沿原始方向處理,影像不會翻轉。 dHeight-
在目標畫布上繪製
image的高度。這允許縮放繪製的影像。如果未指定,則繪製時影像高度不會縮放。請注意,此引數不包含在 3 個引數的語法中。負值會在相反方向上擴充套件子矩形,但畫素始終會沿原始方向處理,影像不會翻轉。
返回值
無(undefined)。
異常
InvalidStateErrorDOMException-
當影像沒有影像資料,或者畫布或源矩形的寬度或高度為零時引發。
TypeMismatchErrorDOMException-
當作為引數傳遞的影像為
null或undefined時引發。
示例
將影像繪製到畫布
此示例使用 drawImage() 方法將影像繪製到畫布。
HTML
<canvas id="canvas"></canvas>
<div class="hidden">
<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。如果元素是 <video> 元素,那麼 videoWidth 和 videoHeight 也一樣,依此類推。
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);
}
結果
規範
| 規範 |
|---|
| HTML # dom-context-2d-drawimage-dev |
瀏覽器相容性
載入中…
注意
drawImage()僅在HTMLVideoElement的HTMLMediaElement.readyState大於 1 時(即,在設定currentTime屬性後觸發了 seek 事件)才能正確工作。drawImage()在繪製、裁剪和/或縮放時將始終使用源元素的CSS 畫素的固有尺寸。- 在某些舊版本的瀏覽器中,
drawImage()會忽略影像中的所有 EXIF 元資料,包括方向。這種行為在 iOS 裝置上尤其令人頭疼。您應該自己檢測方向並使用rotate()來糾正它。
另見
- 定義此方法的介面:
CanvasRenderingContext2D