HTMLImageElement.crossOrigin — Eigenschaft · JavaScript-Referenz

Signatur

HTMLImageElement.crossOrigin

Beschreibung

Die Eigenschaft crossOrigin spiegelt das HTML-Attribut crossorigin eines <img>-Elements wider. Sie legt fest, ob das Bild als CORS-Anfrage geladen wird und ob der Browser dabei Anmeldedaten wie Cookies, HTTP-Authentifizierung oder Client-Zertifikate mitsendet.

Das ist vor allem dann wichtig, wenn Sie ein Bild von einer fremden Origin auf ein <canvas> zeichnen und danach die Pixeldaten auslesen wollen, etwa mit getImageData(), toDataURL() oder toBlob(), oder wenn Sie es als WebGL-Textur verwenden. Ohne CORS gilt das Canvas als „tainted“ (verunreinigt), und solche Lesezugriffe lösen einen SecurityError aus.

Mögliche Werte:

"anonymous": CORS-Anfrage ohne Anmeldedaten (Credentials-Modus same-origin). Jeder ungültige Wert und die leere Zeichenkette werden ebenfalls als "anonymous" behandelt.
"use-credentials": CORS-Anfrage mit Anmeldedaten. Der Server muss dann Access-Control-Allow-Credentials: true und eine konkrete Origin (nicht *) in Access-Control-Allow-Origin senden.
null: Das Attribut fehlt. Dann gibt es keine CORS-Anfrage, sondern einen normalen no-cors-Abruf.

Setzen Sie crossOrigin vor src. Ist das Laden schon gestartet, gilt die Einstellung erst beim nächsten Laden des Bildes.

Parameter

Name	Typ	Default	Beschreibung
$value	string \| null	null	Beim Setzen: `"anonymous"`, `"use-credentials"` oder `null`. Mit `null` wird das Attribut `crossorigin` entfernt.

Rückgabewert

Typ

string | null

Beschreibung

Den normalisierten Wert "anonymous" oder "use-credentials", oder null, wenn das Attribut fehlt. Ungültige Werte werden beim Lesen als "anonymous" zurückgegeben.

Beispiele

Fremdes Bild CORS-fähig laden und auf Canvas auslesen

const img = new Image();
// Wichtig: crossOrigin VOR src setzen
img.crossOrigin = 'anonymous';
img.src = 'https://cdn.example.com/foto.jpg';

img.addEventListener('load', () => {
  const canvas = document.createElement('canvas');
  canvas.width = img.naturalWidth;
  canvas.height = img.naturalHeight;
  const ctx = canvas.getContext('2d');
  ctx.drawImage(img, 0, 0);

  // Funktioniert nur, wenn der Server CORS-Header sendet
  const [r, g, b] = ctx.getImageData(0, 0, 1, 1).data;
  console.log(`Pixel oben links: rgb(${r}, ${g}, ${b})`);
});

img.addEventListener('error', () => {
  console.error('Bild konnte nicht (CORS-konform) geladen werden');
});

Pixel oben links: rgb(34, 87, 150)

Wert lesen und Normalisierung prüfen

const img = document.createElement('img');
console.log(img.crossOrigin);          // Attribut fehlt

img.crossOrigin = 'use-credentials';
console.log(img.crossOrigin);

img.crossOrigin = 'irgendwas';        // ungültiger Wert
console.log(img.crossOrigin);
console.log(img.getAttribute('crossorigin'));

img.crossOrigin = null;               // Attribut entfernen
console.log(img.hasAttribute('crossorigin'));

null use-credentials anonymous irgendwas false

Promise-Helfer für CORS-Bilder (z. B. für WebGL-Texturen)

const loadCorsImage = (url, withCredentials = false) =>
  new Promise((resolve, reject) => {
    const img = new Image();
    img.crossOrigin = withCredentials ? 'use-credentials' : 'anonymous';
    img.onload = () => resolve(img);
    img.onerror = () => reject(new Error(`Laden fehlgeschlagen: ${url}`));
    img.src = url;
  });

const main = async () => {
  try {
    const img = await loadCorsImage('https://assets.example.com/textur.png');
    const blob = await new Promise((res) => {
      const c = document.createElement('canvas');
      c.width = img.naturalWidth;
      c.height = img.naturalHeight;
      c.getContext('2d').drawImage(img, 0, 0);
      c.toBlob(res, 'image/png');
    });
    console.log('Blob-Größe:', blob.size);
  } catch (err) {
    console.error(err.message);
  }
};

main();

Blob-Größe: 48213

// Wichtig · Fallstricke

Reihenfolge: crossOrigin muss vor src bzw. srcset gesetzt werden. Sonst startet der Abruf ohne CORS, und das Canvas wird trotzdem „tainted“.
Server-Header nötig: Sendet der Server kein passendes Access-Control-Allow-Origin, wird das Bild bei gesetztem crossOrigin gar nicht angezeigt, und es feuert das Ereignis error. Ohne das Attribut würde das Bild zwar angezeigt, wäre aber nicht auslesbar.
Cache-Falle: Wurde dasselbe Bild vorher ohne CORS geladen (z. B. durch ein anderes <img>), kann eine zwischengespeicherte Antwort ohne CORS-Header zu Fehlern führen. Abhilfe: Der Server sendet Vary: Origin, oder Sie hängen einen Cache-Buster an die URL.
use-credentials: Die Wildcard Access-Control-Allow-Origin: * ist dann nicht erlaubt, und der Server muss Access-Control-Allow-Credentials: true senden. Aus Sicherheitsgründen nur verwenden, wenn wirklich Cookies bzw. Anmeldedaten nötig sind.
Sicherheit: Die Canvas-Sperre („tainting“) verhindert, dass Skripte fremde Bildinhalte auslesen, die zum Beispiel private, per Cookie geschützte Daten enthalten können. crossOrigin hebt diese Sperre nur auf, wenn der fremde Server per CORS ausdrücklich zustimmt.
Kompatibilität: Wird von allen modernen Browsern unterstützt. Bei data:- und blob:-URLs derselben Origin ist die Eigenschaft wirkungslos.

Siehe auch

HTMLImageElement.align HTMLImageElement.border HTMLImageElement.complete HTMLImageElement.decoding HTMLImageElement.height