CSSFontFeatureValuesRule.annotation — Eigenschaft · JavaScript-Referenz

Signatur

readonly CSSFontFeatureValuesRule.annotation: CSSFontFeatureValuesMap

Beschreibung

Die schreibgeschützte Eigenschaft annotation des Interfaces CSSFontFeatureValuesRule liefert den Inhalt des @annotation-Blocks einer @font-feature-values-Regel als CSSFontFeatureValuesMap. Jeder Eintrag verknüpft einen selbst gewählten Bezeichner (user-defined-ident, z. B. circled) mit einem Feature-Index. Dieser Index wählt eine alternative Glyphenform aus, die die Schrift über das OpenType-Feature nalt (Alternate Annotation Forms) bereitstellt.

In CSS nutzt man die Namen später über font-variant-alternates: annotation(circled). Über CSSOM kann man diese Zuordnungen auslesen, prüfen und auch zur Laufzeit ändern. Das ist praktisch für Editoren, Theme-Werkzeuge oder Debug-Tools, die die typografischen Einstellungen einer Seite anzeigen oder anpassen.

Die CSSFontFeatureValuesMap verhält sich wie eine Map (sie ist maplike). Schlüssel sind Strings, Werte sind Arrays mit ganzen Zahlen ohne Vorzeichen. Es gibt get(), has(), set(), delete(), clear(), forEach(), entries(), keys(), values() und size. Schreibgeschützt ist nur die Eigenschaft selbst. Die Map dahinter lässt sich verändern.

Rückgabewert

Typ

CSSFontFeatureValuesMap

Beschreibung

Eine Map-ähnliche Sammlung, die Bezeichner (string) auf Feature-Indizes (number[]) abbildet. Ohne @annotation-Block ist sie leer (size === 0).

Beispiele

Annotation-Werte einer @font-feature-values-Regel auslesen

const style = document.createElement("style");
style.textContent = `
  @font-feature-values MeineSchrift {
    @annotation { circled: 1; boxed: 3; }
  }
  .hinweis { font-family: MeineSchrift; font-variant-alternates: annotation(circled); }
`;
document.head.append(style);

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

console.log(rule.annotation.size);
console.log(rule.annotation.get("boxed"));
console.log(rule.annotation.has("circled"));

2 [3] true

Alle Annotation-Einträge auflisten

const listeAnnotationen = () => {
  for (const sheet of document.styleSheets) {
    let rules;
    try {
      rules = sheet.cssRules; // bei fremden Stylesheets (CORS) wird eine Ausnahme geworfen
    } catch {
      continue;
    }
    for (const rule of rules) {
      if (rule instanceof CSSFontFeatureValuesRule) {
        for (const [name, indizes] of rule.annotation.entries()) {
          console.log(`${rule.fontFamily}: ${name} → ${indizes.join(", ")}`);
        }
      }
    }
  }
};

listeAnnotationen();

MeineSchrift: circled → 1 MeineSchrift: boxed → 3

Zuordnung zur Laufzeit ändern und Unterstützung prüfen

const unterstuetzt =
  typeof CSSFontFeatureValuesRule !== "undefined" &&
  "annotation" in CSSFontFeatureValuesRule.prototype;

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

  // „circled“ zeigt jetzt auf die alternative Glyphe mit Index 2
  rule.annotation.set("circled", 2);
  rule.annotation.delete("boxed");
  console.log([...rule.annotation.keys()]);
} else {
  console.log("annotation wird nicht unterstützt");
}

["circled"]

// Wichtig · Fallstricke

Browser-Kompatibilität: Das Interface CSSFontFeatureValuesRule gibt es schon länger. Die Map-Eigenschaften wie annotation kommen aber erst in neueren Chromium- und Safari-Versionen vor. Vor dem Zugriff mit "annotation" in CSSFontFeatureValuesRule.prototype prüfen, ob die Eigenschaft vorhanden ist.
Für @annotation ist pro Bezeichner nur ein Index erlaubt. Werden bei set() mehrere Werte übergeben, wirft der Browser eine InvalidAccessError-Ausnahme. Bei @styleset sind dagegen mehrere Werte erlaubt.
get() gibt immer ein Array zurück (z. B. [3]), nie eine einzelne Zahl.
Die Wirkung ist nur sichtbar, wenn die Schrift das OpenType-Feature nalt tatsächlich enthält. Sonst ändert sich die Darstellung nicht, und es gibt keine Fehlermeldung.
Auf cssRules von Stylesheets einer fremden Herkunft (Cross-Origin) darf man nur mit passenden CORS-Headern zugreifen. Sonst wird ein SecurityError geworfen.

Siehe auch

CSSFontFeatureValuesRule.characterVariant CSSFontFeatureValuesRule.fontFamily CSSFontFeatureValuesRule.stylistic CSSFontFeatureValuesRule.ornaments CSSFontFeatureValuesRule.swash