CSSTransformValue.forEach() — Methode · JavaScript-Referenz

Signatur

CSSTransformValue.prototype.forEach(callbackFn, thisArg)

Beschreibung

CSSTransformValue ist Teil der CSS Typed Object Model API (Houdini) und steht für den Wert der CSS-Eigenschaft transform als geordnete Liste von Transformationskomponenten, z. B. CSSTranslate, CSSRotate, CSSScale, CSSSkew, CSSPerspective oder CSSMatrixComponent. Die Methode forEach() durchläuft diese Liste in der Reihenfolge, in der die Funktionen im CSS-Wert stehen.

Das Verhalten entspricht dem von Array.prototype.forEach(): Der Callback erhält den aktuellen Eintrag, den Index und das CSSTransformValue-Objekt selbst. Weil das Interface ein sogenanntes iterables Array-ähnliches Objekt ist, gibt es außerdem entries(), keys(), values(), die Eigenschaft length und Indexzugriff wie transform[0].

Typische Einsatzfälle: Transformationen eines Elements untersuchen (etwa „Enthält das Element eine Rotation?“), einzelne Komponenten protokollieren oder gezielt verändern, bevor der Wert per element.attributeStyleMap.set() zurückgeschrieben wird. Da die Komponenten veränderbare Objekte sind, wirken Änderungen im Callback direkt auf das CSSTransformValue. Im Stil des Elements kommen sie aber erst an, wenn man den Wert erneut setzt.

Parameter

Name	Typ	Default	Beschreibung
$callbackFn Pflicht	(value: CSSTransformComponent, index: number, transformValue: CSSTransformValue) => void		Funktion, die für jede Komponente aufgerufen wird. Sie erhält `value` (die aktuelle Komponente), `index` (ihre Position) und `transformValue` (das durchlaufene Objekt).
$thisArg	any	undefined	Wert, der beim Aufruf von `callbackFn` als `this` dient. Bei Pfeilfunktionen hat er keine Wirkung.

Beispiele

CSSTransformValue erzeugen und Komponenten ausgeben

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

transform.forEach((component, index) => {
  console.log(index, component.constructor.name, component.toString());
});

0 CSSTranslate translate(10px, 20px) 1 CSSRotate rotate(45deg) 2 CSSScale scale(1.5, 1.5)

Transformation eines Elements untersuchen

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

const transform = box.attributeStyleMap.get('transform');
let hatRotation = false;

transform.forEach((component) => {
  if (component instanceof CSSRotate) {
    hatRotation = true;
    console.log(`Rotation: ${component.angle.value}${component.angle.unit}`);
  }
});

console.log('Enthält Rotation:', hatRotation);

Rotation: 30deg Enthält Rotation: true

Komponenten verändern und zurückschreiben

const card = document.querySelector('.card');
card.attributeStyleMap.set('transform', CSSStyleValue.parse('transform', 'translate(10px, 0) scale(1)'));

const transform = card.attributeStyleMap.get('transform');

// Alle Verschiebungen verdoppeln
transform.forEach((component) => {
  if (component instanceof CSSTranslate) {
    component.x = CSS.px(component.x.value * 2);
  }
});

// Erst durch erneutes Setzen wird die Änderung sichtbar
card.attributeStyleMap.set('transform', transform);
console.log(card.attributeStyleMap.get('transform').toString());

translate(20px, 0px) scale(1)

thisArg verwenden

const sammler = {
  namen: [],
  add(component) {
    this.namen.push(component.constructor.name);
  }
};

const transform = new CSSTransformValue([
  new CSSSkew(CSS.deg(10), CSS.deg(0)),
  new CSSPerspective(CSS.px(500))
]);

// Klassische Funktion, damit thisArg greift
transform.forEach(function (component) {
  this.add(component);
}, sammler);

console.log(sammler.namen);

['CSSSkew', 'CSSPerspective']

// Wichtig · Fallstricke

Browser-Kompatibilität: Das CSS Typed OM gibt es in Chromium-Browsern (ab Version 66) und in Safari (ab 16.4). Firefox unterstützt es derzeit nicht. Prüfen Sie die Verfügbarkeit mit if ('CSSTransformValue' in window) und sehen Sie einen Fallback über getComputedStyle() vor.
forEach() lässt sich nicht vorzeitig abbrechen: break ist nicht möglich und return beendet nur den aktuellen Durchlauf. Für einen Abbruch eignet sich for...of (das Objekt ist iterierbar) oder eine Umwandlung mit Array.from(transform).some(...).
Bei computedStyleMap().get('transform') hängt das Ergebnis vom Browser ab. Mitunter liefert er eine einzige CSSMatrixComponent statt der ursprünglichen Einzelfunktionen. Brauchen Sie die im Stil angegebenen Komponenten, verwenden Sie attributeStyleMap.
Hat transform den Wert none, liefert get() einen CSSKeywordValue statt eines CSSTransformValue. Dieser hat kein forEach(). Prüfen Sie deshalb vorher mit instanceof CSSTransformValue.
Änderungen an Komponenten im Callback wirken erst sichtbar, wenn der Wert mit attributeStyleMap.set() erneut gesetzt wird.

Siehe auch

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