CSSPrimitiveValue.setStringValue() — Methode · JavaScript-Referenz

Signatur

CSSPrimitiveValue.prototype.setStringValue(stringType, stringValue)

Beschreibung

setStringValue() gehört zum alten CSS-Objektmodell aus DOM Level 2 CSS. Die Methode sollte einem primitiven CSS-Wert, den man z. B. über getPropertyCSSValue() bekam, einen neuen String-Wert zuweisen. Der erste Parameter gibt an, wie der String gemeint ist: als CSS-String (CSS_STRING), URL (CSS_URI), Bezeichner bzw. Schlüsselwort (CSS_IDENT) oder attr()-Verweis (CSS_ATTR).

In der Praxis funktionierte die Methode fast nirgends. Werte aus berechneten Stilen (getComputedStyle()) waren schreibgeschützt, deshalb warf der Aufruf meist nur eine DOMException mit dem Code NO_MODIFICATION_ALLOWED_ERR. Chrome, Safari und Firefox (ab Version 62) haben CSSPrimitiveValue inzwischen ganz entfernt.

Für neuen Code nimmst du stattdessen CSSStyleDeclaration.setProperty() (element.style.setProperty()) oder das CSS Typed Object Model mit element.attributeStyleMap.set(). Die Methode ist hier nur dokumentiert, damit du alten Code verstehen und umschreiben kannst.

Parameter

Name	Typ	Default	Beschreibung
$stringType Pflicht	number		Art des String-Werts. Erlaubt sind `CSSPrimitiveValue.CSS_STRING` (19), `CSS_URI` (20), `CSS_IDENT` (21) und `CSS_ATTR` (22). Andere Typen lösen `INVALID_ACCESS_ERR` aus.
$stringValue Pflicht	string		Der neue Wert ohne CSS-Syntax drumherum, also z. B. `"bild.png"` statt `url(bild.png)` oder `"bold"` als Bezeichner.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined). Bei Fehlern wird eine DOMException ausgelöst.

Beispiele

Unterstützung prüfen, bevor man die Methode nutzt

// Prüfen, ob die veraltete API überhaupt vorhanden ist
const hatAlteApi = typeof window.CSSPrimitiveValue !== 'undefined' &&
  typeof CSSPrimitiveValue.prototype.setStringValue === 'function';

console.log(hatAlteApi
  ? 'CSSPrimitiveValue.setStringValue() ist verfügbar'
  : 'Veraltete API nicht vorhanden – moderne Alternative nutzen');

Veraltete API nicht vorhanden – moderne Alternative nutzen

Alter Code mit Fehlerbehandlung (historisches Muster)

const el = document.body;
const style = getComputedStyle(el);

try {
  // Gab es nur in alten Browsern; berechnete Werte waren schreibgeschützt
  const wert = style.getPropertyCSSValue('font-family');
  wert.setStringValue(CSSPrimitiveValue.CSS_IDENT, 'serif');
} catch (err) {
  // TypeError (API fehlt) oder DOMException (NO_MODIFICATION_ALLOWED_ERR)
  console.log(`Nicht möglich: ${err.name}`);
}

Nicht möglich: TypeError

Moderner Ersatz: setProperty() und Typed OM

const box = document.createElement('div');
document.body.append(box);

// Ersatz für CSS_URI
box.style.setProperty('background-image', 'url("muster.png")');

// Ersatz für CSS_IDENT – mit CSS Typed OM, falls verfügbar
if (box.attributeStyleMap) {
  box.attributeStyleMap.set('font-weight', new CSSKeywordValue('bold'));
} else {
  box.style.setProperty('font-weight', 'bold');
}

// Ersatz für CSS_STRING
box.style.setProperty('quotes', '"«" "»"');

console.log(box.style.fontWeight);

bold

// Wichtig · Fallstricke

Veraltet und entfernt: CSSPrimitiveValue und getPropertyCSSValue() gibt es in Chrome/Edge und Safari nicht mehr. Firefox hat die API mit Version 62 entfernt. Ein Aufruf endet heute mit einem TypeError.
Schreibschutz: Auch als die API noch existierte, waren Werte aus getComputedStyle() schreibgeschützt. Der Aufruf warf dann NO_MODIFICATION_ALLOWED_ERR.
Falscher Typ: War der Wert kein String-Typ oder passte stringType nicht dazu, kam INVALID_ACCESS_ERR.
Umstellung: Nimm element.style.setProperty(name, wert) oder element.attributeStyleMap.set() (CSS Typed OM, in Chromium-Browsern und Safari; in Firefox nur eingeschränkt).

Siehe auch

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