CSSFontFeatureValuesRule.ornaments — Eigenschaft · JavaScript-Referenz

Signatur

CSSFontFeatureValuesRule.ornaments

Beschreibung

Die Eigenschaft ornaments einer CSSFontFeatureValuesRule steht für den @ornaments-Block innerhalb einer @font-feature-values-Regel. Dort legt man selbst gewählte Bezeichner (user-defined idents) fest und ordnet ihnen Feature-Indizes zu. Über font-variant-alternates: ornaments(name) wird dann das passende Ornament-Glyph der Schrift gewählt. Technisch schaltet das das OpenType-Feature ornm mit dem angegebenen Index ein.

Die Eigenschaft selbst ist schreibgeschützt, das heißt, man kann ihr kein neues Objekt zuweisen. Die zurückgegebene CSSFontFeatureValuesMap verhält sich aber wie eine Map. Mit get(), has(), set(), delete(), forEach(), keys(), values(), entries() und size lassen sich die Einträge zur Laufzeit lesen und ändern. Schlüssel sind die Bezeichner als Zeichenketten, Werte sind Arrays aus Ganzzahlen.

Typische Einsatzfälle: Werkzeuge, die Stylesheets untersuchen, Schrift-Vorschauen und Editoren, in denen man Ornament-Varianten einer Schrift umschalten kann, ohne das CSS neu zu schreiben.

Rückgabewert

Typ

CSSFontFeatureValuesMap

Beschreibung

Ein Map-ähnliches Objekt. Es ordnet Bezeichner (string) den Feature-Indizes (number[]) aus dem @ornaments-Block zu. Gibt es keinen solchen Block, ist die Map leer (size === 0).

Beispiele

Ornament-Bezeichner aus dem Stylesheet auslesen

// CSS im Dokument:
// @font-feature-values MyDeco {
//   @ornaments { fleuron: 1; herz: 4; stern: 7; }
// }

const findFeatureRules = () =>
  [...document.styleSheets]
    .flatMap((sheet) => {
      try { return [...sheet.cssRules]; } catch { return []; } // fremde Stylesheets (CORS) überspringen
    })
    .filter((rule) => rule instanceof CSSFontFeatureValuesRule);

for (const rule of findFeatureRules()) {
  console.log(rule.fontFamily);
  rule.ornaments.forEach((indices, name) => {
    console.log(`${name} → ${indices.join(', ')}`);
  });
}

MyDeco fleuron → 1 herz → 4 stern → 7

Prüfen und gezielt abfragen

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

const { ornaments } = rule;
console.log(ornaments.size);
console.log(ornaments.has('herz'));
console.log(ornaments.get('herz'));
console.log(ornaments.get('unbekannt'));

3 true [4] undefined

Ornament zur Laufzeit ändern und hinzufügen

const style = document.createElement('style');
style.textContent = `
  @font-feature-values MyDeco { @ornaments { fleuron: 1; } }
  .deko { font-family: MyDeco; font-variant-alternates: ornaments(fleuron); }
`;
document.head.append(style);

const rule = [...style.sheet.cssRules]
  .find((r) => r instanceof CSSFontFeatureValuesRule);

// Index des vorhandenen Bezeichners ändern und neuen Bezeichner hinzufügen
rule.ornaments.set('fleuron', 3);
rule.ornaments.set('ranke', [5]);

console.log([...rule.ornaments.entries()]);

// Nicht erlaubt: rule.ornaments = new Map(); (schreibgeschützt)

[["fleuron", [3]], ["ranke", [5]]]

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung an rule.ornaments wird im nicht-strikten Modus stillschweigend ignoriert und löst im strikten Modus einen TypeError aus. Ändern Sie stattdessen die Map selbst mit set() oder delete().
Nur ein Wert pro Bezeichner: Bei @ornaments ist genau ein Index pro Bezeichner gültig. Mehrere Werte, wie bei @character-variant, machen die Deklaration ungültig. Ein Aufruf von set() mit einem zu langen Array kann eine Ausnahme auslösen.
Die Schrift entscheidet: Ein Index wirkt nur, wenn die Schrift das OpenType-Feature ornm mit genau diesem Glyphen-Index anbietet. Sonst ändert sich die Darstellung nicht, und es gibt keine Fehlermeldung.
CORS: Zugriffe auf cssRules in Stylesheets von fremden Ursprüngen lösen einen SecurityError aus. Umschließen Sie diese Zugriffe deshalb mit try/catch.
Kompatibilität: Die Map-Eigenschaften von CSSFontFeatureValuesRule werden in Chromium-Browsern ab Version 111 und in aktuellen Safari-Versionen unterstützt. Firefox kennt die Regel schon länger, unterstützt die Map-Eigenschaften aber möglicherweise nicht vollständig. Prüfen Sie das per Feature-Erkennung, z. B. mit 'ornaments' in CSSFontFeatureValuesRule.prototype.

Siehe auch

CSSFontFeatureValuesRule CSSFontFeatureValuesMap CSSFontFeatureValuesRule.swash CSSFontFeatureValuesRule.styleset CSSFontFeatureValuesRule.annotation CSSFontFeatureValuesMap.size