Serialisierung von CSS-Werten

Wann und wie Werte serialisiert werden

Eine Serialisierung findet immer dann statt, wenn CSS-Eigenschaftswerte über JavaScript-APIs als Zeichenketten gelesen werden, beispielsweise durch:

• CSSStyleDeclaration.getPropertyValue()
• CSSStyleDeclaration.cssText
• den 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 Serialisierungsverhalten 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 ist in den CSS-Spezifikationen ein Serialisierungsformat definiert. Zu den häufigen Regeln gehören:

• Schlüsselwörter (wie auto, block, none) werden vollständig kleingeschrieben serialisiert.
• <angle>: wird in einer vom Kontext abhängigen, nicht festgelegten Winkeleinheit serialisiert. 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 beträgt.
  • Bei Farben in 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 durch " / " getrennte Zahlen serialisiert.
• <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. Bei der Serialisierung berechneter Stile erscheinen sie daher möglicherweise nicht 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 einzelnen Eigenschaften serialisiert und gemäß den Regeln für diese Kurzschreibweise kombiniert.

<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 Werttypen, die am häufigsten 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 üblicherweise im herkömmlichen Format rgb() oder rgba() zurück.

Die folgenden Beispiele zeigen, wie unterschiedliche 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 oft 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 einheitlich zu vergleichen oder mit ihnen zu rechnen.

Spezifikationen

Siehe auch

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