CanvasRenderingContext2D: drawImage() 方法

Baseline 廣泛可用 *

此特性已相當成熟,可在許多裝置和瀏覽器版本上使用。自 ⁨2015 年 7 月⁩以來,各瀏覽器均已提供此特性。

* 此特性的某些部分可能存在不同級別的支援。

CanvasRenderingContext2D.drawImage() 方法(Canvas 2D API)提供了在畫布上繪製圖像的多種方式。

語法

js
drawImage(image, dx, dy)
drawImage(image, dx, dy, dWidth, dHeight)
drawImage(image, sx, sy, sWidth, sHeight, dx, dy, dWidth, dHeight)

drawImage

引數

圖片

要在此上下文中繪製的元素。規範允許任何畫布影像源,具體來說,可以是 HTMLImageElementSVGImageElementHTMLVideoElementHTMLCanvasElementImageBitmapOffscreenCanvasVideoFrame

sx 可選

要繪製到目標上下文的源 image 的子矩形的左上角的 x 軸座標。使用 3 個或 5 個引數的語法可以省略此引數。

sy 可選

要繪製到目標上下文的源 image 的子矩形的左上角的 y 軸座標。使用 3 個或 5 個引數的語法可以省略此引數。

sWidth 可選

要繪製到目標上下文的源 image 的子矩形的寬度。如果未指定,則使用從由 sxsy 指定的座標到影像右下角的所有矩形。使用 3 個或 5 個引數的語法可以省略此引數。負值會在相反方向上擴充套件子矩形,但畫素始終會沿原始方向處理,影像不會翻轉。

sHeight 可選

要繪製到目標上下文的源 image 的子矩形的高度。使用 3 個或 5 個引數的語法可以省略此引數。負值會在相反方向上擴充套件子矩形,但畫素始終會沿原始方向處理,影像不會翻轉。

dx

在目標畫布上放置源 image 左上角的 x 軸座標。

dy

在目標畫布上放置源 image 左上角的 y 軸座標。

dWidth

在目標畫布上繪製 image 的寬度。這允許縮放繪製的影像。如果未指定,則繪製時影像寬度不會縮放。請注意,此引數不包含在 3 個引數的語法中。負值會在相反方向上擴充套件子矩形,但畫素始終會沿原始方向處理,影像不會翻轉。

dHeight

在目標畫布上繪製 image 的高度。這允許縮放繪製的影像。如果未指定,則繪製時影像高度不會縮放。請注意,此引數不包含在 3 個引數的語法中。負值會在相反方向上擴充套件子矩形,但畫素始終會沿原始方向處理,影像不會翻轉。

返回值

無(undefined)。

異常

InvalidStateError DOMException

當影像沒有影像資料,或者畫布或源矩形的寬度或高度為零時引發。

TypeMismatchError DOMException

當作為引數傳遞的影像為 nullundefined 時引發。

示例

將影像繪製到畫布

此示例使用 drawImage() 方法將影像繪製到畫布。

HTML

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。

js
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 並在其 建構函式中指定了可選的大小引數,您將必須使用建立例項的 naturalWidthnaturalHeight 屬性來正確計算裁剪和縮放區域等內容,而不是 element.widthelement.height。如果元素是 <video> 元素,那麼 videoWidthvideoHeight 也一樣,依此類推。

HTML

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

JavaScript

js
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() 僅在 HTMLVideoElementHTMLMediaElement.readyState 大於 1 時(即,在設定 currentTime 屬性後觸發了 seek 事件)才能正確工作。
  • drawImage() 在繪製、裁剪和/或縮放時將始終使用源元素的CSS 畫素的固有尺寸
  • 在某些舊版本的瀏覽器中,drawImage() 會忽略影像中的所有 EXIF 元資料,包括方向。這種行為在 iOS 裝置上尤其令人頭疼。您應該自己檢測方向並使用 rotate() 來糾正它。

另見