CSSTransformValue.keys() — Methode · JavaScript-Referenz

Signatur

CSSTransformValue.prototype.keys()

Beschreibung

CSSTransformValue gehört zum CSS Typed Object Model (Houdini) und stellt einen Wert der Eigenschaft transform als geordnete Liste von CSSTransformComponent-Objekten dar, z. B. CSSTranslate, CSSRotate oder CSSScale. Das Objekt verhält sich wie ein Array: Es hat length, einen Index-Zugriff und die Iterator-Methoden keys(), values(), entries() und forEach().

keys() gibt einen Iterator zurück, der nur die Indizes der einzelnen Transformationsfunktionen liefert, also 0 für die erste Funktion, 1 für die zweite und so weiter. Das ist praktisch, wenn Sie über die Positionen laufen und dabei per Index lesen oder gezielt einzelne Bausteine ersetzen wollen, zum Beispiel nur die Rotation in einer Kette aus translate() und rotate().

Die Reihenfolge der Indizes entspricht der Reihenfolge der Funktionen im CSS-Wert. Diese Reihenfolge ist wichtig, denn Transformationen werden in genau dieser Reihenfolge angewendet. Brauchen Sie Index und Wert zusammen, ist entries() meist die bessere Wahl.

Rückgabewert

Typ

Iterator<number>

Beschreibung

Ein neuer Array-Iterator, der die Indizes 0 bis length - 1 liefert. Er lässt sich mit for...of, dem Spread-Operator oder Array.from() nutzen.

Beispiele

Indizes eines selbst erzeugten Transform-Werts auflisten

const transform = new CSSTransformValue([
  new CSSTranslate(CSS.px(10), CSS.px(20)),
  new CSSRotate(CSS.deg(45)),
  new CSSScale(1.5, 1.5)
]);

for (const index of transform.keys()) {
  console.log(index, transform[index].constructor.name);
}

console.log([...transform.keys()]);

0 CSSTranslate 1 CSSRotate 2 CSSScale [0, 1, 2]

Rotation in einem vorhandenen transform gezielt ersetzen

const box = document.querySelector('.box');
box.style.transform = 'translateX(50px) rotate(10deg)';

const value = box.attributeStyleMap.get('transform');

if (value instanceof CSSTransformValue) {
  for (const i of value.keys()) {
    if (value[i] instanceof CSSRotate) {
      value[i] = new CSSRotate(CSS.deg(90)); // nur die Rotation tauschen
    }
  }
  box.attributeStyleMap.set('transform', value);
  console.log(box.style.transform);
}

translateX(50px) rotate(90deg)

Unterstützung prüfen und Positionen sammeln

const getTransformIndices = (element) => {
  if (!('computedStyleMap' in Element.prototype)) {
    return []; // Typed OM nicht verfügbar (z. B. Firefox)
  }
  const value = element.computedStyleMap().get('transform');
  // Bei transform: none kommt ein CSSKeywordValue zurück
  return value instanceof CSSTransformValue ? Array.from(value.keys()) : [];
};

console.log(getTransformIndices(document.body));

[] (wenn body kein transform hat)

// Wichtig · Fallstricke

Browser-Unterstützung: Das CSS Typed OM gibt es in Chromium-Browsern (ab Chrome/Edge 66) und in Safari (ab 16.4). Firefox unterstützt CSSTransformValue nicht. Prüfen Sie deshalb vorher, ob die API vorhanden ist, etwa mit 'CSSTransformValue' in window, und sehen Sie einen Fallback über element.style.transform vor.
computedStyleMap().get('transform') gibt nicht immer einen CSSTransformValue zurück. Bei transform: none kommt ein CSSKeywordValue, und der hat kein keys(). Prüfen Sie den Typ daher immer mit instanceof.
Der Iterator liefert nur Indizes, keine Transformations-Objekte. Für die Werte verwenden Sie values() oder direkt for...of auf dem Objekt, für Paare aus Index und Wert entries().
Wenn Sie einen Baustein per Index ändern, ändert sich nur das JavaScript-Objekt. Damit die Änderung auf der Seite sichtbar wird, müssen Sie den Wert mit attributeStyleMap.set() zurückschreiben.
Ein bereits verbrauchter Iterator lässt sich nicht zurücksetzen. Für einen zweiten Durchlauf rufen Sie keys() erneut auf.

Siehe auch

CSSTransformValue CSSTransformValue.values() CSSTransformValue.entries() CSSTransformValue.forEach() CSSTransformValue.length CSSTransformComponent Array.prototype.keys()