CSSTransformValue.is2D — Eigenschaft · JavaScript-Referenz

Signatur

CSSTransformValue.is2D

Beschreibung

is2D gehört zum CSS Typed Object Model (Typed OM). Die Eigenschaft sagt Ihnen, ob eine Transformationsliste als Ganzes nur in der Ebene wirkt (2D) oder ob sie eine dritte Dimension (z-Achse) nutzt. Ein CSSTransformValue ist eine Liste von CSSTransformComponent-Objekten wie CSSTranslate, CSSRotate, CSSScale, CSSSkew, CSSPerspective oder CSSMatrixComponent.

Der Wert wird aus den einzelnen Komponenten berechnet. is2D ist nur dann true, wenn jede Komponente der Liste selbst is2D === true meldet. Schon eine einzige 3D-Komponente macht das Ergebnis false, zum Beispiel translate3d(), rotate3d(), scale3d() oder perspective().

Typische Einsatzfälle:

Sie wollen vor dem Umrechnen in eine Matrix mit toMatrix() entscheiden, ob eine 2D-Matrix reicht.
Sie wollen 3D-Effekte in Animationen oder Editoren erkennen, etwa um transform-style oder perspective auf dem Elternelement zu setzen.
Sie wollen Transformationen prüfen, die Sie über element.computedStyleMap() oder attributeStyleMap ausgelesen haben.

Die Eigenschaft ist schreibgeschützt. Wenn Sie etwas ändern wollen, setzen Sie das (beschreibbare) is2D der einzelnen Komponenten.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn alle enthaltenen Transformationskomponenten 2D sind. false, sobald mindestens eine Komponente 3D ist.

Beispiele

2D- und 3D-Transformationslisten vergleichen

// Nur 2D-Komponenten
const flat = new CSSTransformValue([
  new CSSTranslate(CSS.px(10), CSS.px(20)),
  new CSSRotate(CSS.deg(45))
]);
console.log(flat.is2D);

// Eine 3D-Komponente (translate mit z-Wert) macht die ganze Liste 3D
const deep = new CSSTransformValue([
  new CSSTranslate(CSS.px(10), CSS.px(20), CSS.px(5)),
  new CSSRotate(CSS.deg(45))
]);
console.log(deep.is2D);
console.log(deep.toString());

true false translate3d(10px, 20px, 5px) rotate(45deg)

Berechnete Transformation eines Elements prüfen

const card = document.querySelector('.card');
card.style.transform = 'rotateY(30deg) translateX(40px)';

const value = card.computedStyleMap().get('transform');

// Bei transform: none kommt ein CSSKeywordValue zurück, kein CSSTransformValue
if (value instanceof CSSTransformValue) {
  if (!value.is2D) {
    // Für 3D-Effekte braucht das Elternelement eine Perspektive
    card.parentElement.style.perspective = '800px';
  }
  console.log(`3D-Transformation: ${!value.is2D}`);
}

3D-Transformation: true

Komponenten einzeln auswerten und in eine Matrix umrechnen

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

for (const component of transform) {
  console.log(component.constructor.name, component.is2D);
}

console.log('Gesamt 2D:', transform.is2D);

const matrix = transform.toMatrix();
console.log('Matrix 2D:', matrix.is2D);

CSSScale true CSSSkew true CSSPerspective false Gesamt 2D: false Matrix 2D: false

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung wie value.is2D = true hat keine Wirkung (im Strict Mode gibt es einen TypeError). Beschreibbar ist nur CSSTransformComponent.is2D auf den einzelnen Komponenten.
Komponenten-Flag erzwingen: Setzen Sie bei einem CSSTranslate mit z-Wert is2D = true, wird der z-Anteil beim Serialisieren und bei toMatrix() ignoriert. Das Objekt behält den Wert trotzdem. Das kann zu überraschenden Ergebnissen führen.
perspective() ist immer 3D: CSSPerspective meldet stets is2D === false. Eine Liste mit Perspektive ist deshalb nie 2D, auch wenn alle anderen Komponenten flach sind.
transform: none: computedStyleMap().get('transform') gibt dann einen CSSKeywordValue zurück. Prüfen Sie vor dem Zugriff auf is2D mit instanceof CSSTransformValue.
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 nicht. Prüfen Sie die Unterstützung zum Beispiel mit 'CSSTransformValue' in window und greifen Sie sonst auf getComputedStyle() mit DOMMatrix zurück.

Siehe auch

CSSTransformValue.length CSSTransformComponent.is2D CSSTranslate.x CSSTranslate.y CSSTranslate.z