CSSFunctionDeclarations

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used browsers.

Experimental: これは実験的な機能です。
本番で使用する前にブラウザー互換性一覧表をチェックしてください。

CSSFunctionDeclarations は CSS オブジェクトモデルのインターフェイスで、@function 本体に含む CSS 宣言の連続したものを表します。

この中には CSS カスタムプロパティや、@function 本体内の results 記述子の値を含めることができますが、@media などのブロックや、入れることができるアットルールは含みません。宣言のセットの途中に含まれるこのようなブロックは、複数の CSSFunctionDeclarations のデモにあるように、本体コンテンツが別個の CSSFunctionDeclarations オブジェクトになります。

CSSRule CSSFunctionDeclarations

インスタンスプロパティ

このインターフェイスには CSSRule から継承したプロパティがあります。

CSSFunctionDeclarations.style 読取専用

@function の本体で有効な記述子を表す CSSFunctionDescriptors オブジェクトを返します。

例

基本的な CSSFunctionDeclarations の使い方

この例では、CSS カスタム関数を定義し、CSSOM を使用してその宣言にアクセスします。

CSS

この CSS では、@function アットルールを用いてカスタム関数を定義しています。この関数は --lighter() と呼ばれ、入力された色の明るさを増したバージョンを出力します。--lighter() は 2 つの引数として <color> と <number> を取ります。相対色構文を用いて生成された oklch() 色を返します。入力された色を oklch() 色に変換し、その明度チャンネルを入力された数値分だけ増加させます。

css
@function --lighter(--color <color>, --lightness-adjust <number>: 0.2) returns
  <color> {
  --someVar: 100;
  result: oklch(from var(--color) calc(l + var(--lightness-adjust)) c h);
}

関数内でローカルカスタムプロパティ --someVar も設定しています。これは使用されませんが、@function 本体内で複数の宣言が連続して利用できる場合に何が起こるかを示しています。

JavaScript

スクリプトはまず、HTMLStyleElement.sheet を使用してこの文書に添付されたスタイルシートへの参照を取得します。次に、CSSStylesheet.cssRules を通じて、スタイルシート内の唯一のルールである CSSFunctionRule への参照を取得します。

次に、関数内で唯一の連続した宣言群を表す CSSFunctionDeclarations オブジェクトを cssRules[0] で参照し、その記述子の情報を CSSFunctionDeclarations.style で取得した後、記述子の長さおよびスタイル情報を参照します。この情報はすべてコンソールにログ出力されます。

js
// CSSFunctionRule を取得
const cssFunc = document.getElementById("css-output").sheet.cssRules[0];

// CSSFunctionDeclarations と CSSFunctionDescriptors へのアクセス
console.log(cssFunc.cssRules[0]); // CSSFunctionDeclarations
console.log(cssFunc.cssRules[0].style); // CSSFunctionDescriptors
console.log(cssFunc.cssRules[0].style.length);
console.log(cssFunc.cssRules[0].style.result);

もっとも注目すべきことは次の通りです。

length プロパティは 2 となります。これは記述子のテキストが 2 つの部分（--someVar: 100; と result: oklch(from var(--color) calc(l + var(--lightness-adjust)) c h);）から構成されているためです。
result プロパティは、@function 本体の result 記述子と等しく、これは oklch(from var(--color) calc(l + var(--lightness-adjust)) c h) です。

複数の CSSFunctionDeclarations

この例では、一連の宣言の途中に挿入された @media アットルールが、2 つの CSSFunctionDeclarations オブジェクトを生成する様子を示します。

CSS

この CSS では仕様書から引用した @function の例 --bar() を示しています。これは特に機能はしませんが、@media ブロックで別個の宣言を特徴としています。

css
@function --bar() {
  --x: 42;
  result: var(--y);
  @media (width > 1000px) {
    /* ... */
  }
  --y: var(--x);
}

JavaScript

スクリプトはまず、HTMLStyleElement.sheet を通じて文書に添付されたスタイルシートへの参照を取得し、次に CSSStylesheet.cssRules を通じてスタイルシート内の唯一のルールである CSSFunctionRule への参照を取得します。

次に、CSSGroupingRule.cssRules にアクセスし、その値をコンソールにログ出力します。これにより、3 つのオブジェクトを含む CSSRuleList オブジェクトが返されます。

CSSFunctionDeclarations オブジェクトで --x: 42;result: var(--y); の部分を表すもの。
CSSMediaRule オブジェクトで @media アットルールを表すもの。
2 番目の CSSFunctionDeclarations オブジェクトで --y: var(--x); の部分を表すもの。

js
// CSSFunctionRule を取得
const cssFunc = document.getElementById("css-output").sheet.cssRules[0];

// 両方の CSSFunctionDeclarations にアクセス
console.log(cssFunc.cssRules);

次に、それぞれの CSSFunctionDeclarations オブジェクトに関するいくつかの詳細をコンソールにログ出力します。具体的には、オブジェクト自体、その style プロパティに含まれる CSSFunctionDescriptors オブジェクト、および CSSFunctionDescriptors.result プロパティです。

js
console.log(cssFunc.cssRules[0]); // 1 つ目の CSSFunctionDeclarations
console.log(cssFunc.cssRules[0].style); // CSSFunctionDescriptors
console.log(cssFunc.cssRules[0].style.result);

console.log(cssFunc.cssRules[2]); // 2 つ目の CSSFunctionDeclarations
console.log(cssFunc.cssRules[2].style); // CSSFunctionDescriptors
console.log(cssFunc.cssRules[2].style.result);

2 つ目の場合では、result は空文字列を返します。これは、2 つ目の宣言部分に result 記述子が含まれていないためです。