CanvasRenderingContext2D：drawImage() 方法

基线广泛可用

此功能已得到很好的建立，并在许多设备和浏览器版本中都能正常工作。它自以下时间起在所有浏览器中都可用： 2015 年 7 月.

Canvas 2D API 的 **CanvasRenderingContext2D.drawImage()** 方法提供了在画布上绘制图像的不同方法。

语法

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

drawImage

参数

image: 要绘制到上下文中的元素。规范允许使用任何画布图像源，具体来说，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)。

异常

InvalidStateError DOMException: 当图像没有图像数据或画布或源矩形宽度或高度为零时抛出。
TypeMismatchError DOMException: 当将 null 或 undefined 图像作为参数传递时抛出。

示例

将图像绘制到画布

此示例使用 drawImage() 方法将图像绘制到画布。

HTML

html

<canvas id="canvas"></canvas>
<div style="display:none;">
  <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

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

浏览器兼容性

BCD 表格仅在启用 JavaScript 的浏览器中加载。

注释

drawImage() 仅在 HTMLVideoElement 的 HTMLMediaElement.readyState 大于 1（即设置 currentTime 属性后触发 seek 事件）时才能正常工作。
drawImage() 在绘制、裁剪和/或缩放时始终使用源元素的 *CSS 像素中的固有大小*。
在某些旧版浏览器版本中，drawImage() 会忽略图像中的所有 EXIF 元数据，包括方向。此行为在 iOS 设备上尤其麻烦。您应该自行检测方向并使用 rotate() 进行纠正。

另请参阅

定义此方法的接口：CanvasRenderingContext2D