フィルターとフック

Topics

エディターには編集体験を変更する、多くのフィルターやフックが用意されています。以下にその一部を紹介します。

エディターの設定

エディターを変更する最も一般的な方法の1つが block_editor_settings_all PHP フィルターです。このフィルターは初期化されたエディターに設定が送られる前に適用されます。

block_editor_settings_all フックはコールバック関数に2つのパラメータを渡します。

次の例では、プラグインを有効化できないユーザー (管理者) に対してコードエディターを無効にします。これをプラグインまたはテーマの functions.php ファイル内に追加してテストしてください。

add_filter( 'block_editor_settings_all', 'example_restrict_code_editor' );

function example_restrict_code_editor( $settings ) {
	$can_active_plugins = current_user_can( 'activate_plugins' );

	// プラグインを有効化できないユーザー (管理者) に対してコードエディターを無効化する
	if ( ! $can_active_plugins ) {
		$settings[ 'codeEditingEnabled' ] = false;
	}

	return $settings;
}

その他の例については、以下のユースケースを含むEditor Hooksドキュメントをチェックしてください。

Top ↑

サーバーサイド theme.json フィルター

theme.json ファイルはインターフェースオプションを制御する素晴らしい方法ですが、グローバルまたはブロックレベルの変更しかできないため、シナリオによっては制限されることがあります。

例えば、前のセクションでは、theme.json を使用して色とタイポグラフィのコントロールをグローバルに無効にしましたが、管理者ユーザーに対しては色の設定を有効にしたい場合などです。

より柔軟性を持たせるため、WordPress 6.1では、4つの異なるデータレイヤーで theme.json データをカスタマイズできるサーバーサイドフィルターを導入しました。

以下の例では、wp_theme_json_data_theme フィルターを使用して、現在のテーマの theme.json ファイルのデータを更新します。現在のユーザーが管理者であれば、色のコントロールが復元されます。

// 管理者以外のすべてのユーザーの色コントロールを無効にする
function example_filter_theme_json_data_theme( $theme_json ){
    $is_administrator = current_user_can( 'edit_theme_options' );

    if ( $is_administrator ) {
        $new_data = array(
            'version'  => 2,
            'settings' => array(
                'color' => array(
                    'background'       => true,
                    'custom'           => true,
                    'customDuotone'    => true,
                    'customGradient'   => true,
                    'defaultGradients' => true,
                    'defaultPalette'   => true,
                    'text'             => true,
                ),
            ),
        );
    }

	return $theme_json->update_with( $new_data );
}
add_filter( 'wp_theme_json_data_theme', 'example_filter_theme_json_data_theme' );

このフィルターは、それぞれのレイヤーのデータを含む WP_Theme_JSON_Data クラスのインスタンスを受け取ります。そこで、update_with( $new_data ) メソッドに、有効な theme.json に似た構造の新しいデータを渡します。$new_dataにはtheme.json のバージョン番号が必要です。

Top ↑

クライアントサイド (エディター) フィルター

WordPress 6.2では、新しいクライアント側フィルターが導入されました。エディターがレンダーされる前にブロックレベルでtheme.json settings を変更できます。

このフィルターは blockEditor.useSetting.before と呼ばれ、JavaScript のコードで以下のように使用します。

import { addFilter } from '@wordpress/hooks';

/**
 * カラムブロックのスペースオプションを px に制限する。
 */
addFilter(
	'blockEditor.useSetting.before',
	'example/useSetting.before',
	( settingValue, settingName, clientId, blockName ) => {
		if ( blockName === 'core/column' && settingName === 'spacing.units' ) {
			return [ 'px' ];
		}
		return settingValue;
	}
);

この例では、カラムブロックで使用可能なスペースの単位をピクセルだけに制限します。上述したように、同様の制限は、theme.json フィルターを使用するか、ブロックレベルの設定を使用してテーマの theme.json ファイルで直接適用できます。

しかし、blockEditor.useSetting.before フィルターは、ブロックの位置、隣接するブロック、現在のユーザーの役割などに応じて設定を変更できる点でユニークです。カスタマイズの可能性は広範囲にわたります。

次の例では、見出しブロックがメディアとテキストブロックの中に配置されると、テキストの色コントロールが無効になります。

import { select } from  '@wordpress/data';
import { addFilter } from '@wordpress/hooks';

/**
 * メディアとテキストブロック内に配置された見出しブロックのテキスト色コントロールは無効化する。
 */
addFilter(
	'blockEditor.useSetting.before',
	'example/useSetting.before',
	( settingValue, settingName, clientId, blockName ) => {
		if ( blockName === 'core/heading' ) {
			const { getBlockParents, getBlockName } = select( 'core/block-editor' );
			const blockParents = getBlockParents( clientId, true );
			const inMediaText = blockParents.some( ( ancestorId ) => getBlockName( ancestorId ) === 'core/media-text' );

			if ( inMediaText && settingName === 'color.text' ) {
			    return false;
			}
		}

		return settingValue;
	}
);

Top ↑

ブロックフィルター

エディターそのもののカスタマイズだけでなく、個々のブロックを変更する方法も数多くあります。例えば、特定のブロックの背景色などのサポートを無効化したり、デフォルトで表示される設定を定義できます。

最もよく使われるフィルターの1つが block_type_metadata です。サーバー上で PHP でブロックタイプを登録する際に、ブロックの block.json ファイルから読み込まれた生のメタデータをフィルタリングできます。

フィルターは1つのパラメーターを取ります。

  • $metadata (array) – 登録するブロックタイプの block.json から読み込まれるメタデータ

metadata 配列にはブロックの説明や属性からブロックのサポートまで、ブロックに関するあらゆる情報が含まれています。

以下の例では、見出しブロックの背景色とグラデーションのサポートを無効化します。

function example_disable_heading_background_color_and_gradients( $metadata ) {

    // フィルターは見出しブロックのみに適用
    if ( ! isset( $metadata['name'] ) || 'core/heading' !== $metadata['name'] ) {
        return $metadata;
    }

    // 'supports' キーの存在を確認
    if ( isset( $metadata['supports'] ) && isset( $metadata['supports']['color'] ) ) {

        // 背景色とグラデーションサポートを削除
        $metadata['supports']['color']['background'] = false;
        $metadata['supports']['color']['gradients']  = false;
    }

    return $metadata;
}
add_filter( 'block_type_metadata', 'example_disable_heading_background_color_and_gradients' );

利用可能なブロックフィルターの詳細については、ブロックフィルター ドキュメントを参照してください。

Top ↑

追加の情報

原文

最終更新日: