Signatur
Beschreibung
CSSPositionValue war Teil früher Entwürfe der CSS Typed Object Model API. Das Interface sollte Werte von CSS-Eigenschaften, die eine Position erwarten (etwa object-position), als typisiertes Objekt statt als Zeichenkette darstellen. Eine Position besteht dabei aus zwei Achsen: x für die horizontale und y für die vertikale Verschiebung, beide jeweils als CSSNumericValue (z. B. CSS.px(10) oder CSS.percent(50)).
Die Idee dahinter: Statt Strings wie "10px 50%" zusammenzubauen und wieder zu zerlegen, arbeitet man mit echten Zahlen und Einheiten. Das spart Parsing, vermeidet Tippfehler und erlaubt Berechnungen, zum Beispiel über CSSNumericValue.add().
Wichtig: CSSPositionValue wurde aus der Spezifikation entfernt und ist in aktuellen Browsern nicht verfügbar. Chrome hatte das Interface nur zeitweise hinter einem experimentellen Flag. Positionswerte gibt die Typed OM heute als allgemeines CSSStyleValue zurück. Für neuen Code solltest du CSSPositionValue nicht verwenden. Greife stattdessen auf element.attributeStyleMap mit Zeichenketten bzw. CSSStyleValue.parse() zurück oder nutze die klassische style-Eigenschaft.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $x Pflicht | CSSNumericValue | Konstruktor-Argument: horizontale Position, z. B. CSS.px(10) oder CSS.percent(50). Ist danach über die Eigenschaft x les- und schreibbar. |
|
| $y Pflicht | CSSNumericValue | Konstruktor-Argument: vertikale Position, z. B. CSS.em(2). Ist danach über die Eigenschaft y les- und schreibbar. |
Rückgabewert
new CSSPositionValue(x, y) lieferte ein Objekt mit den Eigenschaften x und y (jeweils CSSNumericValue). Mit toString() wird daraus die CSS-Schreibweise, z. B. "10px 50%".Beispiele
Feature-Erkennung vor der Nutzung
// Prüfen, ob CSSPositionValue überhaupt existiert
const hasPositionValue = typeof window.CSSPositionValue === 'function';
const hasTypedOM = typeof window.CSS !== 'undefined' && typeof CSS.px === 'function';
console.log('CSSPositionValue:', hasPositionValue);
console.log('CSS Typed OM:', hasTypedOM);Instanziierung und Zugriff auf x/y (historische API, mit Rückfalllösung)
const img = document.querySelector('img') ?? document.createElement('img');
if (typeof window.CSSPositionValue === 'function') {
// Historische API aus frühen Entwürfen
const pos = new CSSPositionValue(CSS.px(10), CSS.percent(50));
console.log(pos.x.value, pos.x.unit); // 10 'px'
console.log(pos.y.value, pos.y.unit); // 50 'percent'
img.attributeStyleMap.set('object-position', pos);
} else {
// Heute: als String setzen
img.style.objectPosition = '10px 50%';
}
console.log(img.style.objectPosition);Moderne Alternative: Position mit Typed-OM-Werten berechnen
const img = document.createElement('img');
document.body.append(img);
// Einzelwerte typisiert berechnen, dann als String setzen
const x = CSS.px(10).add(CSS.px(15)); // 25px
const y = CSS.percent(50);
if (img.attributeStyleMap) {
img.attributeStyleMap.set('object-position', `${x} ${y}`);
const value = img.attributeStyleMap.get('object-position');
console.log(value.constructor.name, value.toString());
} else {
img.style.objectPosition = `${x} ${y}`;
}// Wichtig · Fallstricke
- Veraltet und nicht verfügbar:
CSSPositionValuewurde aus der Spezifikation CSS Typed OM Level 1 gestrichen. Aktuelle Versionen von Chrome, Edge, Firefox und Safari stellen das Interface nicht bereit. Ein Aufruf vonnew CSSPositionValue()löst deshalb einenReferenceErroraus. - Prüfe das Interface immer mit
typeof window.CSSPositionValue === 'function', bevor du es verwendest, und sieh eine Zeichenketten-Variante als Rückfalllösung vor. attributeStyleMap.get('object-position')liefert heute ein allgemeinesCSSStyleValueohnex/y. Einzelne Koordinaten musst du bei Bedarf selbst austoString()auslesen.- Die CSS Typed OM selbst (
CSS.px(),attributeStyleMap) wird in Chromium-Browsern und seit Safari 16.4 unterstützt, in Firefox bisher nicht. Auch hier ist eine Feature-Erkennung sinnvoll.