@property

Syntax

@property --rotation {
  syntax: "<angle>";
  inherits: false;
  initial-value: 45deg;
}

Der Name der benutzerdefinierten Eigenschaft ist ein <dashed-ident>, der mit -- beginnt, gefolgt von einem gültigen, benutzerdefinierten Bezeichner. Er ist groß-/klein-schreibungssensitiv.

Deskriptoren

syntax

Ein String, der die erlaubten Wertetypen für die registrierte benutzerdefinierte Eigenschaft beschreibt. Es kann ein Datentypname (wie <color>, <length> oder <number> usw.) sein, mit Multiplikatoren (+, #) und Kombinatoren (|), oder ein benutzerdefiniertes ident sein. Siehe die syntax Deskriptorseite für mehr Details.

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 setzt.

Beschreibung

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. Fehlt einer von beiden, ist die gesamte @property-Regel ungültig und wird ignoriert.
• Der initial-value Deskriptor ist optional, wenn der Wert des syntax Deskriptors die universelle Syntaxdefinition ist (also 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 ein computationally independent Wert sein. Das bedeutet, der Wert kann in einen berechneten Wert umgewandelt werden, ohne dass er von anderen Werten abhängt, außer von "globalen" Definitionen, die unabhängig von CSS sind. Zum Beispiel ist 10px rechnerisch unabhängig—es ändert sich nicht bei der Umwandlung in einen berechneten Wert. 2in ist auch gültig, da 1in immer gleich 96px ist. 3em ist jedoch nicht gültig, da der Wert von em von der übergeordneten font-size abhängt.
• Unbekannte Deskriptoren sind ungültig und werden ignoriert, aber sie machen die @property-Regel nicht ungültig.

Formale Syntax

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

Beispiele

Verwenden von @property, um eine benutzerdefinierte Eigenschaft zu registrieren und zu verwenden

In diesem Beispiel definieren wir zwei benutzerdefinierte Eigenschaften: --item-size und --item-color, die wir verwenden, um die Größe (Breite und Höhe) und die Hintergrundfarbe der drei folgenden Elemente zu definieren.

<div class="container">
  <div class="item one">Item one</div>
  <div class="item two">Item two</div>
  <div class="item three">Item three</div>
</div>

Der folgende Code verwendet die CSS @property-Regel, um eine benutzerdefinierte Eigenschaft namens --item-size zu definieren. Die Eigenschaft setzt den Anfangswert auf 40%, wobei gültige Werte auf <percentage>-Werte beschränkt werden. Das bedeutet, dass die Größe eines Elements immer relativ zur Größe seines Elternteils ist. Die Eigenschaft ist vererbbar.

@property --item-size {
  syntax: "<percentage>";
  inherits: true;
  initial-value: 40%;
}

Wir definieren eine zweite benutzerdefinierte Eigenschaft, --item-color, mithilfe von JavaScript anstelle von CSS. Die JavaScript-Methode registerProperty() entspricht der @property-Regel. Die Eigenschaft wird so definiert, dass sie einen Anfangswert von aqua hat, nur <color>-Werte akzeptiert und nicht vererbt wird.

window.CSS.registerProperty({
  name: "--item-color",
  syntax: "<color>",
  inherits: false,
  initialValue: "aqua",
});

Wir verwenden die beiden benutzerdefinierten Eigenschaften, um die Elemente zu gestalten:

.container {
  display: flex;
  height: 200px;
  border: 1px dashed black;

  /* set custom property values on parent */
  --item-size: 20%;
  --item-color: orange;
}

/* use custom properties to set item size and background color */
.item {
  width: var(--item-size);
  height: var(--item-size);
  background-color: var(--item-color);
}

/* set custom property values on element itself */
.two {
  --item-size: initial;
  --item-color: inherit;
}

.three {
  /* invalid values */
  --item-size: 1000px;
  --item-color: xyz;
}

Die beiden benutzerdefinierten Eigenschaften, --item-size: 20% und --item-color: orange; werden auf dem übergeordneten container-Element gesetzt und überschreiben die 40% und aqua-Standardwerte, die beim Definieren dieser benutzerdefinierten Eigenschaften festgelegt wurden. Die Größe ist vererbbar; die Farbe nicht.

Für Artikel eins wurde keine dieser benutzerdefinierten Eigenschaften gesetzt. Da --item-size vererbbar ist, wird der Wert 20%, der auf dem übergeordneten container gesetzt ist, verwendet. Andererseits ist die Eigenschaft --item-color nicht vererbbar, sodass der auf dem Elternteil gesetzte Wert orange nicht berücksichtigt wird. Stattdessen wird der Standardanfangswert aqua verwendet.

Für Artikel zwei werden CSS-Globale Schlüsselwörter für beide benutzerdefinierten Eigenschaften eingestellt, die gültige Werte für alle Wertetypen sind und daher unabhängig vom Wert des syntax Deskriptors gültig sind. --item-size wird auf initial gesetzt und verwendet den initial-value: 40%;, der in der @property-Deklaration gesetzt ist. Der initial Wert bedeutet, dass der initialValue Wert für die Eigenschaft verwendet wird. --item-color wird auf inherit gesetzt und erbt explizit den orange Wert von seinem Elternteil, obwohl die benutzerdefinierte Eigenschaft so eingestellt ist, dass sie sonst nicht vererbt wird. Deshalb ist Artikel zwei orange.

Für Artikel drei wird der --item-size Wert auf 1000px gesetzt. Während 1000px ein <length>-Wert ist, verlangt die @property-Deklaration, dass der Wert ein <percentage> ist. Daher ist die Deklaration nicht gültig und wird ignoriert, was bedeutet, dass die vererbbare 20%, die auf dem Elternteil gesetzt ist, verwendet wird. Der xyz Wert ist ebenfalls ungültig. Da registerProperty() --item-color so eingestellt hat, dass es nicht vererbt wird, wird der Standardanfangswert von aqua verwendet und nicht der orange Wert des Elternteils.

Animieren eines benutzerdefinierten Eigenschaftswerts

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 Positionswert der Farbverläufe in einem linear-gradient() zu definieren, der angibt, wo eine grüne Farbe stoppt und schwarz beginnt. Dann animieren wir den Wert von --progress auf 100% über 2,5 Sekunden, wodurch der Effekt einer animierten Fortschrittsanzeige entsteht.

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

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

Spezifikationen

Browser-Kompatibilität

Siehe auch

• var()
• CSS-Eigenschaften und Werte API
• CSS-Malerei-API
• CSS-typed Object Model
• Houdini APIs
• CSS Custom Properties (Variablen) verwenden Leitfaden
• CSS Custom Properties für kaskadierende Variablen Modul