CSSContainerRule.containerName — Eigenschaft · JavaScript-Referenz

Signatur

CSSContainerRule.containerName

Beschreibung

Die Eigenschaft containerName gehört zu einem CSSContainerRule-Objekt und liefert den Namen aus der Bedingung einer @container-Regel. Bei @container sidebar (min-width: 400px) { … } ist das der String "sidebar". Der Name bezieht sich auf ein Element, für das per container-name (oder über die Kurzschreibweise container) ein passender Name gesetzt ist.

Ist in der Regel kein Name angegeben, etwa bei @container (min-width: 400px), gibt die Eigenschaft einen leeren String zurück. Dann gilt die Abfrage für den nächstgelegenen Vorfahren, der ein Abfrage-Container ist.

Nützlich ist containerName vor allem beim Untersuchen von Stylesheets zur Laufzeit, zum Beispiel für Debug-Werkzeuge, Linter oder Theme-Editoren. Die Abfragebedingung selbst ohne den Namen steht in containerQuery, die vollständige Bedingung (Name und Abfrage) in conditionText.

Die Eigenschaft ist schreibgeschützt. Um den Namen zu ändern, muss man die Regel löschen und neu einfügen, zum Beispiel mit CSSStyleSheet.deleteRule() und insertRule().

Rückgabewert

Typ

string

Beschreibung

Der Container-Name aus der Bedingung der @container-Regel oder "" (leerer String), wenn kein Name angegeben ist.

Beispiele

Container-Namen aus einem erzeugten Stylesheet auslesen

const sheet = new CSSStyleSheet();
sheet.replaceSync(`
  .layout { container: sidebar / inline-size; }
  @container sidebar (min-width: 400px) {
    .card { display: grid; }
  }
`);

const rule = [...sheet.cssRules].find((r) => r instanceof CSSContainerRule);
console.log(rule.containerName);
console.log(rule.containerQuery);
console.log(rule.conditionText);

sidebar (min-width: 400px) sidebar (min-width: 400px)

Regel ohne Namen ergibt einen leeren String

const sheet = new CSSStyleSheet();
sheet.replaceSync(`@container (max-width: 300px) { h2 { font-size: 1rem; } }`);

const [rule] = sheet.cssRules;
console.log(JSON.stringify(rule.containerName));
console.log(rule.containerName === '' ? 'unbenannter Container' : rule.containerName);

"" unbenannter Container

Alle Container-Abfragen der Seite nach Namen gruppieren

const groupContainerRules = () => {
  const groups = new Map();
  for (const sheet of document.styleSheets) {
    let rules;
    try {
      rules = sheet.cssRules; // bei fremden Stylesheets ohne CORS: SecurityError
    } catch {
      continue;
    }
    for (const rule of rules) {
      if (!(rule instanceof CSSContainerRule)) continue;
      const name = rule.containerName || '(ohne Namen)';
      if (!groups.has(name)) groups.set(name, []);
      groups.get(name).push(rule.containerQuery);
    }
  }
  return groups;
};

console.table([...groupContainerRules()].map(([name, queries]) => ({ name, queries: queries.join(' | ') })));

Tabelle mit einer Zeile je Container-Name und den zugehörigen Abfragen

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung wie rule.containerName = "x" wird ohne Fehlermeldung ignoriert, im Strict Mode löst sie einen TypeError aus. Soll sich der Name ändern, muss die Regel neu eingefügt werden.
Leerer String statt null: Ob eine Regel einen Namen hat, prüft man mit rule.containerName !== "" und nicht mit einem Vergleich auf null oder undefined.
Nur eine Bedingung: Die Eigenschaft beschreibt den Namen bei einer Regel mit genau einer Container-Bedingung. Neuere Entwürfe der Spezifikation erlauben mehrere, durch Kommas getrennte Bedingungen. In diesem Fall zuverlässiger mit conditionText arbeiten.
Stylesheets von fremden Domains: Wenn ein Stylesheet von einer anderen Domain ohne CORS-Freigabe geladen wurde, löst schon der Zugriff auf cssRules einen SecurityError aus. Deshalb in try/catch einschließen.
Kompatibilität: CSSContainerRule gibt es seit Chrome 105 und Safari 16. containerName und containerQuery kamen erst später hinzu (Chrome 111, Firefox 110, Safari 16.4). In älteren Browsern bleibt als Ausweg nur, conditionText selbst zu zerlegen.

Siehe auch

CSSConditionRule.conditionText CSSContainerRule.containerQuery CSSContainerRule.conditions CSSImportRule.layerName CSSCounterStyleRule.name