CSSStyleSheet: insertRule()-Methode

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since September 2015.

Die CSSStyleSheet.insertRule()-Methode fügt eine neue CSS-Regel in das aktuelle Stylesheet ein.

Hinweis: Obwohl insertRule() ausschließlich eine Methode von CSSStyleSheet ist, wird die Regel tatsächlich in [CSSStyleSheet](/de/docs/Web/API/CSSStyleSheet).cssRules eingefügt — dessen interne CSSRuleList.

Syntax

js
insertRule(rule)
insertRule(rule, index)

Parameter

rule

Ein String, der die einzufügende Regel enthält. Was die eingefügte Regel enthalten muss, hängt von ihrem Typ ab:

  • Für Regel-Sets sowohl ein Selektor als auch eine Stil-Deklaration.
  • Für at-Rules sowohl einen At-Identifier als auch den Regelinhalt.
index Optional

Eine positive Ganzzahl, die kleiner oder gleich stylesheet.cssRules.length ist und die Position der neu eingefügten Regel in [CSSStyleSheet](/de/docs/Web/API/CSSStyleSheet).cssRules darstellt. Der Standardwert ist 0. (In älteren Implementierungen war dies erforderlich. Siehe Browser-Kompatibilität für Details.)

Rückgabewert

Der Index der neu eingefügten Regel innerhalb der Regel-Liste des Stylesheets.

Ausnahmen

IndexSizeError DOMException

Wird ausgelöst, wenn index > [CSSRuleList](/de/docs/Web/API/CSSRuleList).length.

HierarchyRequestError DOMException

Wird ausgelöst, wenn rule aufgrund einer CSS-Beschränkung nicht an index 0 eingefügt werden kann.

SyntaxError DOMException

Wird ausgelöst, wenn im Parameter rule mehr als eine Regel angegeben ist.

HierarchyRequestError DOMException

Wird ausgelöst, wenn versucht wird, eine @import-At-Regel nach einer Stilregel einzufügen.

InvalidStateError DOMException

Wird ausgelöst, wenn rule ein @namespace ist und die Regel-Liste mehr als nur @import-At-Regeln und/oder @namespace-At-Regeln enthält.

Beispiele

Eine neue Regel einfügen

Dieses Beispiel fügt eine neue Regel an den Anfang meines Stylesheets hinzu.

js
myStyle.insertRule("#blanc { color: white }", 0);

Funktion zum Hinzufügen einer Stylesheet-Regel

js
/**
 * Add a stylesheet rule to the document (it may be better practice
 * to dynamically change classes, so style information can be kept in
 * genuine stylesheets and avoid adding extra elements to the DOM).
 * Note that an array is needed for declarations and rules since ECMAScript does
 * not guarantee a predictable object iteration order, and since CSS is
 * order-dependent.
 * @param {Array} rules Accepts an array of JSON-encoded declarations
 * @example
addStylesheetRules([
  ['h2', // Also accepts a second argument as an array of arrays instead
    ['color', 'red'],
    ['background-color', 'green', true] // 'true' for !important rules
  ],
  ['.myClass',
    ['background-color', 'yellow']
  ]
]);
*/
function addStylesheetRules(rules) {
  const styleEl = document.createElement("style");

  // Append <style> element to <head>
  document.head.appendChild(styleEl);

  // Grab style element's sheet
  const styleSheet = styleEl.sheet;

  for (let i = 0; i < rules.length; i++) {
    let j = 1,
      rule = rules[i],
      selector = rule[0],
      propStr = "";
    // If the second argument of a rule is an array of arrays, correct our variables.
    if (Array.isArray(rule[1][0])) {
      rule = rule[1];
      j = 0;
    }

    for (let pl = rule.length; j < pl; j++) {
      const prop = rule[j];
      propStr += `${prop[0]}: ${prop[1]}${prop[2] ? " !important" : ""};\n`;
    }

    // Insert CSS Rule
    styleSheet.insertRule(
      `${selector}{${propStr}}`,
      styleSheet.cssRules.length,
    );
  }
}

Spezifikationen

Specification
CSS Object Model (CSSOM)
# dom-cssstylesheet-insertrule

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch