CanvasRenderingContext2D: drawImage() Methode

Syntax

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

Parameter

image

Ein Element, das in den Kontext gezeichnet werden soll. Die Spezifikation erlaubt jede Canvas-Bildquelle, insbesondere ein HTMLImageElement, ein SVGImageElement, ein HTMLVideoElement, ein HTMLCanvasElement, ein ImageBitmap, ein OffscreenCanvas oder ein VideoFrame.

sx Optional

Die x-Achsenkoordinate der oberen linken Ecke des Unterrechtecks der Quell-image, das in den Zielkontext gezeichnet werden soll. Verwenden Sie die 3- oder 5-Argument-Syntax, um dieses Argument zu weglassen.

sy Optional

Die y-Achsenkoordinate der oberen linken Ecke des Unterrechtecks der Quell-image, das in den Zielkontext gezeichnet werden soll. Verwenden Sie die 3- oder 5-Argument-Syntax, um dieses Argument zu weglassen.

sWidth Optional

Die Breite des Unterrechtecks der Quell-image, das in den Zielkontext gezeichnet werden soll. Wenn nicht angegeben, wird das gesamte Rechteck von den durch sx und sy angegebenen Koordinaten bis zur unteren rechten Ecke des Bildes verwendet. Verwenden Sie die 3- oder 5-Argument-Syntax, um dieses Argument zu weglassen. Negative Werte vergrößern das Unterrechteck in die entgegengesetzte Richtung, aber die Pixel werden immer in der ursprünglichen Richtung verarbeitet, und das Bild wird nicht gespiegelt.

sHeight Optional

Die Höhe des Unterrechtecks der Quell-image, das in den Zielkontext gezeichnet werden soll. Verwenden Sie die 3- oder 5-Argument-Syntax, um dieses Argument zu weglassen. Negative Werte vergrößern das Unterrechteck in die entgegengesetzte Richtung, aber die Pixel werden immer in der ursprünglichen Richtung verarbeitet, und das Bild wird nicht gespiegelt.

dx

Die x-Achsenkoordinate im Ziel-Canvas, an der die obere linke Ecke des Quell-image platziert werden soll.

dy

Die y-Achsenkoordinate im Ziel-Canvas, an der die obere linke Ecke des Quell-image platziert werden soll.

dWidth

Die Breite, um das image im Ziel-Canvas zu zeichnen. Dies ermöglicht die Skalierung des gezeichneten Bildes. Wenn nicht angegeben, wird das Bild beim Zeichnen in der Breite nicht skaliert. Beachten Sie, dass dieses Argument in der 3-Argument-Syntax nicht enthalten ist. Negative Werte vergrößern das Unterrechteck in die entgegengesetzte Richtung, aber die Pixel werden immer in der ursprünglichen Richtung verarbeitet, und das Bild wird nicht gespiegelt.

dHeight

Die Höhe, um das image im Ziel-Canvas zu zeichnen. Dies ermöglicht die Skalierung des gezeichneten Bildes. Wenn nicht angegeben, wird das Bild beim Zeichnen in der Höhe nicht skaliert. Beachten Sie, dass dieses Argument in der 3-Argument-Syntax nicht enthalten ist. Negative Werte vergrößern das Unterrechteck in die entgegengesetzte Richtung, aber die Pixel werden immer in der ursprünglichen Richtung verarbeitet, und das Bild wird nicht gespiegelt.

Rückgabewert

Keiner (undefined).

Ausnahmen

InvalidStateError DOMException

Wird ausgelöst, wenn das Bild keine Bilddaten hat oder wenn die Breite oder Höhe des Canvas- oder Quellrechtecks Null ist.

TypeMismatchError DOMException

Wird ausgelöst, wenn ein null oder undefined Bild als Parameter übergeben wird.

Beispiele

Ein Bild auf die Leinwand zeichnen

Dieses Beispiel zeichnet ein Bild auf die Leinwand unter Verwendung der drawImage()-Methode.

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>

.hidden {
  display: none;
}

JavaScript

Das Quellbild wird von den Koordinaten (33, 71) mit einer Breite von 104 und einer Höhe von 124 genommen. Es wird auf die Leinwand bei (21, 20) gezeichnet, wobei es eine Breite von 87 und eine Höhe von 104 erhält.

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

Ergebnis

Verständnis der Quellgröße eines Elements

Die drawImage()-Methode verwendet die intrinsische Größe in CSS-Pixel des Quell-Elements beim Zeichnen.

Wenn Sie beispielsweise ein Image laden und die optionalen Größenparameter im Konstruktor angeben, müssen Sie die naturalWidth und naturalHeight Eigenschaften der erstellten Instanz verwenden, um Dinge wie Zuschneidungen und Skalierungsbereiche korrekt zu berechnen, anstatt element.width und element.height. Das Gleiche gilt für videoWidth und videoHeight, wenn das Element ein <video>-Element ist, und so weiter.

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

Ergebnis

Spezifikationen

Browser-Kompatibilität

Anmerkungen

• drawImage() funktioniert nur korrekt mit einem HTMLVideoElement, wenn dessen HTMLMediaElement.readyState größer als 1 ist (d.h. das seek-Ereignis wurde nach dem Setzen der currentTime-Eigenschaft ausgelöst).
• drawImage() verwendet immer die intrinsische Größe in CSS-Pixel des Quell-Elements beim Zeichnen, Zuschneiden und/oder Skalieren.
• In einigen älteren Browserversionen ignoriert drawImage() alle EXIF-Metadaten in Bildern, einschließlich der Orientierung. Dieses Verhalten ist insbesondere auf iOS-Geräten problematisch. Sie sollten die Orientierung selbst erkennen und rotate() verwenden, um sie zu korrigieren.

Siehe auch

• Das Interface, das diese Methode definiert: CanvasRenderingContext2D