Signatur
Beschreibung
Der Konstruktor CSSPositionValue() gehörte zu einem frühen Entwurf der CSS Typed Object Model API (Houdini). Er erzeugt ein Objekt, das eine Position aus einem horizontalen und einem vertikalen Versatz darstellt. Solche Werte kommen bei CSS-Eigenschaften wie object-position, background-position oder transform-origin vor.
Beide Argumente müssen CSSNumericValue-Objekte sein, typischerweise erzeugt mit den Fabrikfunktionen CSS.px(), CSS.percent() oder CSS.em(). Die Werte stehen danach über die les- und schreibbaren Eigenschaften x und y des Objekts zur Verfügung.
Die Schnittstelle wurde aus der Spezifikation entfernt und war nur in Chromium hinter einem Experimentier-Flag verfügbar. In der aktuellen Typed-OM-Spezifikation werden Positionswerte als CSSStyleValue oder als Liste von CSSUnitValue-Objekten dargestellt. Den Konstruktor sollten Sie deshalb nur nach einer Feature-Erkennung verwenden. Für echten Code ist er nicht geeignet.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $x Pflicht | CSSNumericValue | Horizontaler Versatz der Position, z. B. CSS.px(10) oder CSS.percent(50). |
|
| $y Pflicht | CSSNumericValue | Vertikaler Versatz der Position, z. B. CSS.px(20) oder CSS.percent(50). |
Rückgabewert
CSSPositionValue-Objekt mit den Eigenschaften x und y.Beispiele
Feature-Erkennung vor der Verwendung
const hatPositionValue = typeof window !== 'undefined' && 'CSSPositionValue' in window;
const hatTypedOM = typeof CSS !== 'undefined' && typeof CSS.px === 'function';
console.log(`CSSPositionValue: ${hatPositionValue}, Typed OM: ${hatTypedOM}`);Position erzeugen und auslesen
if ('CSSPositionValue' in window) {
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'
} else {
console.log('CSSPositionValue wird nicht unterstützt.');
}object-position setzen mit Fallback
const img = document.querySelector('img');
const setzePosition = (el, x, y) => {
if ('CSSPositionValue' in window && el.attributeStyleMap) {
el.attributeStyleMap.set('object-position', new CSSPositionValue(CSS.px(x), CSS.px(y)));
} else {
// Fallback: klassischer String-Wert
el.style.objectPosition = `${x}px ${y}px`;
}
};
if (img) {
setzePosition(img, 20, 40);
console.log(getComputedStyle(img).objectPosition);
}// Wichtig · Fallstricke
- Veraltet und nicht verfügbar:
CSSPositionValuewurde aus der CSS-Typed-OM-Spezifikation entfernt. Kein aktueller Browser stellt die Schnittstelle standardmäßig bereit. Prüfen Sie deshalb immer zuerst mit'CSSPositionValue' in window, ob sie vorhanden ist. - Beide Argumente müssen
CSSNumericValue-Objekte sein. Übergeben Sie reine Zahlen oder Zeichenketten wie'10px', wird einTypeErrorausgelöst. - Schlüsselwörter wie
centeroderleft toplassen sich damit nicht direkt abbilden. Nur numerische Versätze sind möglich. - Robuste Alternativen sind
element.style.objectPosition = '10px 50%'oderattributeStyleMap.set('object-position', '10px 50%')mit einem String-Wert.