StylePropertyMap.append() — Methode · JavaScript-Referenz

Signatur

StylePropertyMap.prototype.append(property, ...values)

Beschreibung

append() gehört zur CSS Typed OM. Die Methode erweitert die vorhandenen Werte einer Eigenschaft mit Listenwerten, statt sie zu ersetzen. Listenwerte haben Eigenschaften, deren Grammatik eine kommagetrennte Liste erlaubt, etwa transition-property, transition-duration, animation-name, background-image oder mask-image.

Normalerweise ruft man die Methode über element.attributeStyleMap auf, also über die Inline-Styles eines Elements, oder über CSSStyleRule.styleMap für Regeln in einem Stylesheet. element.computedStyleMap() gibt dagegen eine schreibgeschützte StylePropertyMapReadOnly zurück, die kein append() hat.

Als Werte gehen typisierte Objekte wie CSSUnitValue (z. B. aus CSS.s(1) oder CSS.ms(200)) und CSSKeywordValue, aber auch einfache CSS-Strings, die der Browser selbst parst. So lassen sich Übergänge, Animationen oder Hintergrundebenen schrittweise aufbauen, ohne kommagetrennte Strings selbst zusammenzusetzen und wieder zu zerlegen.

Parameter

Name	Typ	Default	Beschreibung
$property Pflicht	string		Name der CSS-Eigenschaft in CSS-Schreibweise, z. B. `'transition-duration'`. Es muss eine Eigenschaft mit Listenwerten sein.
$...values Pflicht	CSSStyleValue \| string		Ein oder mehrere Werte, die ans Ende der Liste gehängt werden. Strings werden als CSS-Werte für die Eigenschaft geparst.

Rückgabewert

Typ

undefined

Beschreibung

Kein Rückgabewert. Die Map wird direkt verändert, und bei attributeStyleMap auch das style-Attribut des Elements.

Beispiele

Übergänge schrittweise ergänzen

const button = document.querySelector('button');
const styles = button.attributeStyleMap;

styles.set('transition-property', 'opacity');
styles.set('transition-duration', CSS.ms(200));

// Weitere Übergänge anhängen, statt die Liste zu überschreiben
styles.append('transition-property', 'transform');
styles.append('transition-duration', CSS.s(0.5));

console.log(button.style.transitionProperty);
console.log(button.style.transitionDuration);

opacity, transform 200ms, 0.5s

Mehrere Hintergrundebenen auf einmal anhängen

const card = document.querySelector('.card');

card.attributeStyleMap.set('background-image', 'url("muster.svg")');
card.attributeStyleMap.append(
  'background-image',
  'linear-gradient(to bottom, #fff, #eee)',
  'url("rauschen.png")'
);

console.log(card.attributeStyleMap.getAll('background-image').length);

3

Fehler bei Eigenschaften ohne Listenwerte abfangen

const box = document.querySelector('.box');

try {
  // 'color' hat keine Listenwerte, daher TypeError
  box.attributeStyleMap.append('color', 'red');
} catch (err) {
  console.log(err.name);
}

// Unterstützung vor der Nutzung prüfen
const supported = 'attributeStyleMap' in HTMLElement.prototype;
console.log(supported ? 'Typed OM verfügbar' : 'Fallback auf element.style');

TypeError Typed OM verfügbar

// Wichtig · Fallstricke

TypeError: Er wird geworfen, wenn die Eigenschaft keine Listenwerte hat (z. B. color, width), wenn es eine benutzerdefinierte Eigenschaft (--foo) ist oder wenn ein Wert für die Eigenschaft ungültig ist.
Kurzschreibweisen wie transition oder background lassen sich nicht zuverlässig per append() erweitern. Verwende die Einzeleigenschaften.
Zusammengehörige Listen (z. B. transition-property und transition-duration) werden nicht automatisch abgeglichen. Achte selbst darauf, dass sie gleich lang sind, damit die Werte richtig zugeordnet werden.
computedStyleMap() ist schreibgeschützt und hat kein append().
Kompatibilität: CSS Typed OM gibt es in Chromium-Browsern seit Version 66 und in Safari ab 16.4. Firefox unterstützt sie bislang nicht. Prüfe vorher, ob attributeStyleMap vorhanden ist, und greife sonst auf element.style zurück.

Siehe auch

StylePropertyMap.clear() StylePropertyMap.delete() StylePropertyMap.set() StylePropertyMapReadOnly.get() StylePropertyMapReadOnly.has()