CSSPageRule — Schnittstelle · JavaScript-Referenz

Signatur

interface CSSPageRule extends CSSGroupingRule

Beschreibung

CSSPageRule ist die CSSOM-Darstellung einer @page-At-Regel. Mit @page legt man Eigenschaften der Druckseite (des „Seitenkastens“) fest, zum Beispiel size, margin oder page-orientation. Mit Pseudoklassen wie :first, :left, :right und :blank lassen sich einzelne Seiten gezielt ansprechen, benannte Seiten zusätzlich über die Eigenschaft page.

Objekte dieses Typs erzeugt man nicht selbst. Man bekommt sie über CSSStyleSheet.cssRules, wenn ein Stylesheet eine @page-Regel enthält. Die wichtigsten Eigenschaften sind:

selectorText (string, lesen und schreiben): der Seitenselektor, z. B. ":first" oder "cover:left". Bei einer @page-Regel ohne Selektor ist der Wert eine leere Zeichenkette.
style (CSSPageDescriptors bzw. CSSStyleDeclaration, nur lesbar): die Deklarationen der Regel. Die einzelnen Werte kann man über dieses Objekt ändern.
Geerbt von CSSGroupingRule: cssRules, insertRule() und deleteRule() für verschachtelte Randbereich-Regeln wie @top-center. Geerbt von CSSRule: cssText, parentRule und parentStyleSheet.

Typische Einsatzfälle sind Druckansichten, die sich zur Laufzeit anpassen, etwa ein Umschalter zwischen Hoch- und Querformat oder frei einstellbare Seitenränder. Auch Werkzeuge, die Stylesheets auswerten oder umschreiben, arbeiten mit CSSPageRule.

Beispiele

Alle @page-Regeln eines Dokuments auflisten

// Sucht in allen Stylesheets nach @page-Regeln
const findPageRules = () => {
  const result = [];
  for (const sheet of document.styleSheets) {
    let rules;
    try {
      rules = sheet.cssRules; // bei fremden Stylesheets ohne CORS wird ein SecurityError geworfen
    } catch {
      continue;
    }
    for (const rule of rules) {
      if (rule instanceof CSSPageRule) result.push(rule);
    }
  }
  return result;
};

for (const rule of findPageRules()) {
  console.log(`Selektor: "${rule.selectorText}" | Rand: ${rule.style.margin}`);
}

Selektor: "" | Rand: 2cm Selektor: ":first" | Rand: 4cm 2cm 2cm

@page-Regel zur Laufzeit einfügen und Querformat umschalten

// Eigenes Stylesheet für Druckeinstellungen anlegen
const style = document.createElement('style');
document.head.append(style);
const sheet = style.sheet;

const index = sheet.insertRule('@page { size: A4 portrait; margin: 20mm; }');
const pageRule = sheet.cssRules[index];

console.log(pageRule instanceof CSSPageRule); // true

const setLandscape = (landscape) => {
  pageRule.style.setProperty('size', landscape ? 'A4 landscape' : 'A4 portrait');
};

setLandscape(true);
console.log(pageRule.cssText);
window.print();

true @page { size: A4 landscape; margin: 20mm; }

Seitenselektor über selectorText ändern

const style = document.createElement('style');
style.textContent = '@page :first { margin-top: 50mm; }';
document.head.append(style);

const rule = style.sheet.cssRules[0];
console.log(rule.selectorText); // ":first"

// Der große obere Rand soll jetzt für alle linken Seiten gelten
rule.selectorText = ':left';
console.log(rule.selectorText);
console.log(rule.style.getPropertyValue('margin-top'));

:first :left 50mm

// Wichtig · Fallstricke

Vererbung: Nach der aktuellen Spezifikation erbt CSSPageRule von CSSGroupingRule, damit verschachtelte Randbereich-Regeln wie @top-left möglich sind. Ältere Browserversionen leiten sie direkt von CSSRule ab. Dort fehlen cssRules und insertRule() auf der Regel selbst.
Typ prüfen: Verwenden Sie rule instanceof CSSPageRule. Der Vergleich rule.type === CSSRule.PAGE_RULE (Wert 6) gilt als veraltet.
style: Der Typ heißt in neueren Implementierungen CSSPageDescriptors, in älteren CSSStyleDeclaration. Die Methoden setProperty() und getPropertyValue() funktionieren mit beiden.
Unterstützung der Deskriptoren: Ob Deskriptoren wie size, page-orientation oder Randbereich-Regeln tatsächlich wirken, ist je nach Browser verschieden. Safari und Firefox haben sie zum Teil erst spät eingeführt. Das Ergebnis sollte man immer in der Druckvorschau prüfen.
Ungültiger Selektor: Wird selectorText auf einen ungültigen Wert gesetzt, ignoriert der Browser die Zuweisung stillschweigend. Es gibt keine Fehlermeldung.
CORS: Der Zugriff auf cssRules von Stylesheets anderer Herkunft ohne passende CORS-Header löst einen SecurityError aus. Deshalb im Code mit try/catch absichern.

Siehe auch

window.print() CSSRule CSSScopeRule CSSStyleRule CSSImageValue