CSSPrimitiveValue.getRectValue() — Methode · JavaScript-Referenz

Signatur

CSSPrimitiveValue.prototype.getRectValue()

Beschreibung

Die Methode getRectValue() gehört zum veralteten Interface CSSPrimitiveValue aus der Spezifikation DOM Level 2 Style. Sie liest einen primitiven CSS-Wert aus, der als Rechteck-Funktion rect(top, right, bottom, left) notiert ist. Praktisch betrifft das fast nur die Eigenschaft clip.

Zurückgegeben wird ein Rect-Objekt. Dessen Eigenschaften top, right, bottom und left sind wiederum CSSPrimitiveValue-Objekte. Die Zahlenwerte liest man dann mit getFloatValue(unitType) aus, z. B. mit CSSPrimitiveValue.CSS_PX. Ein CSSPrimitiveValue erhielt man früher über CSSStyleDeclaration.getPropertyCSSValue() bzw. getComputedStyle(el).getPropertyCSSValue("clip").

Die Methode prüft vorher, ob primitiveType gleich CSSPrimitiveValue.CSS_RECT ist. Ist das nicht der Fall, wird eine DOMException vom Typ InvalidAccessError ausgelöst.

Heute sollte man die Methode nicht mehr verwenden. In neuem Code liest man den Wert als Zeichenkette über getComputedStyle() und getPropertyValue() aus, oder man nutzt das CSS Typed OM (element.computedStyleMap()). Die Eigenschaft clip selbst ist ebenfalls veraltet; ihr Nachfolger ist clip-path: inset(...).

Rückgabewert

Typ

Rect

Beschreibung

Ein Rect-Objekt mit den schreibgeschützten Eigenschaften top, right, bottom und left, jeweils vom Typ CSSPrimitiveValue. Ist der Wert kein rect(), wird eine DOMException (InvalidAccessError) ausgelöst.

Beispiele

Historische Nutzung mit Feature-Erkennung

// <div id="box" style="position:absolute; clip: rect(10px, 200px, 150px, 20px)"></div>
const box = document.getElementById('box');
const style = getComputedStyle(box);

if (typeof style.getPropertyCSSValue === 'function') {
  // Nur in sehr alten Browsern verfügbar
  const value = style.getPropertyCSSValue('clip');
  if (value.primitiveType === CSSPrimitiveValue.CSS_RECT) {
    const rect = value.getRectValue();
    const px = CSSPrimitiveValue.CSS_PX;
    console.log(rect.top.getFloatValue(px), rect.right.getFloatValue(px),
                rect.bottom.getFloatValue(px), rect.left.getFloatValue(px));
  }
} else {
  console.log('getRectValue() wird nicht unterstützt:', style.getPropertyValue('clip'));
}

getRectValue() wird nicht unterstützt: rect(10px, 200px, 150px, 20px)

Moderner Ersatz: rect()-Zeichenkette selbst zerlegen

const parseClipRect = (el) => {
  const raw = getComputedStyle(el).getPropertyValue('clip');
  const match = raw.match(/^rect\((.+)\)$/);
  if (!match) return null; // z. B. "auto"
  const [top, right, bottom, left] = match[1]
    .split(/[\s,]+/)
    .map((part) => (part === 'auto' ? null : parseFloat(part)));
  return { top, right, bottom, left };
};

const box = document.getElementById('box');
console.log(parseClipRect(box));

{ top: 10, right: 200, bottom: 150, left: 20 }

Abfangen des InvalidAccessError (Legacy-Code)

const readRect = (primitiveValue) => {
  try {
    return primitiveValue.getRectValue();
  } catch (err) {
    if (err instanceof DOMException && err.name === 'InvalidAccessError') {
      console.warn('Wert ist kein rect():', primitiveValue.cssText);
      return null;
    }
    throw err;
  }
};

// Wichtig · Fallstricke

Veraltet und entfernt: CSSPrimitiveValue, getPropertyCSSValue() und getRectValue() gibt es in aktuellen Versionen von Chrome, Edge, Firefox (ab Version 62 entfernt) und Safari nicht mehr. Code, der die Methode ohne Feature-Erkennung aufruft, löst einen TypeError aus.
Stattdessen getComputedStyle(el).getPropertyValue('clip') verwenden und die Zeichenkette selbst auswerten, oder das CSS Typed OM (el.computedStyleMap()) nutzen.
Die Eigenschaft clip wirkt nur auf absolut oder fest positionierte Elemente und ist selbst veraltet. Nimm besser clip-path: inset(...).
Die einzelnen Kanten können auto sein. getFloatValue() löst dann eine Ausnahme aus, deshalb vorher primitiveType prüfen.
Ältere Notationen wie rect(10px 200px 150px 20px) ohne Kommas sind erlaubt. Ein eigener Parser muss also Leerzeichen und Kommas als Trennzeichen akzeptieren.

Siehe auch

CSSPrimitiveValue.getCounterValue() CSSPrimitiveValue.getFloatValue() CSSPrimitiveValue.getStringValue() CSSPrimitiveValue.setFloatValue() CSSPrimitiveValue.getRGBColorValue()