CSSPositionTryRule.name — Eigenschaft · JavaScript-Referenz

Signatur

CSSPositionTryRule.name

Beschreibung

Die Eigenschaft name der Schnittstelle CSSPositionTryRule gibt den Namen einer benutzerdefinierten Ausweichposition (position-try fallback option) zurück. Diesen Namen legt man in CSS mit @position-try --mein-name { … } fest. Er muss ein <dashed-ident> sein, also mit zwei Bindestrichen beginnen.

Gebraucht wird die Eigenschaft beim CSS Anchor Positioning: Ein verankertes Element (etwa ein Tooltip oder Popover) nennt in position-try-fallbacks (früher position-try-options) mehrere Ausweichpositionen. Passt die Standardposition nicht in den sichtbaren Bereich, probiert der Browser diese Optionen der Reihe nach durch. Über das CSSOM kannst du per name herausfinden, welche @position-try-Regeln ein Stylesheet definiert. Das hilft beim Debuggen, beim Bauen von Werkzeugen und beim gezielten Anpassen einzelner Regeln.

Die Eigenschaft ist schreibgeschützt. Der Name lässt sich also nicht umbenennen. Die Deklarationen innerhalb der Regel kannst du aber über CSSPositionTryRule.style (ein CSSPositionTryDescriptors-Objekt) ändern.

Rückgabewert

Typ

string

Beschreibung

Der Name der Ausweichposition genau so, wie er in der @position-try-Regel steht, einschließlich der führenden -- (z. B. "--custom-bottom").

Beispiele

Namen aller @position-try-Regeln auslesen

// CSS im Dokument:
// @position-try --custom-bottom { top: anchor(bottom); left: anchor(left); }
// @position-try --custom-top { bottom: anchor(top); left: anchor(left); }

const tryRuleNames = [...document.styleSheets]
  .flatMap((sheet) => {
    try {
      return [...sheet.cssRules];
    } catch {
      return []; // Fremd-Stylesheets ohne CORS überspringen
    }
  })
  .filter((rule) => rule instanceof CSSPositionTryRule)
  .map((rule) => rule.name);

console.log(tryRuleNames);

["--custom-bottom", "--custom-top"]

Regel dynamisch einfügen und Namen prüfen

if ('CSSPositionTryRule' in window) {
  const sheet = new CSSStyleSheet();
  sheet.replaceSync(`
    @position-try --tooltip-right {
      left: anchor(right);
      top: anchor(top);
      margin-left: 8px;
    }
  `);
  document.adoptedStyleSheets = [...document.adoptedStyleSheets, sheet];

  const rule = sheet.cssRules[0];
  console.log(rule.constructor.name, rule.name);
} else {
  console.log('Anchor Positioning wird nicht unterstützt');
}

CSSPositionTryRule --tooltip-right

Bestimmte Ausweichregel per Name finden und anpassen

const findPositionTry = (sheet, name) =>
  [...sheet.cssRules].find(
    (rule) => rule instanceof CSSPositionTryRule && rule.name === name
  );

const sheet = document.styleSheets[0];
const rule = findPositionTry(sheet, '--custom-bottom');

if (rule) {
  // name ist schreibgeschützt – die Deklarationen aber nicht
  rule.style.marginTop = '12px';
  console.log(`${rule.name}:`, rule.style.cssText);
}

--custom-bottom: top: anchor(bottom); left: anchor(left); margin-top: 12px;

// Wichtig · Fallstricke

Schreibgeschützt: rule.name = '--neu' bewirkt nichts und wirft im Strict Mode einen TypeError. Zum Umbenennen löschst du die Regel mit deleteRule() und fügst sie mit insertRule() unter neuem Namen wieder ein.
Der Name enthält immer die führenden --. Vergleiche daher mit '--name', nicht mit 'name'. Gewöhnliche Bezeichner ohne -- sind ungültig. Solche Regeln verwirft der Parser, sie tauchen also gar nicht erst in cssRules auf.
Stehen mehrere @position-try-Regeln mit gleichem Namen im Dokument, gewinnt nach den Kaskadenregeln die letzte. Im CSSOM bleiben trotzdem alle als eigene Objekte sichtbar.
Browser-Unterstützung: CSS Anchor Positioning gibt es in Chromium-Browsern ab Version 125. Andere Engines ziehen erst nach. Prüfe die Unterstützung vorher, z. B. mit 'CSSPositionTryRule' in window oder CSS.supports('anchor-name: --a').
Auf cssRules von Stylesheets anderer Herkunft (ohne CORS) darfst du nicht zugreifen. Der Zugriff wirft dann einen SecurityError, deshalb gehört er in einen try…catch-Block.

Siehe auch

CaretPosition.offsetNode CSSPositionTryRule.style CSSFunctionRule.name CSSPropertyRule.name CSSCounterStyleRule.name