CSSKeyframesRule.findRule() — Methode · JavaScript-Referenz

Signatur

CSSKeyframesRule.prototype.findRule(select)

Beschreibung

Die Methode findRule() gehört zur Schnittstelle CSSKeyframesRule. Diese steht im CSSOM für eine vollständige @keyframes-Regel. findRule() durchsucht die einzelnen Keyframes der Animation und gibt das CSSKeyframeRule-Objekt zurück, dessen Keyframe-Selektor zum übergebenen Text passt, etwa "0%", "50%", "from" oder "to".

Das ist praktisch, wenn du CSS-Animationen zur Laufzeit ändern willst, ohne das ganze Stylesheet neu zu schreiben. Beispiele: eine Zielposition, eine Farbe oder eine Deckkraft abhängig von Benutzereingaben oder Messwerten anpassen. Über die Eigenschaft style des gefundenen Keyframes änderst du die Deklarationen direkt. Laufende und neu gestartete Animationen verwenden dann die neuen Werte.

Die Schlüsselwörter from und to werden als 0% bzw. 100% ausgewertet. findRule("from") und findRule("0%") finden also dasselbe Keyframe. Passen mehrere Keyframes zum Selektor, liefert die Methode das letzte. Wird kein passendes Keyframe gefunden, ist der Rückgabewert null.

Parameter

Name	Typ	Default	Beschreibung
$select Pflicht	string		Keyframe-Selektor als Text, z. B. `"25%"`, `"from"`, `"to"` oder eine Liste wie `"0%, 100%"`. Eine Liste muss genau zum Selektor des gesuchten Keyframes passen.

Rückgabewert

Typ

CSSKeyframeRule | null

Beschreibung

Das zuletzt definierte passende CSSKeyframeRule-Objekt oder null, wenn kein Keyframe zum Selektor passt.

Beispiele

Keyframe einer Animation finden und auslesen

// Stylesheet mit einer Animation anlegen
const style = document.createElement('style');
style.textContent = `
  @keyframes pulse {
    from { opacity: 1; }
    50%  { opacity: 0.3; }
    to   { opacity: 1; }
  }
`;
document.head.append(style);

// @keyframes-Regel über ihren Namen suchen
const keyframes = [...style.sheet.cssRules]
  .find((rule) => rule instanceof CSSKeyframesRule && rule.name === 'pulse');

const middle = keyframes.findRule('50%');
console.log(middle.keyText);
console.log(middle.style.opacity);

50% 0.3

Animation zur Laufzeit anpassen

// Hilfsfunktion: @keyframes-Regel in allen (gleich-origin) Stylesheets finden
const getKeyframes = (name) => {
  for (const sheet of document.styleSheets) {
    let rules;
    try {
      rules = sheet.cssRules; // Fremd-Stylesheets werfen einen SecurityError
    } catch {
      continue;
    }
    for (const rule of rules) {
      if (rule instanceof CSSKeyframesRule && rule.name === name) return rule;
    }
  }
  return null;
};

const style = document.createElement('style');
style.textContent = '@keyframes slide { from { transform: translateX(0); } to { transform: translateX(100px); } }';
document.head.append(style);

// Zielposition abhängig von der Fensterbreite setzen
const slide = getKeyframes('slide');
const end = slide?.findRule('to');
if (end) {
  end.style.transform = `translateX(${Math.round(window.innerWidth / 2)}px)`;
  console.log(end.style.transform);
}

translateX(640px) // abhängig von der Fensterbreite

Fehlendes Keyframe erkennen und ergänzen

const style = document.createElement('style');
style.textContent = '@keyframes fade { from { opacity: 0; } to { opacity: 1; } }';
document.head.append(style);

const fade = style.sheet.cssRules[0];

// "from" und "0%" sind gleichwertig
console.log(fade.findRule('0%') === fade.findRule('from'));

// Nicht vorhandenes Keyframe ergibt null
if (fade.findRule('50%') === null) {
  fade.appendRule('50% { opacity: 0.8; }');
}
console.log(fade.findRule('50%').style.opacity);

true 0.8

// Wichtig · Fallstricke

Rückgabewert prüfen: Gibt es kein passendes Keyframe, liefert die Methode null. Prüfe den Wert daher vor dem Zugriff, zum Beispiel mit optionaler Verkettung (?.).
Mehrfache Treffer: Kommt ein Selektor mehrfach vor, wird nur das letzte passende Keyframe zurückgegeben. Die früheren Keyframes bleiben unverändert.
Selektorlisten: Ein Keyframe wie 0%, 100% { … } passt nur zur vollständigen Liste. findRule("0%") findet es nicht.
Fremde Stylesheets: Bei Stylesheets von anderen Ursprüngen ohne passende CORS-Freigabe wirft der Zugriff auf cssRules einen SecurityError. Umschließe die Schleife deshalb mit try…catch.
Kompatibilität: Wird von allen modernen Browsern unterstützt. Sehr alte WebKit-Versionen kannten nur WebKitCSSKeyframesRule mit Präfix. Wer Animationen häufig dynamisch ändert, fährt mit der Web Animations API (element.animate()) oft besser.

Siehe auch

Element.animate() CSSKeyframesRule.appendRule() CSSKeyframesRule.deleteRule() CSSStyleSheet.addRule() CSSGroupingRule.insertRule()