Package Reference - @wordpress/style-engine - 《WordPress開発者リソース》日本語

注意してください
バックエンド API
インストール (JS のみ)
使用法
用語集

注意してください

このパッケージは WordPress 6.1 から新しく、まだ初期段階にあります。

今後のロードマップに含まれるタスクは以下の通りですが、これに限りません：

グローバルおよびブロックスタイルのレンダリングとエンキューの統合（進行中）
他の一般的および/または繰り返しのブロックスタイルを重複排除する意図で、プリレンダリング CSS ルール処理を探求する。（進行中）
セマンティッククラス名および/またはデザイントークン表現の範囲を拡張し、ルールを安定したユーティリティクラスにカプセル化する。
プリレンダリング CSS ルール処理を探求し、他の一般的および/または繰り返しのブロックスタイルを重複排除する意図で。
階層と特異性を制御する方法を提案し、スタイル階層のカスケードをアクセス可能で予測可能にする。これには、CSS カスケードレイヤーの準備が含まれる可能性があり、より広くサポートされるまで、theme.json を介して Gutenberg でのオプトインサポートを許可することが含まれます。
すべてのブロックをリファクタリングし、すべてのカスタマイズに「style」属性を一貫して使用し、attributes.fontSize のようなプリセット特有の属性を非推奨にします。

ロードマップに関する詳細情報は、ブロックエディタスタイル：イニシアチブと目標および GitHub プロジェクトボードを参照してください。

スタイルエンジンに変更や追加を行う場合は、貢献に関するノートを読む時間を取ってください。

バックエンド API

wp_style_engine_get_styles()

グローバルなパブリック関数で、単一のスタイルオブジェクトからスタイルを生成します。例えば、ブロックの attributes.style オブジェクトや theme.json のトップレベルスタイルなどです。

スタイルエンジンを使用してブロックサポートスタイルを生成するも参照してください。

パラメータ

$block_styles array ブロックの attributes.style オブジェクトまたは theme.json のトップレベルスタイル
$options array<string|boolean> 出力を決定するためのオプションの配列。
- context string スタイルオブジェクトの起源を説明する識別子、例：‘block-supports’ または ‘global-styles’。デフォルトは ‘block-supports’ です。context と selector の両方が設定されている場合、スタイルエンジンは context をキーとして CSS ルールを保存します。
- convert_vars_to_classnames boolean CSS var:? 値を var( –wp–preset–* ) 値に変換するかどうか。デフォルトは false です。
- selector string セレクタが渡されると、generate() は完全な CSS ルール $selector { ...rules } を返します。そうでない場合は、プロパティと値の連結された文字列を返します。

戻り値


``````bash
array(
   'css'           => (string) A CSS ruleset or declarations block formatted to be placed in an HTML `style` attribute or tag.
   'declarations'  => (array) An array of property/value pairs representing parsed CSS declarations.
   'classnames'    => (string) Classnames separated by a space.
);
`

インラインスタイルのためのコンパイルされた CSS 宣言を返します。また、セレクタが提供されている場合は、完全な CSS ルールを返します。

サイトのフロントエンドでレンダリングするためにスタイルをエンキューするには、$options 配列には以下が必要です：

1. selector (string) – これはブロックスタイル CSS 宣言のための CSS セレクタです。
2. context (string) – これはスタイルを保存する場所をスタイルエンジンに指示します。同じコンテキスト内のスタイルは一緒に保存されます。

wp_style_engine_get_styles はコンパイルされた CSS と CSS 宣言の配列を返します。

使用法

前述のように、wp_style_engine_get_styles() は ブロックのスタイルオブジェクト から CSS および/またはクラス名を生成したいときに便利です。良い例は、スタイルエンジンを使用してブロックサポートスタイルを生成するです。

以下のスニペットでは、ブロックの属性からスタイルオブジェクトを取得し、それをスタイルエンジンに渡してスタイルを取得しています。オプションに context を渡すことで、スタイルエンジンは後で取得できるようにスタイルを保存します。たとえば、一連の CSS ルールをバッチエンキューしたい場合などです。

$block_attributes =  array(
   'style' => array(
   'spacing' => array( 'padding' => '100px' ),
   ),
);
$styles = wp_style_engine_get_styles(
   $block_attributes['style'],
   array(
   'selector' => '.a-selector',
   'context'  => 'block-supports',
   )
);
print_r( $styles );
/*
array(
   'css'          => '.a-selector{padding:100px}'
   'declarations' => array( 'padding' => '100px' )
)
*/

wp_style_engine_get_stylesheet_from_css_rules()

この関数を使用して、任意の CSS ルールのスタイルシートをコンパイルして返します。スタイルエンジンは自動的に宣言をマージし、セレクタを結合します。

この関数は CSS コンパイラとして機能しますが、context 文字列がオプションに渡されると、スタイルをストアに登録します。

パラメータ

$css_rules array<array>
$options array<string|bool> 出力を決定するためのオプションの配列。
- context string スタイルオブジェクトの起源を説明する識別子、例：‘block-supports’ または ‘global-styles’。デフォルトは ‘block-supports’ です。設定されると、スタイルエンジンは CSS ルールを保存しようとします。
- prettify bool 出力に新しい行とインデントを追加するかどうか。デフォルトは、定義されている場合はグローバル定数 SCRIPT_DEBUG の値を継承します。
- optimize bool CSS 出力を最適化するかどうか、例：ルールを結合します。デフォルトは false です。

戻り値

string $css_rules に基づいてコンパイルされた CSS 文字列。

使用法

一連のセレクタ + 宣言アイテムからカスタムの CSS ルールセットをコンパイルしたいときに便利です。

スタイルエンジンはサニタイズされたスタイルシートを返します。オプションに context 識別子を渡すことで、スタイルエンジンは後で取得できるようにスタイルを保存します。たとえば、一連の CSS ルールをバッチエンキューしたい場合などです。

wp_style_engine_get_stylesheet_from_css_rules() を複数回呼び出すことができ、スタイルが同じ context 識別子を使用している限り、一緒に保存されます。

$styles = array(
   array(
   'selector'     => '.wp-pumpkin',
   'declarations' => array( 'color' => 'orange' )
   ),
   array(
   'selector'     => '.wp-tomato',
   'declarations' => array( 'color' => 'red' )
   ),
   array(
   'selector'     => '.wp-tomato',
   'declarations' => array( 'padding' => '100px' )
   ),
);
$stylesheet = wp_style_engine_get_stylesheet_from_css_rules(
   $styles,
   array(
   'context' => 'block-supports', // Indicates that these styles should be stored with block supports CSS.
   )
);
print_r( $stylesheet ); // .wp-pumpkin{color:orange}.wp-tomato{color:red;padding:100px}

rules_group キーを使用してシンプルなネストされた CSS ルールを構築することも可能です。

$styles = array(
   array(
   'rules_group'  => '@media (min-width: 80rem)',
   'selector'     => '.wp-carrot',
   'declarations' => array( 'color' => 'orange' )
   ),
   array(
   'rules_group'  => '@media (min-width: 80rem)',
   'selector'     => '.wp-tomato',
   'declarations' => array( 'color' => 'red' )
   ),
);
$stylesheet = wp_style_engine_get_stylesheet_from_css_rules(
   $styles,
   array(
   'context' => 'block-supports', // Indicates that these styles should be stored with block supports CSS.
   )
);
print_r( $stylesheet ); // @media (min-width: 80rem){.wp-carrot{color:orange}}@media (min-width: 80rem){.wp-tomato{color:red;}}

wp_style_engine_get_stylesheet_from_context()

保存されたコンテキストからコンパイルされた CSS を返します。見つかった場合。

パラメータ

$store_name string スタイルオブジェクトの起源を説明する識別子、例：‘block-supports’ または ‘global-styles’。デフォルトは ‘block-supports’ です。
$options array<bool> 出力を決定するためのオプションの配列。
- prettify bool 出力に新しい行とインデントを追加するかどうか。デフォルトは、定義されている場合はグローバル定数 SCRIPT_DEBUG の値を継承します。
- optimize bool CSS 出力を最適化するかどうか、例：ルールを結合します。デフォルトは false です。

戻り値

string 保存された CSS ルールからのコンパイルされた CSS 文字列。

使用法

この関数を使用して、特定のコンテキスト識別子の下に保存されたすべてのスタイルを使用してスタイルシートを生成します。

ユースケースは、フロントエンドにレンダリングするためにすべての保存されたスタイルをエンキューしたいときです。スタイルエンジンは取得時にスタイルをマージし、重複を排除します。

// First, let's gather and register our styles.
$styles = array(
   array(
   'selector'     => '.wp-apple',
   'declarations' => array( 'color' => 'green' )
   ),
);
wp_style_engine_get_stylesheet_from_css_rules(
   $styles,
   array(
   'context' => 'fruit-styles',
   )
);
// Later, we fetch compiled rules from context store.
$stylesheet = wp_style_engine_get_stylesheet_from_context( 'fruit-styles' );
print_r( $stylesheet ); // .wp-apple{color:green;}
if ( ! empty( $stylesheet ) ) {
   wp_register_style( 'my-stylesheet', false, array(), true, true );
   wp_add_inline_style( 'my-stylesheet', $stylesheet );
   wp_enqueue_style( 'my-stylesheet' );
}

インストール (JS のみ)

モジュールをインストールします。

npm install @wordpress/style-engine --save

このパッケージは、あなたのコードが ES2015+ 環境で実行されることを前提としています。もし、言語機能や API のサポートが限られているか、全くない環境を使用している場合は、コードに @wordpress/babel-preset-default に同梱されているポリフィルを含めるべきです。

使用法

compileCSS

指定されたスタイルオブジェクトとセレクタのためのスタイルシートを生成します。

パラメータ

style Style: スタイルオブジェクト、例えば、ブロックの attributes.style オブジェクトの値や theme.json のトップレベルスタイル
options StyleOptions: スタイルが生成される方法を調整するための設定を持つオプションオブジェクト。

戻り値

string: 生成されたスタイルシートまたはインラインスタイル宣言。

変更履歴

6.1.0 WordPress コアに導入されました。

getCSSRules

生成された CSS ルールの JSON 表現を返します。

パラメータ

style Style: スタイルオブジェクト、例えば、ブロックの attributes.style オブジェクトの値や theme.json のトップレベルスタイル
options StyleOptions: スタイルが生成される方法を調整するための設定を持つオプションオブジェクト。

戻り値

GeneratedCSSRule[]: セレクタ（あれば）、CSS プロパティキー（キャメルケース）および解析された CSS 値を含むオブジェクトのコレクション。

変更履歴

6.1.0 WordPress コアに導入されました。

getCSSValueFromRawStyle

受信したスタイルプリセット値から WordPress CSS カスタム変数値を返します。検出された場合。

プリセット値は文字列で、パターン var:description|context|slug に従います。

例：

getCSSValueFromRawStyle( 'var:preset|color|heavenlyBlue' ) // ‘var(–wp–preset–color–heavenly-blue)’ を返します。

パラメータ

styleValue StyleValue: 生の CSS 値を表す文字列。非文字列は処理されません。

戻り値

StyleValue: 受信したスタイル値がプリセット値である場合の CSS カスタム変数値。

用語集

スタイルエンジンパッケージで参照される用語と変数名のガイド。

ブロックスタイル（Gutenberg 内部）
ブロックのスタイル属性を構成するオブジェクトで、ブロックのスタイル値を含みます。例：{ spacing: { margin: '10px' }, color: { ... }, ... }
コンテキスト
共通の起源または目的を持つスタイルのグループの識別子、例：‘block-supports’ または ‘global-styles’。コンテキストは、ストアから CSS ルールを取得するためのキーとしても使用されます。
CSS 宣言または（CSS プロパティ宣言）
CSS プロパティと CSS 値のペア。例：color: pink
CSS 宣言ブロック
通常、CSS セレクタとペアになって CSS ルールを作成する CSS 宣言のセット。
CSS プロパティ
HTML 要素のスタイル的、修正可能な特徴を説明する識別子。例：border、font-size、width…
CSS ルール
CSS セレクタの後に、波括弧内に CSS 宣言ブロックが続く。通常、CSS スタイルシートに見られます。
CSS セレクタ（または CSS クラスセレクタ）
CSS ルールの最初のコンポーネントで、CSS セレクタは、ルールの CSS 定義が適用される要素を定義する要素、クラス名、または他の用語のパターンです。例：p.my-cool-classname > span。CSS セレクタは、「class」属性の内容に基づいて HTML 要素と一致します。MDN CSS セレクタの記事を参照してください。
CSS スタイルシート
ファイル内または HTML スタイルタグ内に含まれる CSS ルールのコレクション。
CSS 値
CSS プロパティの値。値はプロパティがどのように修正されるかを決定します。例：10vw の height: 10vw。
CSS 変数（vars）または CSS カスタムプロパティ
他の CSS 宣言で再利用できる値を持つプロパティ。カスタムプロパティ表記（例：--wp--preset--olive: #808000;）を使用して設定され、var() 関数（例：color: var( --wp--preset--olive );）を使用してアクセスされます。MDN の CSS カスタムプロパティに関する記事を参照してください。
グローバルスタイル（Gutenberg 内部）
テーマの theme.json とユーザースタイル設定からの値を含むマージされたブロックスタイルオブジェクト。
インラインスタイル
インラインスタイルは、スタイル属性内に含まれる単一の HTML 要素に影響を与える CSS 宣言です。
プロセッサ
保存された CSS ルールのコンパイルと最適化を行います。WP_Style_Engine_Processor クラスを参照してください。
ストア
関連するスタイルを含むデータオブジェクト。WP_Style_Engine_CSS_Rules_Store クラスを参照してください。