Serialisierung von CSS-Werten

Wann und wie Werte serialisiert werden

Die Serialisierung erfolgt immer dann, wenn CSS-Eigenschaftswerte über JavaScript-APIs als Zeichenfolgen ausgelesen werden, beispielsweise durch:

• CSSStyleDeclaration.getPropertyValue()
• CSSStyleDeclaration.cssText
• Direkten Zugriff auf Eigenschaften von CSSStyleDeclaration-Objekten (z. B. element.style.backgroundColor)

Verschiedene APIs geben CSSStyleDeclaration-Objekte aus unterschiedlichen Phasen der Wertverarbeitung zurück. Ihr Verhalten bei der Serialisierung unterscheidet sich daher geringfügig. Beispielsweise geben Window.getComputedStyle() und HTMLElement.style den aufgelösten Wert von Eigenschaften zurück, während CSSStyleRule.style mehr oder weniger den deklarierten Wert zurückgibt.

Für jeden CSS-Werttyp legen die CSS-Spezifikationen ein Serialisierungsformat fest. Einige häufige Regeln sind:

• Schlüsselwörter (wie auto, block, none) werden vollständig in Kleinbuchstaben serialisiert.
• <angle>: wird in einer Winkeleinheit serialisiert, die vom Kontext abhängt (nicht genauer festgelegt). Bei element.style und getComputedStyle() ist dies deg.
• <color>:
  • sRGB-Farben (<named-color>, transparent, <system-color>, <hex-color>, rgb, hsl, hwb): werden in der herkömmlichen, durch Kommas getrennten Syntax rgb(R, G, B) oder rgba(R, G, B, A) serialisiert, wobei alle Argumente Zahlen sind. Die Form rgb wird verwendet, wenn der Alphawert genau 1 ist.
  • Bei Farben mit lab(), lch(), oklab(), oklch() und color() bleibt die Funktionsform mit numerischen Argumenten erhalten.
  • Das Schlüsselwort currentColor wird als currentcolor serialisiert.
• <percentage>: bleibt als Prozentwert erhalten.
• <ratio>: wird als zwei Zahlen serialisiert, die durch " / " getrennt sind.
• <url>: wird als <url> mit Anführungszeichen (url("...")) serialisiert, wobei die URL zu einer absoluten URL aufgelöst wird.

Beachten Sie, dass <percentage>-Werte bei der Wertverarbeitung häufig in absolute Größen (wie <length>) umgerechnet werden. Daher erscheinen sie bei der Serialisierung berechneter Stile möglicherweise nicht mehr als Prozentwerte. Bei Größen mit Einheiten, etwa <frequency>, <length>, <resolution> und <time>, hängt die serialisierte Einheit vom Kontext ab und ist nicht genau spezifiziert. getComputedStyle() und element.style serialisieren diese Werte jeweils in Hz, px, dppx und s.

Bei der Serialisierung des Werts einer Kurzschreibweise werden die zugehörigen Langschreibweise-Eigenschaften serialisiert und nach den Regeln der jeweiligen Kurzschreibweise zusammengeführt.

<div>Example Element</div>

div {
  position: absolute; /* keyword */
  rotate: 1rad; /* <angle> */
  color: hsl(240 50% 50%); /* <color> */
  background-color: hsl(120 50% 50% / 0.3); /* <color> with alpha */
  border-color: lab(10 -120 -120); /* <color> in non-sRGB space */
  margin: 2em; /* relative <length> */
  padding: 2cm; /* absolute <length> */
  font-size: calc(1em + 2px); /* complex expression */
  left: 50%; /* <percentage> */
  animation-duration: 500ms; /* <time> */
}

const element = document.querySelector("div");
const table = document.createElement("table");
const elemStyle = getComputedStyle(element);
const ruleStyle = document.getElementById("css-output").sheet.cssRules[0].style;
const head = table.createTHead().insertRow();
["Property", "getComputedStyle()", "CSSStyleRule"].forEach((text) => {
  const th = document.createElement("th");
  th.textContent = text;
  head.appendChild(th);
});
for (const property of [
  "position",
  "rotate",
  "color",
  "background-color",
  "border-color",
  "margin",
  "padding",
  "font-size",
  "left",
  "animation-duration",
]) {
  const row = document.createElement("tr");
  const propCell = document.createElement("td");
  const valueCell = document.createElement("td");
  const ruleCell = document.createElement("td");
  propCell.textContent = property;
  valueCell.textContent = elemStyle.getPropertyValue(property);
  ruleCell.textContent = ruleStyle.getPropertyValue(property);
  row.appendChild(propCell);
  row.appendChild(valueCell);
  row.appendChild(ruleCell);
  table.appendChild(row);
}
document.body.appendChild(table);

Beispiele

Serialisierung von Farbwerten

Farben gehören zu den häufigsten Werttypen, die von der Serialisierung betroffen sind. Unabhängig davon, ob Sie eine Farbe mit hsl(), hwb(), einem Schlüsselwort oder einem modernen Farbraum definieren, gibt JavaScript sie normalerweise im herkömmlichen Format rgb() oder rgba() zurück.

Die folgenden Beispiele zeigen, wie verschiedene Farbformate beim Zugriff über JavaScript serialisiert werden.

<div class="example hsl">HSL Color</div>
<div class="example lab">LAB Color</div>
<div class="example named">Named Color</div>
<div class="example alpha">Transparent Color</div>
<pre id="output"></pre>

.example {
  padding: 10px;
  margin: 5px;
  color: white;
}

.hsl {
  background-color: hsl(240 50% 50%);
}

.lab {
  background-color: lab(100% 0 0);
}

.named {
  background-color: blue;
}

.alpha {
  background-color: hsl(120 50% 50% / 0.3);
}

const examples = document.querySelectorAll(".example");
const output = document.getElementById("output");

examples.forEach((element) => {
  const style = getComputedStyle(element);
  output.textContent += `${element.className}: ${style.getPropertyValue("background-color")}\n`;
});

Serialisierung von Längenwerten

Längen sind ein weiterer häufiger Fall. Relative Einheiten (wie em und %) werden bei der Serialisierung über JavaScript-APIs häufig in absolute Pixelwerte aufgelöst.

element.style.marginLeft = "2em";
console.log(getComputedStyle(element).marginLeft);
// "32px" (depending on font size)

Diese Normalisierung ermöglicht es Skripten, Längen konsistent zu vergleichen oder mit ihnen zu rechnen.

Spezifikationen

Siehe auch

• CSSStyleDeclaration.getPropertyValue()
• Window.getComputedStyle()
• CSS-Farben
• <color>
• Modul CSS-Werte und -Einheiten