在此页

• 句法
• 范例
• 规范
• 浏览器兼容性
• 注意事项
• 另请参阅
• 相关话题

CanvasRenderingContext2D.drawImage() method of the Canvas 2D API provides different ways to draw an image onto the 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);
					

参数

image

An element to draw into the context. The specification permits any canvas image source ( CanvasImageSource ), specifically, a CSSImageValue ， HTMLImageElement ， SVGImageElement ， HTMLVideoElement ， HTMLCanvasElement ， ImageBitmap ，或 OffscreenCanvas .

sx 可选

The x-axis coordinate of the top left corner of the sub-rectangle of the source image to draw into the destination context.

sy 可选

The y-axis coordinate of the top left corner of the sub-rectangle of the source image to draw into the destination context.

sWidth 可选

The width of the sub-rectangle of the source image to draw into the destination context. If not specified, the entire rectangle from the coordinates specified by sx and sy to the bottom-right corner of the image is used.

sHeight 可选

The height of the sub-rectangle of the source image to draw into the destination context.

dx

The x-axis coordinate in the destination canvas at which to place the top-left corner of the source image .

dy

The y-axis coordinate in the destination canvas at which to place the top-left corner of the source image .

dWidth 可选

The width to draw the image in the destination canvas. This allows scaling of the drawn image. If not specified, the image is not scaled in width when drawn.

dHeight 可选

The height to draw the image in the destination canvas. This allows scaling of the drawn image. If not specified, the image is not scaled in height when drawn.

Exceptions thrown

INDEX_SIZE_ERR

If the canvas or source rectangle width or height is zero.

INVALID_STATE_ERR

The image has no image data.

TYPE_MISMATCH_ERR

The specified source element isn't supported.

NS_ERROR_NOT_AVAILABLE

The image is not loaded yet. Use .complete === true and .onload to determine when it is ready.

范例

Drawing an image to the canvas

This example draws an image to the canvas using the drawImage() 方法。

HTML

<canvas id="canvas"></canvas>
<div style="display:none;">
  <img id="source"
       src="https://yari-demos.prod.mdn.mozit.cloud/files/5397/rhino.jpg"
       width="300" height="227">
</div>
					

JavaScript

The source image is taken from the coordinates (33, 71), with a width of 104 and a height of 124. It is drawn to the canvas at (21, 20), where it is given a width of 87 and a height of 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);
});
					

结果

Understanding source element size

drawImage() method uses the source element's intrinsic size in CSS pixels when drawing.

For example, if you load an 图像 and specify the optional size parameters in its constructor , you will have to use the naturalWidth and naturalHeight properties of the created instance to properly calculate things like crop and scale regions, rather than element.width and element.height . The same goes for videoWidth and videoHeight if the element is a <video> element, and so on.

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

结果

规范

规范	状态	注释
HTML 实时标准 The definition of 'CanvasRenderingContext2D: drawImage' in that specification.	实时标准

浏览器兼容性

The compatibility table on this page is generated from structured data. If you'd like to contribute to the data, please check out https://github.com/mdn/browser-compat-data and send us a pull request. 更新 GitHub 上的兼容性数据

	桌面						移动
	Chrome	Edge	Firefox	Internet Explorer	Opera	Safari	Android webview	Chrome for Android	Firefox for Android	Opera for Android	Safari on iOS	Samsung Internet
drawImage	Chrome 1	Edge 12	Firefox 1.5	IE 9	Opera 9	Safari 2	WebView Android 1	Chrome Android 18	Firefox Android 4	Opera Android 10.1	Safari iOS 1	Samsung Internet Android 1.0
ImageBitmap as source image	Chrome Yes	Edge 79	Firefox 42	IE ?	Opera ?	Safari ?	WebView Android Yes	Chrome Android Yes	Firefox Android 42	Opera Android ?	Safari iOS ?	Samsung Internet Android Yes
Smoothing when downscaling	Chrome Yes	Edge ≤79	Firefox 56 56 见 bug 1360415 了解细节。	IE ?	Opera Yes	Safari ?	WebView Android Yes	Chrome Android Yes	Firefox Android 56 56 见 bug 1360415 了解细节。	Opera Android Yes	Safari iOS ?	Samsung Internet Android Yes
SVGImageElement as source image	Chrome 59	Edge ≤79	Firefox 56	IE ?	Opera ?	Safari ?	WebView Android 59	Chrome Android 59	Firefox Android 56	Opera Android ?	Safari iOS ?	Samsung Internet Android 7.0

图例

完整支持

完整支持

兼容性未知 ?

兼容性未知

见实现注意事项。

Gecko-specific notes

• Support for flipping the image by using negative values for sw and sh was added in Gecko 5.0 (Firefox 5.0 / Thunderbird 5.0 / SeaMonkey 2.2).
• Starting with (Firefox 5.0 / Thunderbird 5.0 / SeaMonkey 2.2), drawImage() handles negative arguments in accordance with the specification, by flipping the rectangle around the appropriate axis.
• Specifying a null or undefined image when calling or drawImage() correctly throws a TYPE_MISMATCH_ERR exception starting with (Firefox 5.0 / Thunderbird 5.0 / SeaMonkey 2.2).
• Prior to Gecko 7.0 (Firefox 7.0 / Thunderbird 7.0 / SeaMonkey 2.4), Firefox threw an exception if any of the coordinate values was non-finite or zero. As per the specification, this no longer happens.
• Gecko 9.0 (Firefox 9.0 / Thunderbird 9.0 / SeaMonkey 2.6) now correctly supports CORS for drawing images across domains without tainting the canvas .
• Gecko 11.0 (Firefox 11.0 / Thunderbird 11.0 / SeaMonkey 2.8) now allows SVG-as-an-image to be drawn into a canvas without tainting the canvas .

注意事项

• drawImage() only works correctly on an HTMLVideoElement when its HTMLMediaElement.readyState is greater than 1 (i.e., seek event fired after setting the currentTime 特性)。
• drawImage() will always use the source element's intrinsic size in CSS pixels when drawing, cropping, and/or scaling.
• drawImage() will ignore all EXIF metadata in images, including the Orientation. This behavior is especially troublesome on iOS devices. You should detect the Orientation yourself and use rotate() to make it right.

另请参阅

• The interface defining this method: CanvasRenderingContext2D

元数据

• 最后修改： Jul 25, 2019

相关话题

1. CanvasRenderingContext2D
2. 特性

   1. canvas
   2. currentTransform
   3. direction
   4. fillStyle
   5. filter
   6. font
   7. globalAlpha
   8. globalCompositeOperation
   9. imageSmoothingEnabled
   10. imageSmoothingQuality
   11. lineCap
   12. lineDashOffset
   13. lineJoin
   14. lineWidth
   15. miterLimit
   16. shadowBlur
   17. shadowColor
   18. shadowOffsetX
   19. shadowOffsetY
   20. strokeStyle
   21. textAlign
   22. textBaseline
3. 方法

   1. addHitRegion()
   2. arc()
   3. arcTo()
   4. beginPath()
   5. bezierCurveTo()
   6. clearHitRegions()
   7. clearRect()
   8. clip()
   9. closePath()
   10. createImageData()
   11. createLinearGradient()
   12. createPattern()
   13. createRadialGradient()
   14. drawFocusIfNeeded()
   15. drawImage()
   16. drawWidgetAsOnScreen()
   17. drawWindow()
   18. ellipse()
   19. fill()
   20. fillRect()
   21. fillText()
   22. getImageData()
   23. getLineDash()
   24. getTransform()
   25. isPointInPath()
   26. isPointInStroke()
   27. lineTo()
   28. measureText()
   29. moveTo()
   30. putImageData()
   31. quadraticCurveTo()
   32. rect()
   33. removeHitRegion()
   34. resetTransform()
   35. restore()
   36. rotate()
   37. save()
   38. scale()
   39. scrollPathIntoView()
   40. setLineDash()
   41. setTransform()
   42. stroke()
   43. strokeRect()
   44. strokeText()
   45. transform()
   46. translate()