SVGClipPathElement.clipPathUnits — Eigenschaft · JavaScript-Referenz

Signatur

SVGClipPathElement.clipPathUnits

Beschreibung

Die schreibgeschützte Eigenschaft clipPathUnits des Interfaces SVGClipPathElement gibt ein SVGAnimatedEnumeration-Objekt zurück. Es spiegelt das Attribut clipPathUnits des <clipPath>-Elements wider. Das Attribut legt fest, in welchem Koordinatensystem die Formen innerhalb des Beschneidungspfads gelesen werden.

Es gibt zwei gültige Werte:

userSpaceOnUse (Standard, Konstante SVG_UNIT_TYPE_USERSPACEONUSE = 1): Die Koordinaten beziehen sich auf das Benutzerkoordinatensystem des Elements, das auf den Beschneidungspfad verweist.
objectBoundingBox (Konstante SVG_UNIT_TYPE_OBJECTBOUNDINGBOX = 2): Die Koordinaten sind Anteile (0 bis 1) am umschließenden Rechteck (Bounding Box) des beschnittenen Elements. Dadurch lässt sich ein einziger clipPath für Elemente jeder Größe verwenden.

Die Eigenschaft selbst ist schreibgeschützt, der Wert jedoch nicht: Über clipPathUnits.baseVal kannst du ihn lesen und ändern, über clipPathUnits.animVal liest du den aktuell (ggf. animierten) Wert. Im Alltag nutzt man sie vor allem, um per Skript zu prüfen, wie ein vorhandener Beschneidungspfad ausgelegt ist, oder um zwischen absoluten und relativen Koordinaten umzuschalten.

Rückgabewert

Typ

SVGAnimatedEnumeration

Beschreibung

Objekt mit baseVal (lesbar und schreibbar) und animVal (nur lesbar). Beide enthalten eine Zahl: 0 (SVG_UNIT_TYPE_UNKNOWN), 1 (userSpaceOnUse) oder 2 (objectBoundingBox).

Beispiele

Aktuellen Einheitentyp auslesen

// <svg><clipPath id="clip" clipPathUnits="objectBoundingBox">
//   <circle cx="0.5" cy="0.5" r="0.5" /></clipPath></svg>
const clip = document.getElementById('clip');
const { baseVal } = clip.clipPathUnits;

const names = {
  [SVGUnitTypes.SVG_UNIT_TYPE_USERSPACEONUSE]: 'userSpaceOnUse',
  [SVGUnitTypes.SVG_UNIT_TYPE_OBJECTBOUNDINGBOX]: 'objectBoundingBox'
};

console.log(baseVal, names[baseVal]);

2 objectBoundingBox

Standardwert ohne Attribut

const svgNS = 'http://www.w3.org/2000/svg';
const clip = document.createElementNS(svgNS, 'clipPath');

// Kein Attribut gesetzt → Standard userSpaceOnUse
console.log(clip.clipPathUnits.baseVal === SVGUnitTypes.SVG_UNIT_TYPE_USERSPACEONUSE);

true

Auf relative Koordinaten umschalten

const svgNS = 'http://www.w3.org/2000/svg';
const svg = document.querySelector('svg');

const clip = document.createElementNS(svgNS, 'clipPath');
clip.id = 'rundClip';
const circle = document.createElementNS(svgNS, 'circle');
circle.setAttribute('cx', '0.5');
circle.setAttribute('cy', '0.5');
circle.setAttribute('r', '0.5');
clip.append(circle);
svg.append(clip);

// baseVal ist schreibbar – Eigenschaft selbst nicht
clip.clipPathUnits.baseVal = SVGUnitTypes.SVG_UNIT_TYPE_OBJECTBOUNDINGBOX;
console.log(clip.getAttribute('clipPathUnits'));

// Jedes Element wird nun passend zu seiner Größe rund beschnitten
svg.querySelectorAll('image').forEach((img) => {
  img.setAttribute('clip-path', 'url(#rundClip)');
});

objectBoundingBox

// Wichtig · Fallstricke

Kein direktes Zuweisen: clip.clipPathUnits = 2 hat keine Wirkung (im Strict Mode gibt es einen TypeError). Ändere stattdessen clipPathUnits.baseVal oder rufe setAttribute('clipPathUnits', …) auf.
Ein ungültiger Wert für baseVal (z. B. 0 oder 3) löst einen TypeError aus.
Bei objectBoundingBox brauchen die Formen Werte zwischen 0 und 1. Übernimmst du Pixelwerte wie cx="50", liegt der Pfad weit außerhalb, und das Element verschwindet vollständig.
Bei objectBoundingBox wird ein Element ohne Fläche (Breite oder Höhe 0, z. B. eine waagerechte Linie) nicht dargestellt.
Die Konstanten findest du im globalen Objekt SVGUnitTypes. Ältere Browser stellen sie teilweise nur auf dem Element bereit.
Kompatibilität: wird in allen modernen Browsern unterstützt.

Siehe auch

SVGClipPathElement SVGAnimatedEnumeration SVGUnitTypes SVGMaskElement.maskUnits SVGGraphicsElement.getBBox() SVGClipPathElement.transform SVGPathElement.pathLength