HTMLEmbedElement.width — Eigenschaft · JavaScript-Referenz

Signatur

HTMLEmbedElement.width

Beschreibung

Die Eigenschaft width der Schnittstelle HTMLEmbedElement spiegelt das HTML-Attribut width des <embed>-Elements wider. Sie gibt an, wie breit die eingebettete Ressource (z. B. ein PDF, eine SVG-Grafik oder ein anderer externer Inhalt) dargestellt wird. Der Wert ist eine Längenangabe in CSS-Pixeln.

Anders als bei HTMLImageElement.width oder HTMLCanvasElement.width ist der Wert hier ein String und keine Zahl. Beim Lesen erhältst du genau den Text, der im Attribut steht – zum Beispiel "640". Fehlt das Attribut, ist der Rückgabewert ein leerer String "". Wenn du einen Wert zuweist, schreibt der Browser ihn unverändert per setAttribute('width', …) ins Attribut.

Du brauchst die Eigenschaft vor allem, wenn du eingebettete Inhalte dynamisch erzeugst oder ihre Größe per Skript anpassen willst, etwa bei einem PDF-Viewer, der sich an den Container anpasst. Für responsive Layouts ist CSS (style.width, max-width, aspect-ratio) meist die bessere Wahl, denn eine CSS-Breite überschreibt das Attribut bei der Darstellung.

Parameter

Name	Typ	Default	Beschreibung
$value	string	""	Beim Setzen: neue Breite als String, laut Spezifikation eine nicht-negative Ganzzahl in CSS-Pixeln (z. B. `"800"`). Zahlen werden automatisch in Strings umgewandelt.

Rückgabewert

Typ

string

Beschreibung

Der aktuelle Wert des width-Attributs als String oder "", wenn das Attribut fehlt. Die Eigenschaft liefert nicht die tatsächlich gerenderte Breite.

Beispiele

Breite auslesen und ändern

// HTML: <embed id="doc" src="handbuch.pdf" type="application/pdf" width="640" height="480">
const embed = document.getElementById('doc');

console.log(embed.width, typeof embed.width);

embed.width = '900';
console.log(embed.getAttribute('width'));

640 string 900

Embed-Element dynamisch mit fester Größe erzeugen

const createPdfEmbed = (url, width, height) => {
  const embed = document.createElement('embed');
  embed.src = url;
  embed.type = 'application/pdf';
  embed.width = String(width);
  embed.height = String(height);
  return embed;
};

const viewer = createPdfEmbed('/docs/rechnung.pdf', 800, 600);
document.body.append(viewer);
console.log(viewer.outerHTML);

Breite an den Container anpassen

const container = document.querySelector('.viewer');
const embed = container.querySelector('embed');

const resize = () => {
  // clientWidth ist eine Zahl, width erwartet einen String
  embed.width = String(container.clientWidth);
  // Seitenverhältnis 4:3 beibehalten
  embed.height = String(Math.round(container.clientWidth * 0.75));
};

new ResizeObserver(resize).observe(container);
resize();

Attributwert und gerenderte Breite unterscheiden

const embed = document.querySelector('embed');
embed.width = '500';
embed.style.width = '300px'; // CSS hat Vorrang bei der Darstellung

console.log(embed.width);                         // Attributwert
console.log(embed.getBoundingClientRect().width); // tatsächlich gerendert

500 300

// Wichtig · Fallstricke

String statt Zahl: Anders als bei <img> oder <canvas> gibt embed.width einen String zurück. Rechnungen wie embed.width + 100 hängen den Text an ("640100"). Wandle den Wert vorher mit Number() oder parseInt() um.
Keine Prüfung: Der Browser speichert jeden zugewiesenen Wert, auch ungültige wie "abc" oder "50%". Laut Spezifikation sind nur nicht-negative Ganzzahlen erlaubt; bei anderen Werten ist die Darstellung nicht verlässlich. Prozentangaben gehören ins CSS.
CSS hat Vorrang: Das Attribut ist nur ein Darstellungshinweis. CSS-Regeln wie width oder max-width überschreiben es. Die tatsächliche Breite liefern getBoundingClientRect(), offsetWidth oder clientWidth.
Leerer String: Ohne Attribut ist der Wert "", nicht 0 und nicht null.
Kompatibilität: Die Eigenschaft wird von allen modernen Browsern unterstützt. Ob und wie der eingebettete Inhalt angezeigt wird (z. B. PDFs in mobilen Browsern), hängt vom Browser ab. Für PDF- oder HTML-Inhalte ist <iframe> oft die robustere Wahl.

Siehe auch

HTMLEmbedElement.height HTMLEmbedElement.src HTMLEmbedElement.type HTMLImageElement.width HTMLTableElement.width