CSSPageDescriptors — Schnittstelle · JavaScript-Referenz

Signatur

interface CSSPageDescriptors extends CSSStyleDeclaration

Beschreibung

Das Interface CSSPageDescriptors steht für den Deklarationsblock einer @page-At-Regel. Es wird nicht selbst erzeugt. Man erhält es über die Eigenschaft style eines CSSPageRule-Objekts, das man wiederum in CSSStyleSheet.cssRules findet.

Weil es von CSSStyleDeclaration erbt, stehen alle bekannten Methoden zur Verfügung: getPropertyValue(), setProperty(), removeProperty() und cssText. Dazu kommen eigene Eigenschaften für die Deskriptoren, die in @page erlaubt sind. Es gibt sie jeweils in camelCase und mit Bindestrich:

margin, marginTop/margin-top, marginRight/margin-right, marginBottom/margin-bottom, marginLeft/margin-left: die Seitenränder
size: Seitengröße und Ausrichtung, z. B. "A4 landscape"
pageOrientation/page-orientation: dreht die Seite (upright, rotate-left, rotate-right)

Typische Einsatzfälle sind Web-Anwendungen mit Druckfunktion, z. B. Rechnungen, Berichte oder Etiketten. Dort sollen Papierformat und Ränder vor dem Aufruf von window.print() dynamisch angepasst werden, ohne ein neues Stylesheet zu laden.

Rückgabewert

Typ

CSSPageDescriptors

Beschreibung

Wird von CSSPageRule.style zurückgegeben und enthält die Deskriptoren der zugehörigen @page-Regel.

Beispiele

@page-Regel finden und Deskriptoren auslesen

// Stylesheet mit einer @page-Regel anlegen
const style = document.createElement('style');
style.textContent = '@page { size: A4; margin: 2cm; }';
document.head.append(style);

const pageRule = [...style.sheet.cssRules]
  .find((rule) => rule instanceof CSSPageRule);

const descriptors = pageRule.style;
console.log(descriptors.constructor.name);
console.log(descriptors.size);
console.log(descriptors.marginTop);
console.log(descriptors.getPropertyValue('margin-left'));

CSSPageDescriptors (Firefox; andere Browser: CSSStyleDeclaration) A4 2cm 2cm

Druckformat vor dem Drucken dynamisch umstellen

const getPageRule = () => {
  for (const sheet of document.styleSheets) {
    try {
      const rule = [...sheet.cssRules].find((r) => r instanceof CSSPageRule);
      if (rule) return rule;
    } catch {
      // Fremd-Stylesheets (CORS) überspringen
    }
  }
  // Keine Regel vorhanden: eine anlegen
  const el = document.createElement('style');
  document.head.append(el);
  el.sheet.insertRule('@page {}');
  return el.sheet.cssRules[0];
};

const printLandscape = () => {
  const { style } = getPageRule();
  style.size = 'A4 landscape';
  style.margin = '1cm 1.5cm';
  console.log(style.cssText);
  window.print();
};

printLandscape();

size: A4 landscape; margin: 1cm 1.5cm;

Deskriptor per setProperty/removeProperty ändern

const el = document.createElement('style');
document.head.append(el);
el.sheet.insertRule('@page { margin: 25mm; }');
const { style } = el.sheet.cssRules[0];

style.setProperty('margin-bottom', '40mm'); // Platz für eine Fußzeile
console.log(style.marginBottom);

style.removeProperty('margin');
console.log(style.cssText === '');

40mm true

// Wichtig · Fallstricke

Browser-Kompatibilität: Den eigenen Typ CSSPageDescriptors gibt es bisher nur in Firefox (ab Version 129). In Chromium-Browsern und Safari liefert CSSPageRule.style ein normales CSSStyleDeclaration. Dort funktionieren getPropertyValue() und setProperty() ebenfalls, die camelCase-Eigenschaften (z. B. pageOrientation) können aber fehlen. Deshalb möglichst nicht per instanceof CSSPageDescriptors prüfen, sondern die Methoden von CSSStyleDeclaration verwenden.

Nur Deskriptoren, die in @page erlaubt sind, werden übernommen. Ungültige Eigenschaften wie color oder ungültige Werte werden stillschweigend ignoriert.
Wie gut size und page-orientation umgesetzt werden, hängt vom Browser ab. Oft kann der Druckdialog die Werte überschreiben.
Bei Stylesheets von fremden Origins löst der Zugriff auf cssRules einen SecurityError aus (CORS). Deshalb den Zugriff in try/catch kapseln.
Die Änderungen betreffen nur Druckausgabe und Druckvorschau, nicht die Darstellung auf dem Bildschirm.

Siehe auch

Window.print() CSSFontFaceDescriptors CSSFunctionDescriptors AudioParamDescriptor TrustedScriptURL