CSSKeyframesRule.deleteRule() — Methode · JavaScript-Referenz

Signatur

CSSKeyframesRule.prototype.deleteRule(select)

Beschreibung

Mit deleteRule() löschen Sie einzelne Keyframes aus einer bestehenden @keyframes-Animation, ohne das ganze Stylesheet neu zu schreiben. Die Methode gehört zum Interface CSSKeyframesRule. Dieses Interface steht für den kompletten @keyframes-Block. Seine Kind-Regeln sind CSSKeyframeRule-Objekte, zum Beispiel 0%, 50% oder to.

Der Parameter ist ein Keyframe-Selektor als Zeichenkette und kein numerischer Index. Das unterscheidet die Methode von CSSStyleSheet.deleteRule(index). Erlaubt sind Prozentwerte wie "50%", die Schlüsselwörter "from" (entspricht 0%) und "to" (entspricht 100%) sowie Listen wie "0%, 100%". Stimmen mehrere Keyframes mit dem Selektor überein, entfernt der Browser nur den letzten davon.

Typische Einsätze sind Animationen, die sich zur Laufzeit ändern: Zwischenstufen entfernen, einen Keyframe durch eine neue Version ersetzen (erst deleteRule(), dann appendRule()) oder Animationen in Editoren und Design-Werkzeugen bearbeiten. Laufende Animationen, die diese @keyframes-Regel nutzen, übernehmen die Änderung in der Regel sofort.

Parameter

Name	Typ	Default	Beschreibung
$select Pflicht	string		Keyframe-Selektor des zu löschenden Keyframes, z. B. `"50%"`, `"from"`, `"to"` oder eine kommagetrennte Liste wie `"0%, 100%"`.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined). Findet der Browser keinen passenden Keyframe, passiert nichts und es wird kein Fehler geworfen.

Beispiele

Zwischen-Keyframe aus einer Animation entfernen

// Stylesheet mit einer @keyframes-Regel anlegen
const style = document.createElement('style');
style.textContent = `
  @keyframes pulse {
    from { transform: scale(1); }
    50%  { transform: scale(1.3); }
    to   { transform: scale(1); }
  }
`;
document.head.append(style);

const keyframes = [...style.sheet.cssRules]
  .find((rule) => rule instanceof CSSKeyframesRule && rule.name === 'pulse');

console.log(keyframes.cssRules.length);
keyframes.deleteRule('50%');
console.log(keyframes.cssRules.length);
console.log([...keyframes.cssRules].map((r) => r.keyText));

3 2 ["0%", "100%"]

Keyframe ersetzen: deleteRule() + appendRule()

const findKeyframes = (name) => {
  for (const sheet of document.styleSheets) {
    let rules;
    try {
      rules = sheet.cssRules; // kann bei fremden Stylesheets (CORS) werfen
    } catch {
      continue;
    }
    for (const rule of rules) {
      if (rule instanceof CSSKeyframesRule && rule.name === name) return rule;
    }
  }
  return null;
};

const replaceKeyframe = (name, selector, declarations) => {
  const rule = findKeyframes(name);
  if (!rule) return false;
  rule.deleteRule(selector);
  rule.appendRule(`${selector} { ${declarations} }`);
  return true;
};

// Endzustand der Animation "slide-in" zur Laufzeit ändern
console.log(replaceKeyframe('slide-in', 'to', 'transform: translateX(200px); opacity: 1;'));

true (sofern eine @keyframes-Regel "slide-in" existiert)

from/to sind gleichwertig zu 0%/100%

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

const fade = style.sheet.cssRules[0];
fade.deleteRule('to'); // löscht den 100%-Keyframe
console.log(fade.cssRules.length, fade.cssRules[0].keyText);

fade.deleteRule('33%'); // kein Treffer: kein Fehler
console.log(fade.cssRules.length);

1 "0%" 1

// Wichtig · Fallstricke

Selektor statt Index: Anders als bei CSSStyleSheet.deleteRule() oder CSSGroupingRule.deleteRule() übergeben Sie hier eine Zeichenkette wie "50%". Bei einer Zahl wie 0 sucht der Browser nach dem Selektor "0" und findet nichts, weil gültige Keyframe-Selektoren eine Prozentangabe oder from/to brauchen.
Mehrere Treffer: Passen mehrere Keyframes zum Selektor, wird nur der letzte gelöscht. Wenn Sie alle entfernen wollen, rufen Sie die Methode in einer Schleife auf, bis findRule(select) null liefert.
Kein Fehler bei ungültigem Selektor: Die Methode wirft nichts, wenn der Selektor fehlt oder nicht passt. Prüfen Sie das Ergebnis bei Bedarf selbst, etwa über cssRules.length oder findRule().
CORS: Auf cssRules von Stylesheets einer anderen Herkunft ohne passende CORS-Header können Sie nicht zugreifen. Der Zugriff wirft dann einen SecurityError. Umschließen Sie die Schleife über document.styleSheets deshalb mit try/catch.
Kompatibilität: Wird von allen modernen Browsern unterstützt. Sehr alte Versionen von WebKit und Firefox kannten nur WebKitCSSKeyframesRule bzw. MozCSSKeyframesRule. Außerdem erwarteten ältere Implementierungen teils Prozentwerte statt from/to.
Für einfache, einmalige Animationen ist oft die Web Animations API (element.animate()) übersichtlicher als das Bearbeiten von Stylesheets.

Siehe auch

Element.animate() CSSKeyframesRule.appendRule() CSSKeyframesRule.findRule() CSSGroupingRule.deleteRule() CSSStyleSheet.deleteRule()