HTMLEmbedElement — Schnittstelle · JavaScript-Referenz

Signatur

interface HTMLEmbedElement extends HTMLElement

Beschreibung

Das Interface HTMLEmbedElement steht für ein <embed>-Element. Es erbt alle Eigenschaften und Methoden von HTMLElement und ergänzt sie um Eigenschaften speziell für eingebettete externe Ressourcen. Früher lief das vor allem über Plug-ins wie Flash, heute meist über PDF-Dateien, SVG-Grafiken oder andere Medientypen, die der Browser selbst darstellen kann.

Die wichtigsten Eigenschaften spiegeln die HTML-Attribute wider:

src – URL der eingebetteten Ressource (als absolute URL aufgelöst)
type – MIME-Typ der Ressource, z. B. application/pdf oder image/svg+xml
width / height – Abmessungen als Zeichenkette (z. B. "600" oder "100%")
align und name – veraltet, nur noch aus Kompatibilitätsgründen vorhanden

Zusätzlich gibt es die Methode getSVGDocument(). Ist eine SVG-Datei vom selben Ursprung eingebettet, liefert sie deren Document, sonst null.

Instanzen entstehen über document.createElement("embed") oder durch Abfragen vorhandener <embed>-Elemente. Einen direkten Konstruktoraufruf new HTMLEmbedElement() gibt es nicht, er löst einen TypeError aus. Für neue Projekte sind <iframe>, <object>, <video>, <audio> oder <img> meist die bessere Wahl, weil sie mehr Kontrolle bieten, z. B. Fallback-Inhalte oder Lade-Events.

Parameter

Name	Typ	Default	Beschreibung
$src	string	""	Eigenschaft: URL der einzubettenden Ressource. Spiegelt das Attribut `src` wider.
$type	string	""	Eigenschaft: MIME-Typ der Ressource, z. B. `application/pdf`.
$width	string	""	Eigenschaft: Breite als Zeichenkette (Pixel ohne Einheit oder Prozentangabe).
$height	string	""	Eigenschaft: Höhe als Zeichenkette.
$align	string	""	Veraltet. Ausrichtung relativ zum umgebenden Inhalt. Stattdessen CSS verwenden.
$name	string	""	Veraltet. Name des Elements.

Beispiele

PDF dynamisch einbetten

// Neues <embed>-Element erzeugen und konfigurieren
const embed = document.createElement("embed");
embed.src = "/docs/handbuch.pdf";
embed.type = "application/pdf";
embed.width = "100%";
embed.height = "600";

document.querySelector("#viewer").append(embed);

console.log(embed instanceof HTMLEmbedElement);
console.log(embed.src);

true https://example.com/docs/handbuch.pdf

Eingebettete Ressource austauschen

const embed = document.querySelector("embed#preview");

const zeigeDokument = (url, mime) => {
  embed.type = mime;
  embed.src = url; // Ändern von src lädt den Inhalt neu
};

document.querySelector("#btn-plan").addEventListener("click", () => {
  zeigeDokument("/files/lageplan.svg", "image/svg+xml");
});

Auf ein eingebettetes SVG zugreifen

const embed = document.querySelector("embed[type='image/svg+xml']");

embed.addEventListener("load", () => {
  // Funktioniert nur bei gleichem Ursprung
  const svgDoc = embed.getSVGDocument();
  if (svgDoc) {
    const kreis = svgDoc.querySelector("circle");
    kreis?.setAttribute("fill", "tomato");
    console.log("SVG angepasst");
  } else {
    console.log("Kein Zugriff auf SVG-Dokument");
  }
});

SVG angepasst

Alle Embeds prüfen und Größen auslesen

const embeds = [...document.querySelectorAll("embed")];

embeds.forEach((el) => {
  // width/height sind Strings, daher umwandeln
  const breite = Number.parseInt(el.width, 10) || el.getBoundingClientRect().width;
  console.log(`${el.type || "unbekannt"}: ${breite}px`);
});

application/pdf: 800px

// Wichtig · Fallstricke

Kein Konstruktor: new HTMLEmbedElement() wirft einen TypeError. Verwende stattdessen document.createElement("embed").
Kein Fallback-Inhalt: <embed> ist ein leeres Element. Wenn der Inhalt nicht dargestellt werden kann, sieht der Nutzer keinen Ersatzinhalt. Für Fallbacks eignet sich <object> besser.
Plug-ins: NPAPI-Plug-ins (Flash, Java) werden von keinem aktuellen Browser mehr unterstützt. Die Darstellung von PDFs hängt vom Browser ab und fehlt auf vielen Mobilgeräten.
width/height sind Zeichenketten und keine Zahlen wie bei HTMLImageElement. Für die tatsächlich dargestellte Größe getBoundingClientRect() verwenden.
Sicherheit: src nie ungeprüft aus Nutzereingaben setzen, sonst können fremde, womöglich schädliche Inhalte eingebettet werden. Per CSP lässt sich das mit object-src einschränken; object-src 'none' blockiert <embed> vollständig. getSVGDocument() liefert bei Inhalten von fremdem Ursprung null (Same-Origin-Policy).
Die Eigenschaften align und name sind veraltet. Für die Ausrichtung CSS verwenden.
Browser-Kompatibilität: Das Interface wird von allen aktuellen Browsern unterstützt.

Siehe auch

HTMLFrameSetElement HTMLLegendElement HTMLLabelElement HTMLModElement HTMLAreaElement