カスタムブロックをいくつも作っていくと、インサーター（ブロック挿入ツール）の中で自作ブロックが既定のカテゴリーに散らばってしまい、目的のブロックを探しにくくなります。WordPress では block_categories_all フィルターで独自のカテゴリーを追加でき、block.json の category にそのスラッグを指定すれば、自作ブロックをひとつのグループにまとめられます。この記事では既定カテゴリーの確認から、カテゴリーの追加方法、追加したのに表示されないときの原因までを解説します。
目次
ブロックカテゴリーはインサーターの分類
ブロックエディターの左上の「＋」ボタンから開くインサーターでは、ブロックが「テキスト」「メディア」のようなカテゴリーごとに区切って表示されます。この分類がブロックカテゴリーです。WordPress には次の6つのカテゴリーが最初から用意されています。
| スラッグ | 表示名 | 主なブロック |
|---|---|---|
text | テキスト | 段落・見出し・リストなどの文章系 |
media | メディア | 画像・ギャラリー・動画など |
design | デザイン | ボタン・カラム・グループなどのレイアウト系 |
widgets | ウィジェット | 最新の投稿・アーカイブ・検索など |
theme | テーマ | クエリーループ・テンプレートパーツなど |
embed | 埋め込み | YouTube などの外部コンテンツの埋め込み |
この一覧は WordPress 本体の get_default_block_categories() が返す配列がもとになっていて、各カテゴリーは slug・title・icon の3つのキーを持ちます（既定カテゴリーの icon はすべて null です）。あとで独自カテゴリーを追加するときも、この3つのキーを持つ配列を同じ形式で足すことになります。
ブロックの所属先は block.json の category で決まる
自作ブロックがどのカテゴリーに入るかは、block.json の category にカテゴリーのスラッグを書いて指定します。たとえば「ウィジェット」に入れたいなら次のようにします。
{
"$schema": "https://schemas.wp.org/trunk/block.json",
"apiVersion": 3,
"name": "mytheme/related-posts",
"title": "関連記事",
"category": "widgets",
"editorScript": "file:./index.js"
}既定の6カテゴリーのスラッグをそのまま使ってもよいのですが、ブロックの数が増えてくると「自分のブロックだけをまとめた場所」が欲しくなります。そこで登場するのが block_categories_all フィルターです。
block_categories_all で独自カテゴリーを追加する
block_categories_all は、エディターに渡されるブロックカテゴリーの配列を加工できるフィルターです。コールバックの第1引数にカテゴリーの配列、第2引数に WP_Block_Editor_Context（どのエディターで開かれているかの情報）を受け取ります。テーマの functions.php かプラグインに次のように書きます。
function mytheme_add_block_category( $block_categories, $editor_context ) {
// 配列の末尾に独自カテゴリーを追加する
$block_categories[] = array(
'slug' => 'mytheme-blocks', // block.json の category に書くスラッグ
'title' => 'オリジナルブロック', // インサーターに表示される名前
'icon' => null,
);
return $block_categories;
}
add_filter( 'block_categories_all', 'mytheme_add_block_category', 10, 2 );これだけで「オリジナルブロック」というカテゴリーが登録されます。add_filter の第4引数に 2 を渡しているのは、コールバックで第2引数の $editor_context まで受け取るためです。コンテキストを使わないなら省略しても動きますが、あとで条件分岐を足すことを考えると受け取っておくのがおすすめです。
先頭に追加して一番上に表示する
配列の末尾に追加すると、インサーターでは既定カテゴリーより下に表示されます。自作ブロックをよく使うサイトなら、array_merge() で配列の先頭に差し込むと一番上に表示できます。
function mytheme_add_block_category( $block_categories, $editor_context ) {
// 独自カテゴリーを先頭にして、既定カテゴリーを後ろに連結する
return array_merge(
array(
array(
'slug' => 'mytheme-blocks',
'title' => 'オリジナルブロック',
'icon' => null,
),
),
$block_categories
);
}
add_filter( 'block_categories_all', 'mytheme_add_block_category', 10, 2 );インサーターのカテゴリーは、この配列の並び順のまま表示されます。複数のカテゴリーを追加したい場合も、array_merge() に渡す配列に要素を増やせば同じ要領で並べられます。
icon には Dashicons のアイコン名を指定できる
icon キーには、WordPress 管理画面のアイコンセット「Dashicons」の名前を dashicons- プレフィックスを除いた文字列で指定できます（例: 'icon' => 'lightbulb'）。SVG を使いたい場合は、JavaScript 側で wp.blocks.updateCategory() を呼び、icon に SVG 要素を渡して上書きする方法があります。
ただし現在のブロックエディターでは、インサーター上のカテゴリーは名前がテキストの見出しとして表示されるだけで、アイコンが目立つ形では使われません。既定カテゴリーの icon もすべて null なので、こだわりがなければ null のままで問題ありません。
旧フィルター block_categories は非推奨
WordPress 5.8 より前は block_categories というフィルターが使われていて、第2引数には編集中の投稿（WP_Post）が渡されていました。しかし 5.8 でウィジェットエディターやサイトエディターなど「投稿を前提としない画面」にもブロックエディターが広がったため、block_categories は非推奨になり、代わりに block_categories_all が導入されました。
新しいフィルターの第2引数 WP_Block_Editor_Context には、投稿エディターであれば post プロパティに編集中の投稿が入ります。これを使うと「投稿エディターのときだけカテゴリーを追加する」といった出し分けもできます。
function mytheme_add_block_category( $block_categories, $editor_context ) {
// 投稿エディター以外（サイトエディターなど）では追加しない
if ( empty( $editor_context->post ) ) {
return $block_categories;
}
$block_categories[] = array(
'slug' => 'mytheme-blocks',
'title' => 'オリジナルブロック',
'icon' => null,
);
return $block_categories;
}
add_filter( 'block_categories_all', 'mytheme_add_block_category', 10, 2 );古い解説記事では add_filter( 'block_categories', ... ) のコードを見かけますが、これから書くコードでは block_categories_all を使ってください。旧フィルターも当面は動きますが、非推奨の警告対象で、サイトエディターなど投稿以外の画面では呼ばれません。
追加したカテゴリーに自作ブロックをまとめる
カテゴリーを追加できたら、あとは自作ブロックの block.json の category に、フィルターで登録したスラッグを指定するだけです。
{
"$schema": "https://schemas.wp.org/trunk/block.json",
"apiVersion": 3,
"name": "mytheme/related-posts",
"title": "関連記事",
"category": "mytheme-blocks",
"editorScript": "file:./index.js"
}複数のブロックで同じスラッグを指定すれば、それらがすべて「オリジナルブロック」カテゴリーの下に並びます。block.json は register_block_type() でブロックを登録するときに読み込まれるファイルなので、category の変更に JavaScript の再ビルドは必要ありません。ファイルを書き換えてエディターを再読み込みすれば反映されます。
カテゴリーが表示されない・ブロックが「未分類」になるとき
追加したカテゴリーにブロックが1つもない
インサーターに表示されるのは、所属するブロックが1つ以上あるカテゴリーだけです。フィルターでカテゴリーを追加しただけで、そのスラッグを指定したブロックがまだ存在しない場合、インサーターには何も表示されません。カテゴリーの登録自体は成功していることが多いので、まず block.json の category にスラッグを指定したブロックが有効になっているかを確認してください。
block.json の category とスラッグが一致していない
フィルターで登録したスラッグと block.json の category の値が食い違っていると、ブロックは存在しないカテゴリーを指定したことになります。この場合、ブラウザーのコンソールに「registered with an invalid category」という警告が出て、ブロックはインサーターの末尾の「未分類」グループに表示されます。mytheme-blocks と mytheme_blocks のようなハイフンとアンダースコアの取り違えが定番の原因なので、両方の文字列をコピーして見比べるのが確実です。
フィルターのコールバックで配列を返していない
フィルターのコールバックは、加工したカテゴリーの配列を必ず return する必要があります。$block_categories[] = array( ... ); と追加したあとに return を書き忘れると、カテゴリー一覧そのものが空になり、追加したカテゴリーどころか既定のカテゴリーまで巻き込んで表示が壊れます。エディターの様子が明らかにおかしくなったときは、まず戻り値を疑ってください。
まとめ
インサーターのブロックカテゴリーは、block_categories_all フィルターで slug・title・icon を持つ配列を足すだけで追加できます。末尾に追加すれば既定カテゴリーの下、array_merge() で先頭に差し込めば一番上に表示され、あとは block.json の category に同じスラッグを書けば自作ブロックがそのカテゴリーにまとまります。
旧フィルターの block_categories は WordPress 5.8 で非推奨になっているので、これから書くコードでは必ず block_categories_all を使ってください。カテゴリーが表示されないときは、所属ブロックの有無・スラッグの食い違い・戻り値の書き忘れ、の3点を順に確認すると原因にたどり着けます。