Die CSS Properties and Values API verwenden
Baseline 2024
Newly available
Since July 2024, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.
Die CSS Properties and Values API — Teil der CSS Houdini Gruppe von APIs — ermöglicht die Registrierung von CSS-Benutzerdefinierten Eigenschaften, wodurch Typprüfungen, Standardwerte und Eigenschaften, die ihren Wert erben oder nicht, ermöglicht werden.
Eine benutzerdefinierte Eigenschaft registrieren
Die Registrierung einer benutzerdefinierten Eigenschaft erlaubt es Ihnen, dem Browser mitzuteilen, wie sich die benutzerdefinierte Eigenschaft verhalten soll: welche Typen erlaubt sind, ob die benutzerdefinierte Eigenschaft ihren Wert erbt und welchen Standardwert die benutzerdefinierte Eigenschaft hat. Es gibt zwei Möglichkeiten, eine Eigenschaft zu registrieren: in JavaScript oder in CSS.
CSS.registerProperty
Das Folgende registriert eine benutzerdefinierte Eigenschaft namens --my-prop
mit CSS.registerProperty
. --my-prop
verwendet die CSS-Farbsyntax, hat einen Standardwert von #c0ffee
und wird seinen Wert nicht erben:
window.CSS.registerProperty({
name: "--my-prop",
syntax: "<color>",
inherits: false,
initialValue: "#c0ffee",
});
@property
Die gleiche Registrierung kann in CSS erfolgen. Das Folgende registriert eine benutzerdefinierte Eigenschaft namens --my-prop
mit dem @property
At-rule. --my-prop
verwendet die CSS-Farbsyntax, hat einen Standardwert von #c0ffee
und wird seinen Wert nicht erben:
@property --my-prop {
syntax: "<color>";
inherits: false;
initial-value: #c0ffee;
}
Verwendung registrierter benutzerdefinierter Eigenschaften
Ein Vorteil der Registrierung einer Eigenschaft besteht darin, dass der Browser jetzt weiß, wie er mit Ihrer benutzerdefinierten Eigenschaft umgehen soll, z. B. bei Übergängen! Wenn eine Eigenschaft nicht registriert ist, weiß der Browser nicht, wie er sie behandeln soll, daher geht er davon aus, dass jeder Wert verwendet werden kann, und kann sie daher nicht animieren. Wenn eine Eigenschaft jedoch eine registrierte Syntax besitzt, kann der Browser diese Syntax optimieren, einschließlich der Fähigkeit, sie zu animieren!
In diesem Beispiel wurde die benutzerdefinierte Eigenschaft --registered
mit der Syntax <color>
registriert und dann in einem linearen Gradient verwendet. Diese Eigenschaft wird dann bei Hover oder Fokus auf eine andere Farbe überführt. Beachten Sie, dass der Übergang mit der registrierten Eigenschaft funktioniert, nicht jedoch mit der nicht registrierten!
HTML
<button class="registered">Background Registered</button>
<button class="unregistered">Background Not Registered</button>
CSS
.registered {
--registered: #c0ffee;
background-image: linear-gradient(to right, #fff, var(--registered));
transition: --registered 1s ease-in-out;
}
.registered:hover,
.registered:focus {
--registered: #b4d455;
}
.unregistered {
--unregistered: #c0ffee;
background-image: linear-gradient(to right, #fff, var(--unregistered));
transition: --unregistered 1s ease-in-out;
}
.unregistered:hover,
.unregistered:focus {
--unregistered: #b4d455;
}
button {
height: 40vh;
display: block;
width: 100%;
font-size: 3vw;
}
JavaScript
window.CSS.registerProperty({
name: "--registered",
syntax: "<color>",
inherits: false,
initialValue: "red",
});
Ergebnis
Obwohl es nicht funktional zutreffend ist, lässt sich der Unterschied zwischen der nicht registrierten Eigenschaft im obigen Beispiel und der registrierten Eigenschaft gut mit dem Unterschied zwischen einem <custom-ident>
und einer Zahl beim Versuch einer Animation von height
veranschaulichen. Sie können nicht von auto
zu einer Zahl übergehen oder animieren, weil der Browser den Wert von auto
nicht kennt, bis er berechnet wird. Bei einer nicht registrierten Eigenschaft weiß der Browser ebenfalls nicht, welchen Wert sie haben könnte, bis er berechnet wird, und kann deshalb keinen Übergang von einem Wert zu einem anderen einrichten. Bei einer registrierten Eigenschaft haben Sie jedoch dem Browser mitgeteilt, welchen Wertetyp er erwarten sollte, und weil er das weiß, kann er dann die Übergänge korrekt einrichten.
Stolpersteine
Es gibt zwei Stolpersteine bei der Registrierung einer Eigenschaft. Der erste ist, dass es, einmal registriert, keine Möglichkeit gibt, eine Eigenschaft zu aktualisieren. Der Versuch, sie mit JavaScript erneut zu registrieren, wirft einen Fehler, der angibt, dass sie bereits definiert wurde.
Zweitens, im Gegensatz zu Standardmeldungen, werden registrierte Eigenschaften nicht validiert, wenn sie geparst werden. Vielmehr werden sie validiert, wenn sie berechnet werden. Das bedeutet sowohl, dass ungültige Werte beim Inspizieren der Eigenschaften des Elements nicht als ungültig erscheinen werden, und dass das Einschließen einer ungültigen Eigenschaft nach einer gültigen nicht auf die gültige Eigenschaft zurückfallen wird. Eine ungültige Eigenschaft wird jedoch auf ihren registrierten Standardwert zurückfallen.
Browser-Kompatibilität
BCD tables only load in the browser