@property

Baseline 2024

Newly available

Since ⁨July 2024⁩, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

@property はCSS のアットルールで、 API のCSS Houdini の傘下にあるものです。開発者が明示的にCSS カスタムプロパティを定義し、プロパティ型のチェック、既定値の設定、プロパティが値を継承するかどうかの定義ができるようになっています。

@property ルールは、 JS を実行することなく、スタイルシートの中で直接カスタムプロパティの登録を表します。有効な@property ルールは、あたかもregisterProperty() が同等の引数で呼び出されたかのように、登録されたカスタムプロパティを生成します。

プロパティに許容される構文を記述します。<length>,<number>,<percentage>,<length-percentage>,<color>,<image>,<url>,<integer>,<angle>,<time>,<resolution>,<transform-function>,<custom-ident> のいずれか、またはデータ型とキーワード値のリストです。

+ （スペース区切り）と# （カンマ区切り）の量化子は、値のリストが期待されることを示します。例えば、<color># は<color> 値のカンマ区切りのリストが期待される構文であることを意味しています。

垂直線 (|) は期待された条件の「論理和」を表します。例えば<length> | auto は<length> またはauto を受け入れ、<color># | <integer># はカンマで区切られた<color> 値のリスト、またはカンマで区切られた<integer> 値のリストを受け入れます。

inherits

@property で指定されたカスタムプロパティの登録を既定で継承するかどうかを制御します。

initial-value

プロパティの初期値を設定します。

@property ルールにはsyntax およびinherits 記述子を含める必要があります。どちらかがない場合は、@property ルール全体が無効となり、無視されます。initial-value 記述子は構文が* 全称構文定義（例えばsyntax: "*"）である場合のみ省略可能で、それ以外の場合は必須です。initial-value 記述子が必須である場合にこれが省略されると、ルール全体が無効となって無視されます。

未知の記述子は無効で無視されますが、@property ルールは無効になりません。

形式文法

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

例

この例では、--item-size と--item-color という 2 つのカスタムプロパティを定義し、以下の 3 つのアイテムのサイズ（幅と高さ）と背景色を定義します。

html

<div>  <div>Item one</div>  <div>Item two</div>  <div>Item three</div></div>

以下のコードは CSS の@property アットルールを使用して、--item-size という名前のカスタムプロパティを定義します。このプロパティは初期値を40% に設定し、有効な値をパーセント値 (<percentage>) のみに制限します。つまり、アイテムのサイズの値として使用する場合、そのサイズは常に親のサイズからの相対値となります。このプロパティは継承可能です。

css

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

第 2 のカスタムプロパティである--item-color は、 CSS の代わりにJavaScript を使用して定義します。 JavaScript のregisterProperty() メソッドは、@property アットルールと同等です。このプロパティは初期値がaqua で、<color> の値のみを受け入れるように定義されており、継承されません。

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

アイテムのスタイル設定には、 2 つのカスタムプロパティを使用します。

css

.container {  display: flex;  height: 200px;  border: 1px dashed black;  /* 親にカスタムプロパティの値を設定 */  --item-size: 20%;  --item-color: orange;}/* カスタムプロパティを使用して、アイテムのサイズと背景色を設定 */.item {  width: var(--item-size);  height: var(--item-size);  background-color: var(--item-color);}/* 要素自体にカスタムプロパティ値を設定 */.two {  --item-size: initial;  --item-color: inherit;}.three {  /* 無効な値 */  --item-size: 1000px;  --item-color: xyz;}

2 つのカスタムプロパティ--item-size: 20% と--item-color: orange; がcontainer の親に設定され、これがカスタムプロパティを定義したときに設定された40% とaqua の既定値を上書きします。サイズは継承できるように設定されていますが、色は継承できません。

アイテム one では、これらのカスタムプロパティはいずれも設定されていません。--item-size は継承可能なので、親プロパティcontainer に設定されている値20% が使用されます。他にも、--item-color プロパティは継承できないので、親に設定されている値orange は考慮されません。代わりに既定値の初期値aqua が使用されます。

アイテム two については、両方のカスタムプロパティに CSS のグローバルキーワードが設定されています。これは、すべての値タイプで有効な値であるため、syntax 記述子の値に関係なく有効です。item-size はinitial に設定し、initial-value： 40%; は@property 宣言で設定します。initial 値はプロパティのinitialValue 値が使用されることを意味しています。item-color はinherit に設定されており、たとえカスタムプロパティが継承されないように設定されていても、明示的に親からorange 値を継承します。これがアイテム two がオレンジ色である理由です。

アイテム three では、--item-size の値は1000px に設定されます。1000px は<length> の値ですが、@property 宣言では<percentage> であることが要求されているため、この宣言は無効であり無視され、すなわち親に設定されている継承可能な20% が使用されます。xyz の値も不正な値です。registerProperty() は--item-color を継承しないように設定したので、親のorange 値ではなく、既定値のaqua が使用されます。