CSSTransformComponent.is2D — Eigenschaft · JavaScript-Referenz

Signatur

CSSTransformComponent.is2D

Beschreibung

Die Eigenschaft is2D gehört zum Interface CSSTransformComponent der CSS Typed OM. Sie steht damit allen Unterklassen zur Verfügung: CSSTranslate, CSSRotate, CSSScale, CSSSkew, CSSSkewX, CSSSkewY, CSSPerspective und CSSMatrixComponent. Der Wert ist true, wenn die Komponente eine reine 2D-Transformation beschreibt (z. B. translate(), rotate()), und false bei einer 3D-Variante (z. B. translate3d(), rotate3d()).

Beim Erzeugen einer Komponente legt der Konstruktor den Anfangswert fest: Gibt man etwa bei new CSSTranslate(x, y) keinen z-Wert an, ist is2D gleich true. Mit z-Wert ist er false. Bei Werten aus element.computedStyleMap() oder attributeStyleMap spiegelt is2D die CSS-Funktion wider, aus der die Komponente entstanden ist.

Die Eigenschaft ist beschreibbar. Setzt du sie auf true, werden 3D-Anteile (z. B. die z-Achse) bei der Serialisierung mit toString() und bei der Umrechnung mit toMatrix() ignoriert. Die gespeicherten Werte bleiben aber erhalten. Das ist praktisch, wenn du eine 2D-Ausgabe erzwingen oder zwischen 2D- und 3D-Darstellung umschalten willst, ohne das Objekt neu anzulegen.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn die Komponente als 2D-Transformation behandelt wird, sonst false.

Beispiele

2D oder 3D beim Erzeugen erkennen

const flat = new CSSTranslate(CSS.px(10), CSS.px(20));
const deep = new CSSTranslate(CSS.px(10), CSS.px(20), CSS.px(5));

console.log(flat.is2D, flat.toString());
console.log(deep.is2D, deep.toString());

const rot = new CSSRotate(0, 0, 1, CSS.deg(45));
console.log(rot.is2D, rot.toString());

true "translate(10px, 20px)" false "translate3d(10px, 20px, 5px)" false "rotate3d(0, 0, 1, 45deg)"

2D-Ausgabe durch Setzen von is2D erzwingen

const move = new CSSTranslate(CSS.px(50), CSS.px(0), CSS.px(100));
console.log(move.toString());

// z-Anteil bei Ausgabe und Matrix ignorieren
move.is2D = true;
console.log(move.toString());
console.log(move.z.toString()); // Wert bleibt gespeichert

const box = document.querySelector('.box');
box.attributeStyleMap.set('transform', new CSSTransformValue([move]));

translate3d(50px, 0px, 100px) translate(50px, 0px) 100px

Berechnete Transformationen eines Elements untersuchen

const el = document.querySelector('.card');
el.style.transform = 'translateX(20px) rotateY(30deg) scale(1.2)';

const transform = el.computedStyleMap().get('transform');

if (transform instanceof CSSTransformValue) {
  for (const part of transform) {
    console.log(part.constructor.name, part.is2D ? '2D' : '3D');
  }
  // Gesamte Liste ist nur dann 2D, wenn alle Komponenten 2D sind
  console.log('Gesamt 2D:', transform.is2D);
}

Die Ausgabe hängt vom Browser ab, weil berechnete Werte als Matrix normalisiert werden können – z. B.: CSSMatrixComponent 3D Gesamt 2D: false

// Wichtig · Fallstricke

Browser-Unterstützung: CSS Typed OM gibt es in Chromium-Browsern ab Version 66 und in Safari ab 16.4 (teilweise). Firefox unterstützt sie nicht. Prüfe die Verfügbarkeit vorher, z. B. mit 'CSSTransformComponent' in window oder window.CSS?.px.
Nicht bei allen Unterklassen beschreibbar: Bei CSSSkew, CSSSkewX und CSSSkewY ist is2D immer true, bei CSSPerspective immer false. Eine Zuweisung wird dort stillschweigend ignoriert und löst keinen Fehler aus.
Werte gehen nicht verloren: Mit is2D = true wird der z-Anteil nur bei toString() und toMatrix() ausgeblendet. Setzt du die Eigenschaft wieder auf false, ist der ursprüngliche Wert wieder aktiv.
Berechnete Werte: computedStyleMap() liefert Transformationen oft als CSSMatrixComponent zurück. is2D sagt dann etwas über die Matrix (matrix() oder matrix3d()) aus, nicht über die ursprünglich geschriebenen Funktionen.
CSSTransformValue.is2D ist dagegen nur lesbar. Sie ist genau dann true, wenn alle enthaltenen Komponenten 2D sind.

Siehe auch

CSSTransformValue.is2D CSSTransformValue.length RTCIceTransport.component CSSMatrixComponent.matrix SVGTransform.matrix