CSSUnparsedValue.length — Eigenschaft · JavaScript-Referenz

Signatur

readonly CSSUnparsedValue.length

Beschreibung

Ein CSSUnparsedValue steht im CSS Typed Object Model für einen CSS-Wert, der nicht in einen bestimmten Typ zerlegt wurde, zum Beispiel den Wert einer nicht registrierten benutzerdefinierten Eigenschaft (--foo) oder einen Wert, der var() enthält. Intern ist er eine listenähnliche Folge von Fragmenten. Jedes Fragment ist entweder ein string oder ein CSSVariableReferenceValue.

Die Eigenschaft length gibt an, wie viele Fragmente diese Liste enthält. Damit kannst du die Fragmente per Index durchlaufen (value[i]), prüfen, ob ein Wert leer ist, oder zählen, wie ein Wert aufgeteilt wurde, bevor du einzelne Teile ersetzt.

length ist schreibgeschützt. Die Liste lässt sich nicht kürzen, indem man length setzt, wie es bei Arrays geht. Neue Einträge kannst du dagegen über Indexzuweisung hinzufügen, und zwar genau an der Position length. Danach steigt der Wert entsprechend.

Rückgabewert

Typ

number

Beschreibung

Eine nicht-negative Ganzzahl (unsigned long) mit der Anzahl der Fragmente im CSSUnparsedValue.

Beispiele

Länge eines selbst erzeugten Werts

// Entspricht in CSS etwa: 1px solid var(--rahmenfarbe)
const wert = new CSSUnparsedValue([
  '1px solid ',
  new CSSVariableReferenceValue('--rahmenfarbe')
]);

console.log(wert.length);
console.log(wert.toString());

2 1px solid var(--rahmenfarbe)

Fragmente per Index durchlaufen

const wert = new CSSUnparsedValue([
  'calc(',
  new CSSVariableReferenceValue('--abstand'),
  ' * 2)'
]);

for (let i = 0; i < wert.length; i++) {
  const teil = wert[i];
  const art = teil instanceof CSSVariableReferenceValue
    ? `Variable ${teil.variable}`
    : `Text "${teil}"`;
  console.log(i, art);
}

0 Text "calc(" 1 Variable --abstand 2 Text " * 2)"

Custom Property aus attributeStyleMap auslesen und erweitern

const box = document.querySelector('.box');
box.style.setProperty('--schatten', '0 0 4px var(--farbe)');

const wert = box.attributeStyleMap.get('--schatten');
if (wert instanceof CSSUnparsedValue) {
  console.log('Fragmente:', wert.length);
  // Ein Eintrag lässt sich nur genau an Position length anhängen
  wert[wert.length] = ', inset 0 0 2px black';
  console.log('Neu:', wert.length);
  box.attributeStyleMap.set('--schatten', wert);
}

Fragmente: 2 Neu: 3

Leeren Wert erkennen

const leer = new CSSUnparsedValue([]);
console.log(leer.length === 0); // true

// Zuweisung wird ignoriert (im strict mode: TypeError)
leer.length = 5;
console.log(leer.length);

true 0

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung an length wird im nicht strikten Modus einfach ignoriert. Im strict mode (also auch in ES-Modulen) wirft sie einen TypeError. Anders als bei Arrays kann man die Liste damit nicht kürzen.
Fragmente statt Zeichen: length zählt die Fragmente, nicht die Zeichen der Zeichenkette. Wie der Browser einen Wert in Text- und Variablenteile aufteilt, kann sich im Detail unterscheiden, etwa bei Leerzeichen. Verlass dich deshalb nicht auf eine fest angenommene Anzahl.
Indexzuweisung: Nur Indizes im Bereich 0 bis length sind zulässig. Liegt der Index höher, wird ein RangeError ausgelöst.
Werte ohne var(): Ein Wert wie --x: 10px ergibt meist ein einziges Textfragment (length === 1).
Kompatibilität: CSS Typed OM gibt es in Chromium-Browsern (ab 66) und in Safari (ab 16.4), in Firefox bisher nicht. Prüf die Unterstützung vorher, z. B. mit if ('CSSUnparsedValue' in window).

Siehe auch

CSSKeyframesRule.length CSSTransformValue.length CSSPerspective.length CSSUnitValue.unit CSSValueList.length