@property

Syntax

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

Der Name der benutzerdefinierten Eigenschaft ist ein <dashed-ident>, der mit -- beginnt und einem gültigen, benutzerdefinierten Bezeichner folgt. Er ist groß- und kleinschreibungssensitiv.

Deskriptoren

syntax

Ein String, der die erlaubten Wertetypen für die registrierte benutzerdefinierte Eigenschaft beschreibt. Er kann ein Datentypname sein (wie <color>, <length> oder <number>, etc.), mit Multiplikatoren (+, #) und Kombinatoren (|), oder ein benutzerdefinierter Identifikator. Weitere Details finden Sie auf der Syntax-Deskriptorseite.

inherits

Ein boolescher Wert, der steuert, ob die durch @property angegebene Registrierung einer benutzerdefinierten Eigenschaft standardmäßig vererbt wird.

initial-value

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

Beschreibung

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

• Die @property-Regel muss sowohl die Deskriptoren syntax als auch inherits enthalten. Falls einer davon fehlt, ist die gesamte @property-Regel ungültig und wird ignoriert.
• Der Deskriptor initial-value ist optional, wenn der Wert des syntax-Deskriptors die universelle Syntaxdefinition ist (d.h. syntax: "*"). Wenn der initial-value-Deskriptor erforderlich ist, 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 Deskriptor initial-value einen computationally independent Wert haben. Dies bedeutet, dass der Wert konvertiert werden kann, um einen berechneten Wert zu erhalten, ohne von anderen Werten abhängig zu sein, außer "globalen" Definitionen, die unabhängig von CSS sind. Zum Beispiel ist 10px rechnerisch unabhängig — es ändert sich nicht, wenn es in einen berechneten Wert umgewandelt wird. 2in ist ebenfalls gültig, da 1in immer gleich 96px ist. Jedoch ist 3em nicht gültig, da der Wert eines em von der Elterneigenschaft font-size abhängt.
• Unbekannte Deskriptoren sind ungültig und werden ignoriert, machen jedoch die @property-Regel nicht ungültig.

Formale Syntax

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

Beispiele

Verwenden von @property zur Registrierung und Verwendung einer benutzerdefinierten Eigenschaft

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

<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 at-Regel, um eine benutzerdefinierte Eigenschaft namens --item-size zu definieren. Die Eigenschaft legt den Anfangswert auf 40% fest und beschränkt die gültigen Werte ausschließlich auf <percentage>-Werte. Dies bedeutet, dass bei Verwendung als Wert für die Größe eines Elements die Größe immer relativ zur Größe des Elternelements sein wird. Die Eigenschaft ist vererbbar.

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

Wir definieren eine zweite benutzerdefinierte Eigenschaft, --item-color, unter Verwendung von JavaScript anstelle von CSS. Die JavaScript-Methode registerProperty() entspricht der @property-at-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 stylen:

.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 container-Elternelement gesetzt und überschreiben die Standardwerte 40% und aqua, die festgelegt wurden, als diese benutzerdefinierten Eigenschaften definiert wurden. Die Größe ist vererbbar festgelegt; die Farbe nicht.

Für Element eins wurde keine dieser benutzerdefinierten Eigenschaften festgelegt. Da --item-size vererbbar ist, wird der auf seinem übergeordneten container festgelegte Wert 20% verwendet. Andererseits ist die Eigenschaft --item-color nicht vererbbar, daher wird der auf dem Elternteil festgelegte Wert orange nicht berücksichtigt. Stattdessen wird der anfängliche Standardwert aqua verwendet.

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

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

Animieren eines benutzerdefinierten Eigenschaftswerts

In diesem Beispiel definieren wir eine benutzerdefinierte Eigenschaft namens --progress mithilfe von @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, wobei spezifiziert wird, wo eine grüne Farbe endet und schwarz beginnt. Wir animieren dann den Wert von --progress über 2,5 Sekunden auf 100%, was den Effekt einer animierten Fortschrittsanzeige ergibt.

<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-Mal-API
• CSS Typisiertes Objektmodell
• Houdini-APIs
• Verwendung von CSS-Benutzerdefinierten Eigenschaften (Variablen) Leitfaden
• CSS-Benutzerdefinierte Eigenschaften für Kaskadierende Variablen Modul