Die@property-CSS-At-Regel wird verwendet, umbenutzerdefinierte CSS-Eigenschaften explizit zu definieren. Dies ermöglicht die Überprüfung und Einschränkung von Eigenschaftstypen, das Setzen von Standardwerten und die Definition, ob eine benutzerdefinierte Eigenschaft vererbt werden kann oder nicht.

Syntax

@property --canBeAnything {  syntax: "*";  inherits: true;}@property --rotation {  syntax: "<angle>";  inherits: false;  initial-value: 45deg;}@property --defaultSize {  syntax: "<length> | <percentage>";  inherits: true;  initial-value: 200px;}

Der Name der benutzerdefinierten Eigenschaft ist ein<dashed-ident>, der mit-- beginnt und von einem gültigen, benutzerdefinierten Bezeichner gefolgt wird. Er ist case-sensitive.

Deskriptoren

syntax

Ein String, der die zulässigen Wertetypen für die registrierte benutzerdefinierte Eigenschaft beschreibt.

inherits

Ein Boolescher Wert, der steuert, ob die durch@property spezifizierte benutzerdefinierte Eigenschaft standardmäßig vererbt wird.

initial-value

Ein Wert, der den Startwert für die Eigenschaft festlegt.

Beschreibung

Die@property-At-Regel ist Teil derCSS Houdini-API-Sammlung. Sie ermöglicht es Entwicklern,benutzerdefinierte CSS-Eigenschaften explizit zu definieren und dabei die Überprüfung und Einschränkung von Eigenschaftstypen, das Setzen von Standardwerten und die Definition, ob eine benutzerdefinierte Eigenschaft vererbt werden kann oder nicht, zu ermöglichen.

Die@property-Regel erlaubt die Registrierung von benutzerdefinierten Eigenschaften direkt innerhalb von Stylesheets, ohne JavaScript zu benötigen. Gültige@property-Regeln erzeugen registrierte benutzerdefinierte Eigenschaften und haben den gleichen Effekt wie ein Aufruf vonregisterProperty() mit gleichwertigen Parametern.

Die folgenden Bedingungen müssen erfüllt sein, damit die@property-Regel gültig ist:

• Die@property-Regel muss sowohl densyntax- als auch deninherits-Deskriptor enthalten.Fehlt einer von beiden, ist die gesamte@property-Regel ungültig und wird ignoriert.
• Diesyntax kann ein Datentypname sein (wie<color>,<length> oder<number>, etc.), mit Multiplikatoren (+,#) und Kombinatoren (|), einem benutzerdefinierten ident oder der universellen Syntaxdefinition (*), was bedeutet, dass die Syntax jeder gültigen Tokenfolge entsprechen kann. Der Wert ist ein<string> und muss daher in Anführungszeichen stehen.
• Derinitial-value-Deskriptor ist optional, wenn der Wert dessyntax-Deskriptors die universelle Syntaxdefinition ist (syntax: "*").Wird derinitial-value-Deskriptor benötigt, aber weggelassen, ist die gesamte@property-Regel ungültig und wird ignoriert.
• Wenn der Wert dessyntax-Deskriptors nicht die universelle Syntaxdefinition ist, muss derinitial-value-Deskriptor einencomputationally independent Wert haben.Dies bedeutet, dass der Wert in einen berechneten Wert umgewandelt werden kann, ohne von anderen Werten abhängig zu sein, außer von "globalen" Definitionen, die unabhängig von CSS sind.Zum Beispiel ist10px rechnerisch unabhängig—es ändert sich nicht, wenn es in einen berechneten Wert umgewandelt wird.2in ist auch gültig, weil1in immer96px entspricht.3em ist jedoch nicht gültig, weil der Wert vonem von derfont-size des Elternteils abhängt.
• Unbekannte Deskriptoren sind ungültig und werden ignoriert, machen aber die@property-Regel nicht ungültig.

Wenn mehrere gültige@property-Regeln mit demselben Namen definiert sind, "gewinnt" die letzte in der Stylesheet-Reihenfolge. Wenn benutzerdefinierte Eigenschaften mit demselben Namen mit@property in CSS undCSS.registerProperty() in JavaScript registriert werden, gewinnt die JavaScript-Registrierung.

Formale Syntax

@property =
  @property<custom-property-name> {<declaration-list> }

Beispiele

Einfaches Beispiel

In diesem Beispiel verwenden wir die@property-At-Regel, um zwei benutzerdefinierte Eigenschaften zu deklarieren und diese Eigenschaften dann in unseren Style-Deklarationen zu verwenden.

HTML

<p>Hello world!</p>

CSS

@property --myColor {  syntax: "<color>";  inherits: true;  initial-value: rebeccapurple;}@property --myWidth {  syntax: "<length> | <percentage>";  inherits: true;  initial-value: 200px;}p {  background-color: var(--myColor);  width: var(--myWidth);  color: white;}

Ergebnisse

Der Absatz sollte200px breit sein, mit einem lila Hintergrund und weißem Text.

Animieren eines benutzerdefinierten Eigenschaftswertes

In diesem Beispiel definieren wir eine benutzerdefinierte Eigenschaft namens--progress mit@property: Diese akzeptiert<percentage>-Werte und hat einen Anfangswert von25%. Wir verwenden--progress, um den Positionswert der Farbstopps in einemlinear-gradient() zu definieren, der angibt, wo eine grüne Farbe stoppt und schwarz beginnt. Dann animieren wir den Wert von--progress auf100% über 2,5 Sekunden, was den Effekt animierter Fortschrittsbalken ergibt.

HTML

<div></div>

CSS

@property --progress {  syntax: "<percentage>";  inherits: false;  initial-value: 25%;}.bar {  display: inline-block;  --progress: 25%;  width: 100%;  height: 5px;  background: linear-gradient(    to right,    #00d230 var(--progress),    black var(--progress)  );  animation: progressAnimation 2.5s ease infinite;}@keyframes progressAnimation {  to {    --progress: 100%;  }}

Ergebnisse

Spezifikationen

Browser-Kompatibilität

Siehe auch

• var()
• Benutzerdefinierte Eigenschaften (--*)
• Registrierung von benutzerdefinierten CSS-Eigenschaften
• CSS Properties and Values API Modul
• CSS-Eigenschaften und -Werte API-Dokumentation
• Verwendung von benutzerdefinierten CSS-Eigenschaften (Variablen) Leitfaden
• CSS-Benutzerdefinierte Eigenschaften für kaskadierende Variablen Modul