`@property` CSS at-rule

Baseline 2024

Neu verfügbar

Seit July 2024 funktioniert diese Funktion auf aktuellen Geräten und in aktuellen Browserversionen. Auf älteren Geräten oder in älteren Browsern funktioniert sie möglicherweise nicht.

Die @property CSS At-Regel wird verwendet, um CSS-Custom Properties explizit zu definieren. Dies ermöglicht das Überprüfen und Einschränken von Eigenschaftstypen, das Festlegen von Standardwerten und das Definieren, ob eine Custom Property Werte erben kann oder nicht.

Hinweis: Die JavaScript-Methode registerProperty() ist gleichwertig zur @property-At-Regel.

Syntax

css

@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 Custom Property ist ein <dashed-ident>, der mit -- beginnt und auf einen gültigen, benutzerdefinierten Identifier folgt. Er ist Groß- und Kleinschreibung empfindlich.

Deskriptoren

syntax: Ein String, der die erlaubten Wertetypen für die registrierte Custom Property beschreibt.
inherits: Ein boolescher Wert, der steuert, ob die von @property spezifizierte Custom Property standardmäßig erbt.
initial-value: Ein Wert, der den Anfangswert für die Eigenschaft festlegt.

Beschreibung

Die @property-At-Regel ist Teil des CSS Houdini-API-Sets. Sie ermöglicht es Entwicklern, CSS-Custom Properties explizit zu definieren. Dies ermöglicht das Überprüfen und Einschränken von Eigenschaftstypen, das Festlegen von Standardwerten und das Definieren, ob eine Custom Property Werte erben kann oder nicht.

Die @property-Regel ermöglicht die Registrierung von Custom Properties direkt innerhalb von Stylesheets, ohne dass JavaScript erforderlich ist. Gültige @property-Regeln erzeugen registrierte Custom Properties, die denselben Effekt haben wie ein Aufruf von registerProperty() mit gleichwertigen Parametern.

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

Die @property-Regel muss sowohl den syntax- als auch den inherits-Deskriptor enthalten. Wenn einer fehlt, ist die gesamte @property-Regel ungültig und wird ignoriert.
Der syntax-Deskriptor kann ein Datentypenname sein (wie <color>, <length> oder <number> usw.) mit Multiplikatoren (+, um eine durch Leerzeichen getrennte Liste zu akzeptieren, oder #, um eine durch Kommas getrennte Liste zu akzeptieren) und Kombinatoren (|, um einen von mehreren Datentypen zu akzeptieren), ein benutzerdefiniertes Ident oder die universelle Syntaxdefinition (*), was bedeutet, dass die Syntax jeder gültigen Tokenfolge entsprechen kann. Der Wert ist ein <string> und muss daher in Anführungszeichen stehen.
Der initial-value-Deskriptor ist optional, wenn der Wert des syntax-Deskriptors die universelle Syntaxdefinition ist (syntax: "*"). Wenn der initial-value-Deskriptor erforderlich, aber nicht angegeben ist, ist die gesamte @property-Regel ungültig und wird ignoriert.
Wenn der Wert des syntax-Deskriptors nicht die universelle Syntaxdefinition ist, muss der initial-value-Deskriptor einen rechnerisch unabhängigen Wert haben. Das bedeutet, der Wert kann in einen berechneten Wert umgewandelt werden, ohne von anderen Werten abhängig zu sein, mit Ausnahme von nicht von CSS abhängigen "globalen" Definitionen. Zum Beispiel ist 10px rechnerisch unabhängig, da es sich nicht ändert, wenn es in einen berechneten Wert umgewandelt wird. 2in ist ebenfalls gültig, da 1in immer gleich 96px ist. Allerdings ist 3em nicht valide, denn der Wert eines em hängt von der font-size des übergeordneten Elements ab.
Unbekannte Deskriptoren sind ungültig und werden ignoriert, machen jedoch die @property-Regel nicht ungültig.

Falls mehrere gültige @property-Regeln mit demselben Namen definiert sind, "gewinnt" die zuletzt im Stylesheet definierte. Wenn Custom Properties mit demselben Namen sowohl mit @property in CSS als auch mit CSS.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 Custom Properties zu deklarieren und dann diese Properties in unseren Stil-Deklarationen zu verwenden.

HTML

html

<p>Hello world!</p>

CSS

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 sollte 200px breit sein, mit einem lila Hintergrund und weißem Text.

Animieren eines Custom Property-Werts

In diesem Beispiel definieren wir eine Custom Property namens --progress mit @property: diese akzeptiert <percentage>-Werte und hat einen Anfangswert von 25%. Wir verwenden --progress, um den Positionswert der Farbstopps in einem linear-gradient() zu definieren, und legen fest, wo eine grüne Farbe aufhört und schwarz beginnt. Wir animieren dann den Wert von --progress auf 100% über 2,5 Sekunden, was den Effekt eines animierten Fortschrittbalkens ergibt.

HTML

html

<div class="bar"></div>

CSS

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%;
  }
}