💡

【CSS】カスタムプロパティ(変数)に型定義をする

2023/03/08に公開

Safari 16.4 betaでCSS変数に型定義やデフォルト値を設定できる@propertyのサポートが追加されました。

Added support for CSS Properties and Values API with support for @property.

Safari16.4が正式リリースされたらFirefox以外で利用できるようになります。

`@property`とは

@propertyはCSSのカスタムプロパティ(変数)にデフォルト値やプロパティの型チェックができるようになるアットルールです。

基本構文は以下の通りです。

基本構文

@property カスタムプロパティ名 {
  syntax: 値として許容するルール;
  inherits: ルールを継承するか;
  initial-value: デフォルト値;
}

具体的な値を指定すると次のようになります。

sample.css

@property --property-name {
  syntax: '<color>'; /* CSSのcolorに指定可能な値のみ受け入れる */
  inherits: false; /* ルールを継承しない */
  initial-value: #c0ffee; /* デフォルト値 */
}

@propertyで指定可能なそれぞれのプロパティについて、もう少し具体的に解説します。

syntax

syntaxプロパティは以下3種類のルールを指定できます。

決められたルール
カスタムルール
全て

決められたルール

以下のいずれかを指定できます。

rule	説明
`<length>`	`px`や`em`、`vw`等、長さ指定で利用可能な値。詳しくはこちら
`<number>`	`12`や`-456.8`、`10e3`等、数、値指定で利用可能な値。詳しくはこちら
`<percentage>`	`12%`や`-456.8%`、`10e3%`等、`<number>`+`%`形式が利用可能。詳しくはこちら
`<length-percentage>`	`<length>`または`<percentage>`で利用可能な値
`<color>`	`red`や`#fff`、`rgb(255,0,20)`等、`color`プロパティで利用可能な値。詳しくはこちら
`<image>`	`url()`や`image()`等、`background-image`プロパティで利用可能な値。詳しくはこちら
`<url>`	`url()`で指定可能な値。詳しくはこちら
`<integer>`	`10`や`-12`等、整数が利用可能。詳しくはこちら
`<angle>`	`45deg`や`1.75turn`等、`rotate()`に指定可能な値。詳しくはこちら
`<time>`	`10s`や`5ms`等、`transition`プロパティに指定可能な値。詳しくはこちら
`<resolution>`	`10dpcm`や`96dpi`等、メディアクエリの`resolution`に指定可能な値。詳しくはこちら
`<transform-function>`	`rotate()`や`scale()`等、`transform`プロパティで指定可能な値。詳しくはこちら
`<custom-ident>`	`test10`や`-test`等、識別子として利用可能な値が指定可能。詳しくはこちら
`<transform-list>`	`skew()`や`translate()`等、`transform`プロパティで指定可能な値。詳しくはこちら

カスタムルール

任意の値をパイプ|でつないで定義できます。

@property --property-name {
  syntax: 'small | medium | large'; /* small or medium or large */
  inherits: false;
  initialValue: 'medium',
}

もともと定義されているルールもパイプ|でつなげます。

@property --property-name {
  syntax: '<length> | <percentage>';
  inherits: false;
  initialValue: '100px',
}

全て

*で何でも受け入れます。

@property --property-name {
  syntax: '*';
  inherits: false;
  initialValue: 'hogehoge',
}

inherits

inheritsプロパティはBoolean型 (true | false) の値を取ります。
これは必須プロパティで、値を継承したい場合はtrue、継承させたくない場合はfalseを指定します。

initial-value

initial-valueプロパティは該当するカスタムプロパティのデフォルト値を指定します。

おまけ

JavaScriptから登録することもできます。

window.CSS.registerProperty({
  name: '--my-color',
  syntax: '<color>',
  inherits: false,
  initialValue: '#c0ffee',
});