CSSUnparsedValue.keys() — Methode · JavaScript-Referenz

Signatur

CSSUnparsedValue.prototype.keys()

Beschreibung

Ein CSSUnparsedValue steht im CSS Typed Object Model für einen Wert, den der Browser nicht weiter auswerten konnte oder durfte. Das betrifft vor allem nicht registrierte Custom Properties (--meine-variable) und Werte, die var()-Verweise enthalten. Intern ist der Wert eine geordnete Liste von Segmenten. Jedes Segment ist entweder ein string (Rohtext) oder ein CSSVariableReferenceValue (ein var()-Verweis).

Weil CSSUnparsedValue in WebIDL als iterierbar deklariert ist, stellt es die gleichen Iterator-Methoden bereit wie ein Array: keys(), values(), entries() und forEach(). keys() gibt einen Iterator zurück, der nur die numerischen Indizes der Segmente liefert, also 0 bis length - 1.

Sinnvoll ist keys(), wenn Sie die Position eines Segments brauchen, etwa um über den Index-Zugriff (value[i]) gezielt einzelne Segmente zu ersetzen. In for...of-Schleifen, mit dem Spread-Operator oder mit Array.from() lässt sich der Iterator direkt verwenden. Brauchen Sie Index und Segment zusammen, ist entries() meist praktischer.

Rückgabewert

Typ

Iterator<number>

Beschreibung

Ein neuer Array-Iterator, der nacheinander die Indizes (number) aller Segmente liefert. Er ist selbst iterierbar und kann daher direkt in for...of oder mit [...iter] verwendet werden.

Beispiele

Indizes eines selbst erzeugten Werts auslesen

// Entspricht dem CSS-Wert: 4px var(--abstand)
const wert = new CSSUnparsedValue([
  '4px ',
  new CSSVariableReferenceValue('--abstand')
]);

for (const index of wert.keys()) {
  console.log(index);
}

0 1

Iterator in ein Array umwandeln

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

const indizes = [...wert.keys()];
console.log(indizes);
console.log(indizes.length === wert.length);

[0, 1, 2] true

var()-Verweise über ihren Index gezielt ersetzen

const wert = new CSSUnparsedValue([
  new CSSVariableReferenceValue('--farbe-alt'),
  ' solid 1px'
]);

for (const i of wert.keys()) {
  const segment = wert[i];
  if (segment instanceof CSSVariableReferenceValue && segment.variable === '--farbe-alt') {
    // Segment per Index-Zugriff durch einen neuen Verweis ersetzen
    wert[i] = new CSSVariableReferenceValue('--farbe-neu');
  }
}

document.body.attributeStyleMap.set('border', wert);
console.log(wert.toString());

var(--farbe-neu) solid 1px

Custom Property eines Elements untersuchen (mit Feature-Erkennung)

if ('CSSUnparsedValue' in window) {
  const el = document.body;
  el.style.setProperty('--schatten', '0 0 var(--blur) black');

  const wert = el.attributeStyleMap.get('--schatten');
  if (wert instanceof CSSUnparsedValue) {
    for (const i of wert.keys()) {
      console.log(i, wert[i]);
    }
  }
} else {
  console.log('CSS Typed OM wird nicht unterstützt');
}

0 "0 0 " 1 CSSVariableReferenceValue {variable: '--blur', fallback: null} 2 " black"

// Wichtig · Fallstricke

Browser-Unterstützung: Das CSS Typed OM gibt es in Chromium-Browsern ab Version 66 und in Safari ab 16.4. Firefox unterstützt es bisher nicht. Prüfen Sie deshalb vorab mit 'CSSUnparsedValue' in window, ob die API vorhanden ist.
Nur Indizes: keys() liefert keine Segmente, sondern nur deren Position. Für die Segmente selbst nutzen Sie values() oder direkt for...of auf dem Objekt, für Index und Segment zusammen entries().
Einmal verwendbar: Ein Iterator ist nach dem Durchlauf erschöpft. Für einen zweiten Durchlauf rufen Sie keys() erneut auf.
Segmentierung hängt vom Browser ab: Wie der Browser Rohtext in Zeichenketten-Segmente aufteilt, etwa bei Leerzeichen, kann je nach Engine leicht abweichen. Verlassen Sie sich daher nicht auf feste Indizes, wenn der Wert aus einem Stylesheet gelesen wird.
Registrierte Properties: Custom Properties, die mit CSS.registerProperty() oder @property einen Typ bekommen haben, liefert attributeStyleMap.get() als typisierten Wert (z. B. CSSUnitValue) zurück und nicht als CSSUnparsedValue.
Ändern Sie die Liste während der Iteration nicht in ihrer Länge. Ersetzen per Index ist unproblematisch.

Siehe auch

Array.prototype.keys() CSSUnparsedValue.values() CSSUnparsedValue.entries() CSSUnparsedValue.forEach() CSSTransformValue.keys()