CSSPositionTryDescriptors — Schnittstelle · JavaScript-Referenz

Signatur

interface CSSPositionTryDescriptors extends CSSStyleDeclaration

Beschreibung

CSSPositionTryDescriptors gehört zur CSS Anchor Positioning-API. Mit einer @position-try --name { … }-Regel legt man alternative Positionen („Fallback-Optionen“) fest. Ein am Anker positioniertes Element wechselt zu einer dieser Optionen, wenn es mit der Standardposition aus seinem Container herausragen würde. Das Interface bildet genau die Deskriptoren ab, die in so einer Regel erlaubt sind. Im CSSOM erreicht man es über die Eigenschaft style eines CSSPositionTryRule-Objekts.

Da das Interface von CSSStyleDeclaration erbt, funktionieren alle bekannten Methoden wie getPropertyValue(), setProperty(), removeProperty() und cssText. Dazu kommen eigene Eigenschaften, jeweils in camelCase- und Bindestrich-Schreibweise (z. B. positionArea und "position-area"):

Einfügungen (Inset): top, right, bottom, left, inset, insetBlock, insetBlockStart, insetBlockEnd, insetInline, insetInlineStart, insetInlineEnd
Außenabstände: margin, marginTop, marginRight, marginBottom, marginLeft sowie die logischen Varianten marginBlock* und marginInline*
Größen: width, height, minWidth, minHeight, maxWidth, maxHeight, blockSize, inlineSize, minBlockSize, maxBlockSize, minInlineSize, maxInlineSize
Ausrichtung: alignSelf, justifySelf, placeSelf
Anker: positionAnchor, positionArea

Das Interface braucht man, wenn Fallback-Positionen zur Laufzeit gelesen oder verändert werden sollen. Beispiele sind ein Tooltip-System mit einstellbarem Abstand oder Entwicklerwerkzeuge, die Stylesheets untersuchen. Einen eigenen Konstruktor gibt es nicht. Instanzen entstehen immer über eine @position-try-Regel im Stylesheet.

Rückgabewert

Typ

CSSPositionTryDescriptors

Beschreibung

Wird über CSSPositionTryRule.style geliefert. Alle Deskriptor-Eigenschaften sind Zeichenketten (string). Ist ein Deskriptor nicht gesetzt, ist die Zeichenkette leer.

Beispiele

Deskriptoren einer @position-try-Regel auslesen

// CSS im Dokument:
// @position-try --unten { top: anchor(bottom); left: anchor(left); margin-top: 8px; }

const findePositionTry = (name) => {
  for (const sheet of document.styleSheets) {
    for (const rule of sheet.cssRules) {
      if (rule instanceof CSSPositionTryRule && rule.name === name) {
        return rule;
      }
    }
  }
  return null;
};

const rule = findePositionTry('--unten');
const desc = rule.style; // CSSPositionTryDescriptors

console.log(desc.top);
console.log(desc['margin-top']);
console.log(desc.width === '');

anchor(bottom) 8px true

Regel per insertRule anlegen und Abstand dynamisch ändern

const style = document.createElement('style');
document.head.append(style);
const sheet = style.sheet;

const index = sheet.insertRule(`
  @position-try --oben {
    position-area: top;
    margin-bottom: 4px;
  }
`);

const desc = sheet.cssRules[index].style;

// Abstand zur Laufzeit anpassen, z. B. über eine Nutzereinstellung
const setzeAbstand = (px) => {
  desc.marginBottom = `${px}px`;
};

setzeAbstand(12);
console.log(desc.positionArea, desc.marginBottom);

top 12px

Geerbte CSSStyleDeclaration-Methoden nutzen

const rule = [...document.styleSheets[0].cssRules]
  .find((r) => r instanceof CSSPositionTryRule);

const desc = rule.style;

desc.setProperty('max-height', '50vh');
desc.removeProperty('margin-top');

console.log(desc.getPropertyValue('max-height'));
console.log(desc.cssText);

50vh top: anchor(bottom); left: anchor(left); max-height: 50vh;

// Wichtig · Fallstricke

Browser-Unterstützung: Bisher nur in Chromium-Browsern (Chrome/Edge ab 125) verfügbar. Vorher auf Unterstützung prüfen, z. B. mit 'CSSPositionTryRule' in window oder CSS.supports('position-area: top').
Nur erlaubte Deskriptoren: Eigenschaften, die in @position-try nicht vorgesehen sind (z. B. color, padding), werden beim Parsen verworfen. setProperty() ignoriert sie ohne Fehlermeldung.
Kein !important: Innerhalb von @position-try sind Deklarationen mit !important ungültig und werden verworfen.
Umbenennung: In frühen Entwürfen hieß der Deskriptor inset-area statt position-area. Ältere Chrome-Versionen kennen deshalb nur insetArea.
Cross-Origin-Stylesheets: Wird ein Stylesheet von einer fremden Domain ohne CORS geladen, löst der Zugriff auf cssRules einen SecurityError aus.
Die Fallback-Option wird erst wirksam, wenn das positionierte Element sie über position-try-fallbacks (früher position-try-options) einbindet.

Siehe auch

CSSFunctionDescriptors CSSFontFaceDescriptors CSSPageDescriptors CSSPositionTryRule AudioParamDescriptor