CSS-Wertserialisierung

Wann und wie Werte serialisiert werden

Serialisierung passiert immer dann, wenn CSS-Eigenschaftswerte als Zeichenfolgen über JavaScript-APIs gelesen werden, wie zum Beispiel:

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

Verschiedene APIs geben CSSStyleDeclaration-Objekte in unterschiedlichen Stadien der Wertverarbeitung zurück, die leicht unterschiedliche Serialisierungsverhalten haben. Zum Beispiel 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.

Jeder CSS-Werttyp hat ein zugehöriges Serialisierungsformat, das durch die CSS-Spezifikationen definiert ist. Einige allgemeine Regeln sind:

• Schlüsselwörter (wie auto, block, none) werden in Kleinbuchstaben serialisiert.
• <angle>: wird in eine Winkelmaßeinheit serialisiert, abhängig vom Kontext (nicht spezifiziert). Für element.style und getComputedStyle() ist das deg.
• <color>:
  • Für sRGB-Farben (<named-color>, transparent, <system-color>, <hex-color>, rgb, hsl, hwb): serialisiert in die veraltete kommaseparierte Syntax rgb(R, G, B) oder rgba(R, G, B, A), wobei alle Argumente Zahlen sind. Die rgb-Form wird ausgewählt, wenn der Alpha-Wert genau 1 ist.
  • Für lab(), lch(), oklab(), oklch() und color() Farben: die Funktionsform bleibt erhalten, mit numerischen Argumenten.
  • Das Schlüsselwort currentColor wird als currentcolor serialisiert.
• <percentage>: bleibt als Prozentwert erhalten.
• <ratio>: wird in zwei durch " / " getrennte Zahlen serialisiert.
• <url>: wird als ein zitierter <url> (url("...")) serialisiert, wobei die URL in eine absolute URL aufgelöst wird.

Beachten Sie, dass <percentage>-Werte oft in absolute Dimensionen (wie <length>) während der Wertverarbeitung umgewandelt werden, sodass sie möglicherweise nicht als Prozentsätze erscheinen, wenn sie aus berechneten Stilen serialisiert werden. Bei Dimensionen mit Einheiten, wie <frequency>, <length>, <resolution>, und <time>, hängt die serialisierte Einheit vom Kontext ab und ist nicht gut spezifiziert. getComputedStyle() und element.style serialisieren sie in Hz, px, dppx und s jeweils.

Bei der Serialisierung des Wertes für Kurzschreibweiseigenschaften werden seine konstituierenden Langform-Eigenschaften gemäß den Regeln für diese Kurzform serialisiert und kombiniert.

<div>Example Element</div>

div {
  position: absolute; /* keyword */
  rotate: 1rad; /* <angle> */
  color: hsl(240 100% 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

Farbwertserialisierung

Farben gehören zu den am häufigsten von der Serialisierung betroffenen Typen. Unabhängig davon, ob man eine Farbe mit hsl(), hwb(), einem Schlüsselwort oder einem modernen Farbraum definiert, gibt JavaScript sie normalerweise im veralteten rgb()- oder rgba()-Format zurück.

Die folgenden Beispiele zeigen, wie verschiedene Farbformate serialisiert werden, wenn darauf über JavaScript zugegriffen wird.

<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 100% 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`;
});

Längenwertserialisierung

Längen sind ein weiterer häufiger Fall. Relative Einheiten (wie em, %) werden oft in absolute Pixel umgerechnet, wenn sie durch JavaScript-APIs serialisiert werden.

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 zu berechnen.

Spezifikationen

Siehe auch

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