--- title: CanvasRenderingContext2D.drawImage() slug: Web/API/CanvasRenderingContext2D/drawImage tags: - API - Canvas - CanvasRenderingContext2D - Refer translation_of: Web/API/CanvasRenderingContext2D/drawImage ---
{{APIRef}}

Canvas 2D API 中的 CanvasRenderingContext2D.drawImage() 方法提供了多种方式在Canvas上绘制图像。

语法

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);

drawImage

参数

image
绘制到上下文的元素。允许任何的 canvas 图像源({{domxref("CanvasImageSource")}})，例如：{{domxref("CSSImageValue")}}，{{domxref("HTMLImageElement")}}，{{domxref("SVGImageElement")}}，{{domxref("HTMLVideoElement")}}，{{domxref("HTMLCanvasElement")}}，{{domxref("ImageBitmap")}} 或者{{domxref("OffscreenCanvas")}}。
sx{{optional_inline}}
需要绘制到目标上下文中的，image的矩形（裁剪）选择框的左上角 X 轴坐标。
sy{{optional_inline}}
需要绘制到目标上下文中的，image的矩形（裁剪）选择框的左上角 Y 轴坐标。
sWidth{{optional_inline}}
需要绘制到目标上下文中的，image的矩形（裁剪）选择框的宽度。如果不说明，整个矩形（裁剪）从坐标的sx和sy开始，到image的右下角结束。
sHeight{{optional_inline}}
需要绘制到目标上下文中的，image的矩形（裁剪）选择框的高度。
dx
image的左上角在目标canvas上 X 轴坐标。
dy
image的左上角在目标canvas上 Y 轴坐标。
dWidth{{optional_inline}}
image在目标canvas上绘制的宽度。 允许对绘制的image进行缩放。 如果不说明， 在绘制时image宽度不会缩放。
dHeight{{optional_inline}}
image在目标canvas上绘制的高度。 允许对绘制的image进行缩放。 如果不说明， 在绘制时image高度不会缩放。

抛出异常

INDEX_SIZE_ERR
如果 canvas 或者图像矩形区域的宽度或高度为0 。
INVALID_STATE_ERR
图像没有数据。
TYPE_MISMATCH_ERR
提供的原始元素不支持。
NS_ERROR_NOT_AVAILABLE
图像尚未加载。使用.complete === true和.onload确定何时准备就绪。

示例

使用 drawImage 方法

这是一段使用 drawImage 方法的简单的代码片段。

HTML

<canvas id="canvas"></canvas>
  <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);

结果

{{ EmbedLiveSample('Drawing_an_image_to_the_canvas', 700, 180) }}

理解源元素大小

drawImage()方法在绘制时使用源元素的CSS大小。

例如，如果加载图像并在其构造函数中指定可选的大小参数，则必须使用所创建实例的naturalWidth和naturalHeight属性来正确计算裁剪和缩放区域等内容，而不是element.width和element.height。如果元素是{{htmlelement("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.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);
}

结果

{{EmbedLiveSample('Understanding_source_element_size', 700, 260)}}

规范说明

Specification Status Comment
{{SpecName('HTML WHATWG', "scripting.html#dom-context-2d-drawimage", "CanvasRenderingContext2D.drawImage")}} {{Spec2('HTML WHATWG')}}

浏览器兼容性

{{Compat("api.CanvasRenderingContext2D.drawImage")}}

兼容性注解

Notes

参见