フックリファレンス - ブロックフィルター（Block Filters）

登録
フロントエンド
- render_block
- renderblock{namespace/block}
エディター
ブロックの削除
- 拒否リストの使用
- 許可リストの使用
挿入ツールからのブロックの非表示
- allowed_block_types_all
ブロックカテゴリの管理
- block_categories_all
- wp.blocks.updateCategory

登録

WordPressのブロックは、通常、block.jsonメタデータを使用してサーバー側とクライアント側の両方で登録されます。以下のフィルターを使用して、PHPでサーバー上での登録中やJavaScriptでクライアント上でのブロック設定を変更または拡張できます。詳細については、ブロック登録ガイドを参照してください。

block_type_metadata

サーバー上でPHPを使用してブロックタイプを登録する際に、block.jsonファイルから読み込まれた生のメタデータをフィルタリングします。メタデータが処理される前に変更を適用できます。

このフィルターのコールバック関数は、1つのパラメーターを受け取ります:

$metadata (array): ブロックタイプを登録するためにblock.jsonから読み込まれたメタデータ。

以下の例では、すべてのブロックのapiVersionを2に設定します。

function example_filter_metadata_registration( $metadata ) {
   $metadata['apiVersion'] = 2;
   return $metadata;
};
add_filter( 'block_type_metadata', 'example_filter_metadata_registration' );

ここでは、見出しブロックの背景色とグラデーションサポートを無効にするより堅牢な例を示します。block_type_metadataフィルターは、エディター体験のキュレーションに最適です。

function example_disable_heading_background_color_and_gradients( $metadata ) {
   // Only apply the filter to Heading blocks.
   if ( ! isset( $metadata['name'] ) || 'core/heading' !== $metadata['name'] ) {
   return $metadata;
   }
   // Check if 'supports' key exists.
   if ( isset( $metadata['supports'] ) && isset( $metadata['supports']['color'] ) ) {
   // Remove Background color and Gradients support.
   $metadata['supports']['color']['background'] = false;
   $metadata['supports']['color']['gradients']  = false;
   }
   return $metadata;
}
add_filter( 'block_type_metadata', 'example_disable_heading_background_color_and_gradients' );

block_type_metadata_settings

処理されたブロックタイプメタデータから決定された設定をフィルタリングします。デフォルトで処理されないブロックメタデータを使用してカスタム変更を適用できます。

このフィルターのコールバック関数は、2つのパラメーターを受け取ります:

$settings (array): ブロックタイプを登録するための決定された設定の配列。
$metadata (array): block.jsonファイルから読み込まれたメタデータ。

以下の例では、すべてのブロックのapiVersionを1だけ増加させます。

function example_filter_metadata_registration( $settings, $metadata ) {
   $settings['api_version'] = $metadata['apiVersion'] + 1;
   return $settings;
};
add_filter( 'block_type_metadata_settings', 'example_filter_metadata_registration', 10, 2 );

register_block_type_args

ブロックタイプがサーバー上で正式に登録される直前に、ブロックの引数配列($args)をフィルタリングします。

このフィルターのコールバック関数は、2つのパラメーターを受け取ります:

$args (array): ブロックタイプを登録するための引数の配列。
$block_type (string): 名前空間を含むブロックタイプ名。


以下のコードは、段落、見出し、リスト、およびリストアイテムブロックの色のコントロールを無効にします。  
``````bash
function example_disable_color_for_specific_blocks( $args, $block_type ) {
   // List of block types to modify.
   $block_types_to_modify = [
   'core/paragraph',
   'core/heading',
   'core/list',
   'core/list-item'
   ];
   // Check if the current block type is in the list.
   if ( in_array( $block_type, $block_types_to_modify, true ) ) {
   // Disable color controls.
   $args['supports']['color'] = array(
   'text'       => false,
   'background' => false,
   'link'       => false,
   );
   }
   return $args;
}
add_filter( 'register_block_type_args', 'example_disable_color_for_specific_blocks', 10, 2 );
`

blocks.registerBlockType

JavaScriptを使用してクライアントでブロックを登録する際に、ブロック設定をフィルタリングするために使用されます。ブロック設定、登録されたブロックの名前、およびnullまたは非推奨のブロック設定（登録された非推奨に適用される場合）を引数として受け取ります。このフィルターは、ブロックの非推奨設定のそれぞれにも適用されます。

以下の例では、リストブロックが標準生成クラス名(wp-block-list)で保存されることを保証します:

function addListBlockClassName( settings, name ) {
   if ( name !== 'core/list' ) {
   return settings;
   }
   return {
   ...settings,
   supports: {
   ...settings.supports,
   className: true,
   },
   };
}
wp.hooks.addFilter(
   'blocks.registerBlockType',
   'my-plugin/class-names/list-block',
   addListBlockClassName
);

フロントエンド

フロントエンドでブロックの出力を変更するために利用できるPHPフィルターは次のとおりです。

render_block

任意のブロックのフロントエンドコンテンツをフィルタリングします。このフィルターは、エディター内のブロックの動作には影響しません。

このフィルターのコールバック関数は、3つのパラメーターを受け取ります:

$block_content (string): ブロックコンテンツ。
$block (array): 名前と属性を含む完全なブロック。
$instance (WP_Block): ブロックインスタンス。

以下の例では、クラスexample-classがフロントエンドのすべての段落ブロックに追加されます。ここでは、HTML APIを使用して、正規表現に依存せずにクラスを簡単に追加します。

function example_add_custom_class_to_paragraph_block( $block_content, $block ) {
   // Check if the block is a Paragraph block.
   if ( 'core/paragraph' === $block['blockName'] ) {
   // Add the custom class to the block content using the HTML API.
   $processor = new WP_HTML_Tag_Processor( $block_content );
   if ( $processor->next_tag( 'p' ) ) {
   $processor->add_class( 'example-class' );
   }
   return $processor->get_updated_html();
   }
   return $block_content;
}
add_filter( 'render_block', 'example_add_custom_class_to_paragraph_block', 10, 2 );

renderblock{namespace/block}

定義されたブロックのフロントエンドコンテンツをフィルタリングします。これは、特定のブロックタイプを変更する必要がある場合のrender_blockの単純な形式です。

このフィルターのコールバック関数は、3つのパラメーターを受け取ります:

$block_content (string): ブロックコンテンツ。
$block (array): 名前と属性を含む完全なブロック。
$instance (WP_Block): ブロックインスタンス。

以下の例では、クラスexample-classがフロントエンドのすべての段落ブロックに追加されます。上記のrender_blockの例と比較して、コンテンツを変更する前にブロックタイプを確認する必要がなくなります。再度、HTML APIが正規表現の代わりに使用されます。

function example_add_custom_class_to_paragraph_block( $block_content, $block ) {
   // Add the custom class to the block content using the HTML API.
   $processor = new WP_HTML_Tag_Processor( $block_content );
   if ( $processor->next_tag( 'p' ) ) {
   $processor->add_class( 'example-class' );
   }
   return $processor->get_updated_html();
}
add_filter( 'render_block_core/paragraph', 'example_add_custom_class_to_paragraph_block', 10, 2 );

エディター

エディターで編集中のブロックの動作を変更するために利用できるJavaScriptフィルターは次のとおりです。

blocks.getSaveElement

ブロックのsave関数の結果に適用されるフィルターです。このフィルターは、要素を置き換えたり拡張したりするために使用されます。たとえば、React.cloneElementを使用して要素のプロパティを変更したり、子要素を置き換えたり、まったく新しい要素を返したりします。

このフィルターのコールバック関数は、3つのパラメーターを受け取ります:

element (Object): 修正されて返される要素。
blockType (Object): ブロックタイプ定義オブジェクト。
attributes (Object): ブロックの属性。

以下の例では、カバーブロックを外部コンテナdivでラップします。

function wrapCoverBlockInContainer( element, blockType, attributes ) {
   // Skip if element is undefined.
   if ( ! element ) {
   return;
   }
   // Only apply to Cover blocks.
   if ( blockType.name !== 'core/cover' ) {
   return element;
   }
   // Return the element wrapped in a div.
   return <div className="cover-block-wrapper">{ element }</div>;
}
wp.hooks.addFilter(
   'blocks.getSaveElement',
   'my-plugin/wrap-cover-block-in-container',
   wrapCoverBlockInContainer
);

blocks.getSaveContent.extraProps


このフィルターのコールバック関数は、3つのパラメーターを受け取ります:  
- `````props````` (`````Object`````): 修正されて返される現在の`````save`````要素のプロパティ。 
- `````blockType````` (`````Object`````): ブロックタイプ定義オブジェクト。  
- `````attributes````` (`````Object`````): ブロックの属性。
以下の例では、すべてのブロックにデフォルトで赤い背景を追加します。  
``````bash
function addBackgroundColorStyle( props ) {
   return {
   ...props,
   style: { backgroundColor: 'red' },
   };
}
wp.hooks.addFilter(
   'blocks.getSaveContent.extraProps',
   'my-plugin/add-background-color-style',
   addBackgroundColorStyle
);
`

注意: このフィルターが次回投稿が編集されるときに既存のコンテンツを変更すると、ブロック検証エラーが発生します。エディターは、投稿に保存されたコンテンツがsave()関数によって出力されたコンテンツと一致することを確認します。

この検証エラーを回避するには、render_blockをサーバー側で使用して、既存の投稿コンテンツをこのフィルターの代わりに変更します。render_blockドキュメントを参照してください。

blocks.getBlockDefaultClassName

ブロックの生成されたHTMLクラスは、wp-block-{name}命名法に従います。このフィルターを使用すると、代替のクラス名を提供できます。

// Our filter function.
function setBlockCustomClassName( className, blockName ) {
   return blockName === 'core/code' ? 'my-plugin-code' : className;
}
// Adding the filter.
wp.hooks.addFilter(
   'blocks.getBlockDefaultClassName',
   'my-plugin/set-block-custom-class-name',
   setBlockCustomClassName
);

blocks.switchToBlockType.transformedBlock

ブロック変換からの個々の変換結果をフィルタリングするために使用されます。変換は多対多であり、1対1ではないため、すべての元のブロックが渡されます。

blocks.getBlockAttributes

ブロックの属性のデフォルト解析の直後に呼び出され、検証の前にプラグインが属性値を操作できるようにします。

このフィルターのコールバック関数は、4つのパラメーターを受け取ります:

– blockAttributes (Object): すべてのブロック属性。

– blockType (Object): ブロックタイプ。

– innerHTML (string): 生のブロックコンテンツ。

– attributes (object): 既知のブロック属性（区切り記号から）。

以下の例では、blocks.getBlockAttributesフィルターを使用して、ページ上のすべての段落ブロックの位置をロックします。

// Our filter function
function lockParagraphs( blockAttributes, blockType, innerHTML, attributes  ) {
   if('core/paragraph' === blockType.name) {
   blockAttributes['lock'] = {move: true}
   }
   return blockAttributes;
}
// Add the filter
wp.hooks.addFilter(
   'blocks.getBlockAttributes',
   'my-plugin/lock-paragraphs',
   lockParagraphs
);

editor.BlockEdit

ブロックのeditコンポーネントを変更するために使用されます。元のブロックBlockEditコンポーネントを受け取り、新しいラップされたコンポーネントを返します。

以下の例では、すべてのブロックに新しいインスペクターパネルを追加します。

const { createHigherOrderComponent } = wp.compose;
const { InspectorControls } = wp.blockEditor;
const { PanelBody } = wp.components;
const withMyPluginControls = createHigherOrderComponent( ( BlockEdit ) => {
   return ( props ) => {
   return (
   <>
   <BlockEdit key="edit" { ...props } />
   <InspectorControls>
   <PanelBody>My custom control</PanelBody>
   </InspectorControls>
   </>
   );
   };
}, 'withMyPluginControls' );
wp.hooks.addFilter(
   'editor.BlockEdit',
   'my-plugin/with-inspector-controls',
   withMyPluginControls
);

このフックはすべてのブロックに対して実行されるため、消費することでパフォーマンスの回帰が発生する可能性があります。特にブロック選択メトリックに関してです。

これを軽減するために、実行する作業が特定の条件下でのみ実行されるように変更できるかどうかを検討してください。

たとえば、ブロックが選択されたときにのみレンダリングする必要があるコンポーネントを追加しているとします。この場合、ブロックの「選択された」状態(props.isSelected)を使用してレンダリングを条件付けできます。

以下の例では、すべてのブロックに新しいインスペクターパネルを追加しますが、ブロックが選択されているときのみです。

const withMyPluginControls = createHigherOrderComponent( ( BlockEdit ) => {
   return ( props ) => {
   return (
   <>
   <BlockEdit { ...props } />
   { props.isSelected && (
   <InspectorControls>
   <PanelBody>My custom control</PanelBody>
   </InspectorControls>
   ) }
   </>
   );
   };
}, 'withMyPluginControls' );

editor.BlockListBlock

ブロックのeditコンポーネントとすべてのツールバーを含むブロックのラッパーコンポーネントを変更するために使用されます。元のBlockListBlockコンポーネントを受け取り、新しいラップされたコンポーネントを返します。

以下の例では、すべてのブロックにユニークなクラス名を追加します。

const { createHigherOrderComponent } = wp.compose;
const withClientIdClassName = createHigherOrderComponent(
   ( BlockListBlock ) => {
   return ( props ) => {
   return (
   <BlockListBlock
   { ...props }
   className={ 'block-' + props.clientId }
   />
   );
   };
   },
   'withClientIdClassName'
);
wp.hooks.addFilter(
   'editor.BlockListBlock',
   'my-plugin/with-client-id-class-name',
   withClientIdClassName
);

ラップされたコンポーネントのwrapperPropsプロパティを使用して、ブロックのラッパーコンポーネントに新しいプロパティを追加できます。以下の例のように。

const { createHigherOrderComponent } = wp.compose;
const withMyWrapperProp = createHigherOrderComponent( ( BlockListBlock ) => {
   return ( props ) => {
   const wrapperProps = {
   ...props.wrapperProps,
   'data-my-property': 'the-value',
   };
   return <BlockListBlock { ...props } wrapperProps={ wrapperProps } />;
   };
}, 'withMyWrapperProp' );
wp.hooks.addFilter(
   'editor.BlockListBlock',
   'my-plugin/with-my-wrapper-prop',
   withMyWrapperProp
);

editor.postContentBlockTypes

ロックされたテンプレート内で使用されている場合でも、有効にする必要があるブロックのリストを変更するために使用されます。投稿にデータを保存するすべてのブロックは、ここに追加する必要があります。これの例は、投稿のフィーチャー画像ブロックです。テンプレートでよく使用されるこのブロックは、テンプレートがロックされている場合でも画像を選択できるようにする必要があります。

以下の例では、架空のブロックnamespace/exampleを有効にします。

const addExampleBlockToPostContentBlockTypes = ( blockTypes ) => {
   return [ ...blockTypes, 'namespace/example' ];
};
wp.hooks.addFilter(
   'editor.postContentBlockTypes',
   'my-plugin/post-content-block-types',
   addExampleBlockToPostContentBlockTypes
);

ブロックの削除

拒否リストの使用

ブロックを追加するのは簡単で、削除するのも同様です。プラグインやテーマの著者は、JavaScriptの拒否リストを使用してブロックを「登録解除」できます。

次のコードをmy-plugin.jsファイルに配置します。

// my-plugin.js
import { unregisterBlockType } from '@wordpress/blocks';
import domReady from '@wordpress/dom-ready';
domReady( function () {
   unregisterBlockType( 'core/verse' );
} );

次に、次の関数を使用してエディターでこのスクリプトを読み込みます。

<?php
// my-plugin.php
function my_plugin_deny_list_blocks() {
   wp_enqueue_script(
   'my-plugin-deny-list-blocks',
   plugins_url( 'my-plugin.js', __FILE__ ),
   array( 'wp-blocks', 'wp-dom-ready', 'wp-edit-post' )
   );
}
add_action( 'enqueue_block_editor_assets', 'my_plugin_deny_list_blocks' );

ブロックを登録解除する際には、どのコードが最初に実行されるかに競合条件が発生する可能性があります: ブロックを登録するか、ブロックを登録解除するか。登録解除コードが最後に実行されるようにしたいです。これを行うには、ブロックを登録しているコンポーネントを依存関係として指定する必要があります。この場合、wp-edit-postです。さらに、wp.domReady()を使用すると、DOMが読み込まれた後に登録解除コードが実行されることが保証されます。

許可リストの使用

許可リストを除いてすべてのブロックを無効にしたい場合は、上記のスクリプトを次のように適応できます:

// my-plugin.js
var allowedBlocks = [
   'core/paragraph',
   'core/image',
   'core/html',
   'core/freeform',
];
wp.blocks.getBlockTypes().forEach( function ( blockType ) {
   if ( allowedBlocks.indexOf( blockType.name ) === -1 ) {
   wp.blocks.unregisterBlockType( blockType.name );
   }
} );

挿入ツールからのブロックの非表示

allowed_block_types_all

WordPress 5.8以前は、このフックはallowed_block_typesとして知られており、現在は非推奨です。古いバージョンのWordPressをサポートする必要がある場合、どのフィルターを使用するかを検出する方法が必要になるかもしれません。allowed_block_typesが使用可能かどうかは、5.8で導入されたWP_Block_Editor_Contextクラスが存在するかどうかを確認することで確認できます。

サーバー上で、allowed_block_types_allフィルターを使用して挿入ツールに表示されるブロックのリストをフィルタリングできます。すべてのブロックタイプがサポートされている場合はtrue（すべてのブロックタイプがサポートされている）、false（ブロックタイプはサポートされていない）、または許可するブロックタイプ名の配列を返すことができます。また、提供された2番目のパラメーター$editor_contextを使用して、コンテンツに基づいてブロックタイプをフィルタリングできます。

<?php
// my-plugin.php
function example_filter_allowed_block_types_when_post_provided( $allowed_block_types, $editor_context ) {
   if ( ! empty( $editor_context->post ) ) {
   return array( 'core/paragraph', 'core/heading' );
   }
   return $allowed_block_types;
}
add_filter( 'allowed_block_types_all', 'example_filter_allowed_block_types_when_post_provided', 10, 2 );

ブロックカテゴリの管理

block_categories_all

WordPress 5.8以前は、このフックはblock_categoriesとして知られており、現在は非推奨です。古いバージョンのWordPressをサポートする必要がある場合、どのフィルターを使用するかを検出する方法が必要になるかもしれません。block_categoriesが使用可能かどうかは、5.8で導入されたWP_Block_Editor_Contextクラスが存在するかどうかを確認することで確認できます。


``````bash
// my-plugin.php
function example_filter_block_categories_when_post_provided( $block_categories, $editor_context ) {
   if ( ! empty( $editor_context->post ) ) {
   array_push(
   $block_categories,
   array(
   'slug'  => 'custom-category',
   'title' => __( 'Custom Category', 'custom-plugin' ),
   'icon'  => null,
   )
   );
   }
   return $block_categories;
}
add_filter( 'block_categories_all', 'example_filter_block_categories_when_post_provided', 10, 2 );
`

wp.blocks.updateCategory

ブロックカテゴリにアイコンを表示するには、icon属性を設定します。値はWordPress Dashiconのスラッグにすることができます。

SVG形式のカスタムアイコンを設定することもできます。そのためには、アイコンをレンダリングしてフロントエンドに設定する必要があります。これにより、WordPress SVGを利用でき、モバイル互換性が向上し、アイコンがよりアクセスしやすくなります。

前の例で表示されたカテゴリのSVGアイコンを設定するには、次のJavaScriptコードをエディターに追加し、wp.blocks.updateCategoryを呼び出します。例えば:

( function () {
   var el = React.createElement;
   var SVG = wp.primitives.SVG;
   var circle = el( 'circle', {
   cx: 10,
   cy: 10,
   r: 10,
   fill: 'red',
   stroke: 'blue',
   strokeWidth: '10',
   } );
   var svgIcon = el(
   SVG,
   { width: 20, height: 20, viewBox: '0 0 20 20' },
   circle
   );
   wp.blocks.updateCategory( 'my-category', { icon: svgIcon } );
} )();