@property

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>, das mit -- beginnt und von einem gültigen, benutzerdefinierten Bezeichner gefolgt wird. Es ist case-sensitiv.

Deskriptoren

syntax

Ein String, der die erlaubten Werttypen 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 Anfangswert für die Eigenschaft festlegt.

Beschreibung

Die @property At-Regel ist Teil der CSS Houdini API-Set. Sie ermöglicht es Entwicklern, CSS-Custom Properties explizit zu definieren, was die Überprüfung und Einschränkung von Eigenschaftstypen ermöglicht, Standardwerte festlegt und definiert, ob eine benutzerdefinierte Eigenschaft vererbbar ist oder nicht.

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

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

• Die @property Regel muss sowohl den syntax- als auch den inherits-Deskriptor enthalten. Wenn einer von beiden fehlt, ist die gesamte @property Regel ungültig und wird ignoriert.
• Die syntax kann ein Datentypname sein (wie <color>, <length> oder <number> usw.), mit Multiplikatoren (+, #) und Kombinatoren (|), ein benutzerdefiniertes Ident oder die universelle Syntaxdefinition (*), was bedeutet, dass die Syntax jeder gültigen Token-Sequenz entsprechen kann. Der Wert ist ein <string>. Daher muss er 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 weggelassen wird, 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, dass der Wert in einen berechneten Wert umgewandelt werden kann, ohne von anderen Werten abhängig zu sein, außer für "globale" Definitionen, die unabhängig von CSS sind. Beispielsweise ist 10px rechnerisch unabhängig - es ändert sich nicht, wenn es in einen berechneten Wert umgewandelt wird. 2in ist auch gültig, da 1in immer 96px entspricht. 3em ist jedoch nicht gültig, da der Wert von em von der font-size des übergeordneten Elements abhängt.
• Unbekannte Deskriptoren sind ungültig und werden ignoriert, machen jedoch 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 sowohl mit @property in CSS als auch mit CSS.registerProperty() in JavaScript registriert werden, hat die JavaScript-Registrierung Vorrang.

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 verwenden dann diese Eigenschaften in unseren Style-Deklarationen.

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

Animation eines benutzerdefinierten Eigenschaftswerts

In diesem Beispiel definieren wir eine benutzerdefinierte Eigenschaft namens --progress mit @property: dies akzeptiert <percentage>-Werte und hat einen Anfangswert von 25%. Wir verwenden --progress, um den Positionswert der Farbstopps in einem linear-gradient() zu definieren, wobei angegeben wird, wo eine grüne Farbe stoppt und Schwarz beginnt. Dann animieren wir den Wert von --progress zu 100% über 2,5 Sekunden, was den Effekt einer animierten Fortschrittsleiste ergibt.

HTML

<div class="bar"></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 CSS-Custom Properties
• CSS Properties and Values API Modul
• CSS Properties and Values API-Dokumentation
• Verwendung von CSS-Custom Properties (Variablen) Leitfaden
• CSS-Custom Properties für kaskadierende Variablen Modul