`@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-Benutzerdefinierte Eigenschaften explizit zu definieren, was eine Überprüfung und Einschränkung des Eigenschaftentyps, das Festlegen von Standardwerten und die Definition ermöglicht, ob eine benutzerdefinierte Eigenschaft Werte erben kann oder nicht.

Hinweis: Die JavaScript-Methode registerProperty() entspricht der @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 benutzerdefinierten Eigenschaft ist ein <dashed-ident>, der mit -- beginnt und mit einem gültigen, benutzerdefinierten Bezeichner fortgesetzt wird. Er ist case-sensitiv.

Deskriptoren

syntax: Ein String, der die erlaubten Wertetypen für die registrierte benutzerdefinierte Eigenschaft beschreibt.
inherits: Ein boolescher Wert, der steuert, ob die durch @property spezifizierte Registrierung der benutzerdefinierten Eigenschaft standardmäßig erbt.
initial-value: Ein Wert, der den Startwert für die Eigenschaft festlegt.

Beschreibung

Die @property-At-Regel ist Teil der CSS Houdini API-Sammlung. Sie ermöglicht es Entwicklern, CSS-Benutzerdefinierte Eigenschaften explizit zu definieren, was eine Überprüfung und Einschränkung des Eigenschaftentyps, das Festlegen von Standardwerten und die Definition ermöglicht, ob eine benutzerdefinierte Eigenschaft Werte erben kann oder nicht.

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

Folgende 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. Ist einer von beiden fehlend, ist die gesamte @property-Regel ungültig und wird ignoriert.
Die syntax kann ein Datentypname sein (wie <color>, <length>, oder <number>, etc.), mit Multiplikatoren (+, #) und Kombinatoren (|), einem benutzerdefinierten Identifikator oder der universelle Syntax-Definition (*), was bedeutet, dass die Syntax jeder gültige Tokenstrom sein 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 Syntax-Definition (syntax: "*") ist. Wenn der initial-value-Deskriptor erforderlich, aber weggelassen wird, ist die gesamte @property-Regel ungültig und wird ignoriert.
Wenn der Wert des syntax-Deskriptors nicht die universelle Syntax-Definition ist, muss der initial-value-Deskriptor einen computationally 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 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 96px entspricht. 3em ist jedoch nicht gültig, da der Wert eines em von der font-size des übergeordneten Elements 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 und 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 benutzerdefinierte Eigenschaften zu deklarieren und diese dann 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 purpurnen Hintergrund und weißem Text.

Animieren eines Wertes einer benutzerdefinierten Eigenschaft

In diesem Beispiel definieren wir eine benutzerdefinierte Eigenschaft namens --progress mit @property: Diese akzeptiert <percentage>-Werte und hat einen Anfangswert von 25%. Wir verwenden --progress, um den Wert der Farbstopps in einem linear-gradient() zu definieren, der angibt, wo ein grüner Farbton endet und ein schwarzer beginnt. Wir animieren dann den Wert von --progress auf 100% über 2,5 Sekunden, was den Effekt eines animierten Fortschrittsbalkens 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%;
  }
}