CSSPositionValue.x — Eigenschaft · JavaScript-Referenz

Signatur

CSSPositionValue.x

Beschreibung

Die Eigenschaft x gehört zum Interface CSSPositionValue aus einem frühen Entwurf der CSS Typed Object Model API (Houdini). Ein CSSPositionValue sollte Positionsangaben wie object-position oder background-position als typisiertes Objekt abbilden. x steht dabei für den Versatz entlang der horizontalen Achse, y für den Versatz entlang der vertikalen Achse.

Der Wert ist ein CSSNumericValue, meistens ein CSSUnitValue mit einer Einheit wie px, % oder em. Auch berechnete Werte wie CSSMathSum (entspricht calc()) sind möglich. Die Eigenschaft ist lesbar und beschreibbar. So lässt sich die horizontale Position ändern, ohne einen CSS-String zusammenzubauen und wieder zu zerlegen.

In der Praxis sollten Sie CSSPositionValue nicht mehr verwenden. Das Interface wurde aus der Spezifikation entfernt und ist in keinem aktuellen Browser verfügbar. Positionswerte werden heute als CSSStyleValue oder als String behandelt. Einzelne Längen lesen Sie direkt über element.computedStyleMap() und CSSUnitValue aus.

Rückgabewert

Typ

CSSNumericValue

Beschreibung

Die horizontale Komponente der Position, zum Beispiel ein CSSUnitValue mit value und unit oder ein CSSMathValue für calc()-Ausdrücke. Einem neuen Wert muss ebenfalls ein CSSNumericValue zugewiesen werden.

Beispiele

Position erzeugen und x auslesen (mit Feature-Erkennung)

if ('CSSPositionValue' in window && window.CSS?.px) {
  const pos = new CSSPositionValue(CSS.px(120), CSS.percent(50));
  console.log(pos.x.value, pos.x.unit);
  console.log(pos.x.toString());
} else {
  console.log('CSSPositionValue wird nicht unterstützt');
}

CSSPositionValue wird nicht unterstützt

Horizontale Position nachträglich verschieben

if ('CSSPositionValue' in window) {
  const pos = new CSSPositionValue(CSS.px(10), CSS.px(20));
  // x um 15px erhöhen – ergibt einen CSSNumericValue
  pos.x = pos.x.add(CSS.px(15));
  console.log(pos.x.toString()); // "25px"
} else {
  console.log('Fallback: Position als String setzen');
}

Fallback: Position als String setzen

Moderner Ersatz: object-position per String und Typed OM

const img = document.createElement('img');
document.body.append(img);

// Horizontale Position setzen – heute als String
img.style.objectPosition = '30% 50%';

if (img.attributeStyleMap) {
  const value = img.attributeStyleMap.get('object-position');
  console.log(value.toString());
} else {
  console.log(getComputedStyle(img).objectPosition);
}

30% 50%

// Wichtig · Fallstricke

Veraltet: CSSPositionValue und damit auch x wurden aus der CSS-Typed-OM-Spezifikation entfernt. Die Eigenschaft war nur in frühen Chrome-Versionen hinter einem Experimental-Flag verfügbar. Setzen Sie sie nicht in Produktionscode ein.
Prüfen Sie die Unterstützung immer vorher mit 'CSSPositionValue' in window. Ohne diese Prüfung wirft new CSSPositionValue() einen ReferenceError.
Eine Zuweisung an x erwartet einen CSSNumericValue. Ein einfacher String wie '10px' oder eine Zahl führt in der ursprünglichen Implementierung zu einem TypeError. Verwenden Sie stattdessen CSS.px(10) oder CSSNumericValue.parse('10px').
Schlüsselwörter wie left oder center lassen sich nicht direkt als x abbilden. Sie müssen vorher in Längen oder Prozentwerte umgerechnet werden, etwa center in 50%.
Heute nutzen Sie stattdessen element.attributeStyleMap und computedStyleMap(). Positionswerte werden dort als generischer CSSStyleValue geliefert.

Siehe auch

CSSPositionValue.y CSSMathMin.values CSSPositionTryRule.name CSSRotate.x CSSScale.x