@property構文

【CSS】@property構文を使ってカスタムプロパティ（CSS変数）にルールを定義する
...
yuito-blog.com

ルールを設定してカスタムプロパティを登録できる構文である。
設定できるルールは以下の通り。

  • syntax（値のデータ型）
  • inherits（プロパティ継承の有無）
  • initial-value（初期値）
@property --main-color {
  syntax: "<color>";
  inherits: true;
  initial-value: #fafafa;
}

body {
 background-color: var(--main-color);
}

@propertyのブラウザ対応状況

syntax（値のデータ型）

syntaxルールでは、カスタムプロパティに値として指定できるデータ型を引用符で囲って定義する。
このルールは必須で、省略すると無効となる。
以下2種類のルール指定方法が存在する。

  • 定義済みの型を使って指定
  • 記号を使って指定

定義済みの型を使って指定

定義で使用されている型を使うことができる。
以下のようなデータ型が指定できる。

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プロパティで指定可能な値。

記号を使って指定

以下4種類の記号を使って定義する。

  • プラス記号（＋）
  • ハッシュ記号（＃）
  • パイプ記号（｜）
  • アスタリスク記号（＊）

プラス記号（＋）

定義済みの型の直後にプラス記号を記述する。これはスペース区切りの値を受け入れる。

@property --set-position {
  syntax: "<length>+"; // スペース区切りのlength型の値を受け入れる
  inherits: false;
  initial-value: 50px 50px;
}

.hoge {
  translate: var(--set-position); // xに50px、yに50px移動
}

ハッシュ記号（＃）

カンマ区切りの値を受け入れる。

@property --main-color {
  syntax: "<number>#"; // カンマ区切りのnumber型の値を受け入れる
  inherits: false;
  initial-value: 50,255,30;
}

body {
  background-color: rgb(var(--main-color)); // rgb(50,255,30)
}

パイプ記号（｜）

パイプ記号で決められたルールを繋いだり、任意の値を繋いで定義できる。

// 複数の決められたルールを繋ぐ
@property --property-name {
 syntax:"<length> | <percentage>"; // 長さまたはパーセント値を受け入れるが、両者を組み合わせた calc式は受け入れない（calc(50px * 10%)はだめ）
 // 省略 
}

// 任意の値を繋ぐ
@property --property-name {
 syntax:"small | medium | large"; //「small、medium、large」のいずれかを受け入れる
 // 省略 
}

// 任意の値と決められたルールとカスタムルールを繋ぐ
@property --property-name {
 syntax:"small | <integer> | <color>#"; //「small、単一の整数、カンマ区切りの色リスト」のいずれかを受け入れる
 // 省略 
}

アスタリスク記号（＊）

全ての値を受け入れる。これが指定された場合のみ、initial-valueは省略可能でる。

@property --custom-property {
  syntax: "*"; // 全ての値を受け入れる
  inherits: false;
  initial-value: 省略可能;
}

inherits（プロパティ継承の有無）

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

親要素がカスタムプロパティの初期値を上書きした場合かつ、子要素がカスタムプロパティを指定しなかった場合、trueとfalseでは以下の値になる。

  • true：子要素のカスタムプロパティの値は親要素が上書きした値になる
  • false：子要素のカスタムプロパティの値は初期値になる

initial-value（初期値）

これはカスタムプロパティの初期値を指定する。
指定するときは、syntaxルールで指定した型に従う必要がある。
このルールは、syntaxルールにアスタリスク記号が指定されている場合を除き、必須である。
誤った型を書いたり、syntaxルールにアスタリスク記号以外が指定されている場合に省略すると無効となる。
無効な値を指定して、var関数を使ってプロパティにセットした場合、そのプロパティには初期値が設定される。

@property --main-color {
  syntax: "<color>";
  inherits: false;
  initial-value: 10; // color型ではない無効な値
}

// background-colorの初期値である、transparent（rgba(0,0,0,0)）が設定される
body {
  background-color: var(--main-color);
}

無効な書き方をした場合

@property構文でルールを指定してカスタムプロパティを登録したにもかかわらず、そのルールに違反した書き方をした場合、プロパティの値は登録された初期値を設定する。

@property --main-color {
  syntax: "<color>";
  inherits: false;
  initial-value: #000;
}

body {
  --main-color:10; // ルール違反
  background-color: var(--main-color); // 10は無視されて#000が入る
}

JavaScriptから登録

CSS.registerProperty()メソッドを使用してJavaScriptから登録することもできる。
https://developer.mozilla.org/ja/docs/Web/API/CSS/registerProperty_static

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