HTMLObjectElement — Schnittstelle · JavaScript-Referenz

Signatur

interface HTMLObjectElement extends HTMLElement

Beschreibung

Das Interface HTMLObjectElement erweitert HTMLElement um spezielle Eigenschaften und Methoden für das <object>-Element. Damit bindest du externe Ressourcen in ein Dokument ein, etwa PDF-Dateien, SVG-Grafiken, andere HTML-Dokumente oder Bilder. Je nach Ressourcentyp wird der Inhalt als verschachtelter Browsing-Kontext (wie bei einem <iframe>) oder als Bild dargestellt.

Wichtige Eigenschaften sind:

data: URL der eingebetteten Ressource (spiegelt das Attribut data).
type: MIME-Typ der Ressource, z. B. application/pdf oder image/svg+xml.
width / height: Abmessungen als Zeichenkette.
name: Name des Browsing-Kontexts, z. B. als Ziel für Links (target).
form: das zugehörige HTMLFormElement oder null (nur lesbar).
contentDocument / contentWindow: Zugriff auf das eingebettete Dokument bzw. dessen Window, sofern es same-origin ist (nur lesbar).
validity, validationMessage, willValidate: Constraint-Validation-API (ein <object> nimmt allerdings nie an der Validierung teil).

An Methoden stehen checkValidity(), reportValidity(), setCustomValidity() sowie getSVGDocument() zur Verfügung. Mit den Ereignissen load und error stellst du fest, ob das Laden geklappt hat. Kann die Ressource nicht dargestellt werden, zeigt der Browser den Inhalt zwischen <object> und </object> als Ausweichinhalt an.

In der Praxis nutzt man <object> heute vor allem, um PDFs oder SVGs mit Ausweichinhalt einzubetten. Für HTML-Dokumente ist meist <iframe> die bessere Wahl, weil es Sandboxing (sandbox) und feinere Berechtigungen unterstützt.

Rückgabewert

Typ

HTMLObjectElement

Beschreibung

Wird z. B. von document.createElement("object") oder document.querySelector("object") zurückgegeben.

Beispiele

PDF dynamisch mit Ausweichinhalt einbetten

const viewer = document.createElement("object");
viewer.data = "/docs/handbuch.pdf";
viewer.type = "application/pdf";
viewer.width = "100%";
viewer.height = "600";

// Ausweichinhalt, falls der Browser kein PDF anzeigen kann
const fallback = document.createElement("a");
fallback.href = viewer.data;
fallback.textContent = "Handbuch als PDF herunterladen";
viewer.append(fallback);

document.querySelector("#doku").append(viewer);
console.log(viewer instanceof HTMLObjectElement);

true

Ladezustand über load und error überwachen

const obj = document.querySelector("object#grafik");

const onLoad = () => console.log(`Geladen: ${obj.data}`);
const onError = () => console.warn("Ressource konnte nicht geladen werden");

obj.addEventListener("load", onLoad, { once: true });
obj.addEventListener("error", onError, { once: true });

// Ressource wechseln – löst erneutes Laden aus
obj.data = "/img/diagramm-2024.svg";

Geladen: https://example.com/img/diagramm-2024.svg

Eingebettetes SVG per contentDocument einfärben

// HTML: <object id="logo" type="image/svg+xml" data="/img/logo.svg"></object>
const logo = document.getElementById("logo");

logo.addEventListener("load", () => {
  const svgDoc = logo.contentDocument; // null bei Cross-Origin
  if (!svgDoc) {
    console.warn("Kein Zugriff – Ressource ist nicht same-origin");
    return;
  }
  svgDoc.querySelectorAll("path").forEach((p) => p.setAttribute("fill", "#0a7"));
  console.log(`${svgDoc.querySelectorAll("path").length} Pfade eingefärbt`);
});

12 Pfade eingefärbt

// Wichtig · Fallstricke

Same-Origin-Policy: contentDocument und contentWindow liefern bei Ressourcen von fremden Ursprüngen null bzw. ein stark eingeschränktes WindowProxy. Ob der Server CORS-Header setzt, spielt dafür keine Rolle.
Sicherheit: Ein eingebettetes HTML- oder SVG-Dokument von deinem eigenen Ursprung kann Skripte mit vollen Rechten ausführen. Binde deshalb keine ungeprüften, von Nutzern hochgeladenen SVGs per <object> ein, denn das öffnet eine XSS-Lücke. Nimm dafür lieber <img> (dort laufen keine Skripte) oder ein <iframe sandbox>. Über die CSP-Direktive object-src kannst du einschränken, welche Quellen erlaubt sind. Empfohlen wird object-src 'none', wenn du das Element nicht brauchst.
Veraltet: Die Eigenschaften align, archive, border, code, codeBase, codeType, declare, hspace, vspace, standby und useMap sind veraltet. Plugins wie Flash oder Java werden von keinem aktuellen Browser mehr unterstützt.
Ereignisse: Registriere load- und error-Listener, bevor du data setzt oder das Element einfügst, sonst verpasst du das Ereignis womöglich. Wie zuverlässig error ausgelöst wird, unterscheidet sich je nach Browser, etwa bei PDFs, die der Browser nicht selbst anzeigen kann.
getSVGDocument() ist ein Überbleibsel aus älteren Spezifikationen. Nutze stattdessen contentDocument.
Mobile Browser (z. B. iOS Safari) zeigen PDFs in <object> oft nur eingeschränkt an. Gib deshalb immer einen Ausweichinhalt mit Download-Link an.

Siehe auch

HTMLSelectElement HTMLOListElement HTMLOutputElement HTMLAreaElement HTMLBRElement