CSSNamespaceRule — Schnittstelle · JavaScript-Referenz

Signatur

interface CSSNamespaceRule extends CSSRule

Beschreibung

CSSNamespaceRule ist das CSSOM-Gegenstück zur At-Regel @namespace. Mit dieser Regel legt ein Stylesheet einen Standard-Namespace oder ein Namespace-Präfix fest. Das ist vor allem bei gemischten Dokumenten wichtig, etwa bei XHTML mit eingebettetem SVG oder MathML oder bei reinen XML-Dokumenten. Selektoren wie svg|a gelten dann nur für Elemente im passenden Namespace.

Das Interface erbt von CSSRule und hat zwei eigene, schreibgeschützte Eigenschaften:

namespaceURI: die Namespace-URI als Zeichenkette, z. B. "http://www.w3.org/2000/svg".
prefix: das Präfix der Regel. Bei einer Standard-Namespace-Deklaration ohne Präfix ist es ein leerer String "".

Du erzeugst CSSNamespaceRule-Objekte nicht direkt, denn es gibt keinen öffentlichen Konstruktor. Du bekommst sie über CSSStyleSheet.cssRules, wenn ein Stylesheet @namespace-Regeln enthält. Neue Regeln fügst du mit CSSStyleSheet.insertRule() ein. Typische Einsatzfälle sind Werkzeuge, die Stylesheets untersuchen (Linter, Devtools, CSS-Serialisierer), und das dynamische Erzeugen namespace-abhängiger Styles.

Das Interface ist eine Web-API und steht nur im Browser zur Verfügung. Es hat weder Parameter noch einen Konstruktor. Die Beispiele zeigen deshalb, wie du an die Regel kommst und ihre Eigenschaften ausliest.

Rückgabewert

Typ

CSSNamespaceRule

Beschreibung

Du bekommst Instanzen nur indirekt, z. B. als Einträge von CSSStyleSheet.cssRules. Sie haben die Eigenschaften namespaceURI (string) und prefix (string) sowie die von CSSRule geerbten Eigenschaften wie cssText und parentStyleSheet.

Beispiele

Namespace-Regeln eines Stylesheets auslesen

// Ein konstruierbares Stylesheet mit zwei @namespace-Regeln
const sheet = new CSSStyleSheet();
sheet.replaceSync(`
  @namespace url(http://www.w3.org/1999/xhtml);
  @namespace svg url(http://www.w3.org/2000/svg);
  svg|circle { fill: tomato; }
`);

for (const rule of sheet.cssRules) {
  if (rule instanceof CSSNamespaceRule) {
    console.log(`Präfix: "${rule.prefix}" → ${rule.namespaceURI}`);
  }
}

Präfix: "" → http://www.w3.org/1999/xhtml Präfix: "svg" → http://www.w3.org/2000/svg

Namespace-Regel per insertRule() einfügen

const sheet = new CSSStyleSheet();

// @namespace-Regeln müssen vor allen Stilregeln stehen, darum Index 0
sheet.insertRule('@namespace math url(http://www.w3.org/1998/Math/MathML);', 0);
sheet.insertRule('math|mi { font-style: italic; }', 1);

const nsRule = sheet.cssRules[0];
console.log(nsRule.constructor.name);
console.log(nsRule.prefix, nsRule.namespaceURI);
console.log(nsRule.cssText);

CSSNamespaceRule math http://www.w3.org/1998/Math/MathML @namespace math url("http://www.w3.org/1998/Math/MathML");

Präfix-Tabelle aus allen Stylesheets des Dokuments aufbauen

const collectNamespaces = () => {
  const map = new Map();
  for (const sheet of document.styleSheets) {
    let rules;
    try {
      rules = sheet.cssRules; // kann bei fremden Ursprüngen (CORS) werfen
    } catch {
      continue;
    }
    for (const rule of rules) {
      if (rule instanceof CSSNamespaceRule) {
        map.set(rule.prefix || '(Standard)', rule.namespaceURI);
      }
    }
  }
  return map;
};

console.log(Object.fromEntries(collectNamespaces()));

{ "(Standard)": "http://www.w3.org/1999/xhtml", "svg": "http://www.w3.org/2000/svg" }

// Wichtig · Fallstricke

Schreibgeschützt: namespaceURI und prefix lassen sich nicht ändern. Um einen Namespace zu ändern, entfernst du die Regel mit deleteRule() und fügst eine neue ein.
Position: @namespace muss nach @charset und @import, aber vor allen anderen Regeln stehen. insertRule() an einer ungültigen Position wirft einen HierarchyRequestError. Enthält das Stylesheet schon andere Regeln als @import oder @namespace, wirft das nachträgliche Einfügen einen InvalidStateError.
Kein Präfix: Bei einer Standard-Namespace-Deklaration liefert prefix einen leeren String, nicht null.
CORS: Liest du cssRules von Stylesheets aus fremden Ursprüngen ohne passende CORS-Header, wird ein SecurityError geworfen. Verwende dafür try/catch.
HTML-Dokumente: In normalem HTML (nicht XHTML) liegen Elemente zwar im XHTML-Namespace, und eingebettetes SVG liegt im SVG-Namespace. Trotzdem wird @namespace in der Praxis selten gebraucht.
Kompatibilität: Das Interface wird von allen modernen Browsern unterstützt. new CSSStyleSheet() und replaceSync() aus den Beispielen gibt es erst ab Chrome 73, Firefox 101 und Safari 16.4. In Node.js gibt es das Interface nicht.

Siehe auch

CSSRule CSSStyleSheet CSSStyleSheet.insertRule() CSSImportRule CSSStyleRule Document.styleSheets