CSSFontFeatureValuesRule.characterVariant — Eigenschaft · JavaScript-Referenz

Signatur

get CSSFontFeatureValuesRule.characterVariant

Beschreibung

Die schreibgeschützte Eigenschaft characterVariant einer CSSFontFeatureValuesRule gibt den Inhalt des @character-variant-Blocks innerhalb einer @font-feature-values-Regel zurück. Das Ergebnis ist eine CSSFontFeatureValuesMap: Die Schlüssel sind die selbst gewählten Namen (user-defined-ident, z. B. fancy-a), die Werte sind Arrays mit Ganzzahlen.

Bei @character-variant steht die erste Zahl für den OpenType-Feature-Index (1 entspricht cv01, 2 entspricht cv02 usw. bis cv99). Die optionale zweite Zahl wählt die Glyphen-Alternative innerhalb dieses Features. In CSS nutzt man die Namen dann über font-variant-alternates: character-variant(fancy-a).

Schreibgeschützt ist nur die Eigenschaft selbst. Die zurückgegebene Map lässt sich ändern: Mit set(), delete() und clear() passt man die Zuordnungen zur Laufzeit an, und die Änderungen wirken sich direkt auf die Darstellung aus. Das ist z. B. praktisch für Schrift-Konfiguratoren oder Themes, bei denen der Nutzer Glyphen-Varianten auswählt.

Rückgabewert

Typ

CSSFontFeatureValuesMap

Beschreibung

Eine Map-ähnliche Sammlung (maplike<string, number[]>) mit den Einträgen aus @character-variant. Gibt es den Block nicht, ist die Map leer (size === 0).

Beispiele

Character-Variant-Einträge auslesen

const style = document.createElement('style');
style.textContent = `
  @font-feature-values "Inter" {
    @character-variant {
      alt-a: 1;
      alt-g: 2 1;
    }
  }
`;
document.head.append(style);

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

console.log(rule.fontFamily);
for (const [name, values] of rule.characterVariant) {
  console.log(name, values);
}

"Inter" alt-a [1] alt-g [2, 1]

Neue Variante zur Laufzeit hinzufügen

const rule = [...document.styleSheets]
  .flatMap((sheet) => {
    try { return [...sheet.cssRules]; } catch { return []; } // Cross-Origin-Stylesheets überspringen
  })
  .find((r) => r instanceof CSSFontFeatureValuesRule);

if (rule) {
  // cv05, Glyphen-Alternative 2
  rule.characterVariant.set('alt-r', [5, 2]);
  console.log(rule.characterVariant.has('alt-r'));
  console.log(rule.characterVariant.get('alt-r'));

  // Verwenden im Dokument
  document.body.style.fontVariantAlternates = 'character-variant(alt-r)';
}

true [5, 2]

Varianten-Auswahl für einen Schrift-Konfigurator

const listVariants = (rule) =>
  Array.from(rule.characterVariant.keys());

const applyVariant = (el, name) => {
  el.style.fontVariantAlternates = `character-variant(${name})`;
};

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

if (rule) {
  const names = listVariants(rule);
  console.log('Verfügbar:', names.join(', '));
  applyVariant(document.querySelector('h1'), names[0]);
}

Verfügbar: alt-a, alt-g

// Wichtig · Fallstricke

Nur für OpenType-Features cv01–cv99: Die Werte wirken nur, wenn die Schrift diese Features tatsächlich enthält. Andernfalls bleibt die Änderung ohne sichtbaren Effekt, und es gibt auch keine Fehlermeldung.
Höchstens zwei Werte: Für @character-variant sind nur ein oder zwei Zahlen erlaubt. Mehr Werte machen die Deklaration in CSS ungültig.
Nur die Eigenschaft ist schreibgeschützt: rule.characterVariant = … hat keine Wirkung (im Strict Mode gibt es einen TypeError). Ändern kann man nur die Map selbst über set()/delete().
Cross-Origin-Stylesheets: Wer cssRules in Stylesheets von fremden Domains ohne CORS liest, bekommt einen SecurityError. Deshalb den Zugriff in try/catch einschließen.
Kompatibilität: @font-feature-values und die zugehörigen Map-Eigenschaften gibt es erst seit 2023 in allen großen Engines (Chromium 111+, aktuelles Firefox und Safari). Bei älteren Browsern vorher mit 'CSSFontFeatureValuesRule' in window prüfen. Als Ausweichlösung eignet sich font-feature-settings: \"cv01\" 1.

Siehe auch

CSSFontFeatureValuesRule.fontFamily CSSFontFeatureValuesRule.ornaments CSSFontFeatureValuesRule.annotation CSSFontFeatureValuesRule.styleset CSSFontFeatureValuesRule.stylistic