ブロックエディター

theme.json で編集者が使える色や文字サイズを制限し、カスタムブロックとパターンで編集する部品を用意するルール

ブロックエディターは、編集者がデザインを崩さずに更新できる範囲に絞って提供します。自由度を残しすぎると、公開後に色や文字サイズがページごとにばらばらになり、デザインの統一を保てなくなるためです。

theme.json

色・文字サイズ・余白の選択肢は、theme.json でデザインのトークンに合わせて定義します。 CSS のカスタムプロパティと同じ値を使い、エディターの表示とサイトの表示を揃えます（CSS 変数）。

編集者が任意の値を入力できる機能は、デザイン上必要な場合を除いて無効にします。

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 3,
  "settings": {
    "color": {
      "custom": false,
      "customGradient": false,
      "defaultPalette": false,
      "defaultGradients": false,
      "palette": [
        { "slug": "primary", "color": "#0a4b8c", "name": "メイン" },
        { "slug": "text", "color": "#222222", "name": "本文" }
      ]
    },
    "typography": {
      "customFontSize": false,
      "defaultFontSizes": false,
      "fontSizes": [
        { "slug": "small", "size": "0.875rem", "name": "小" },
        { "slug": "medium", "size": "1rem", "name": "標準" },
        { "slug": "large", "size": "1.25rem", "name": "大" }
      ]
    }
  }
}

使えるブロックの制限

編集者が使うブロックは、案件で必要なものに絞ります。使わないブロックが一覧に並んでいると、デザインが用意されていないブロックが使われ、表示が崩れる原因になります。

ブロックの制限は、allowed_block_types_all フィルターで行います。

add_filter(
  "allowed_block_types_all",
  function ($allowed_block_types, $block_editor_context) {
    if ("post" !== ($block_editor_context->post->post_type ?? "")) {
      return $allowed_block_types;
    }

    return ["core/paragraph", "core/heading", "core/list", "core/list-item", "core/image", "core/buttons", "core/button", "theme/card"];
  },
  10,
  2
);

core/list と core/list-item のように、親子で使うブロックは両方を許可してください。子のブロックを許可しないと、親のブロックを挿入しても中身を追加できません。案件で作ったカスタムブロック（例では theme/card）も、一覧に加えてください。

カスタムブロック

コアのブロックで作れない部品（デザインの決まったカード、比較表など）は、カスタムブロックとして作ります。ブロックは theme/blocks/ に置くと、ビルド後に functions/blocks.php が自動で登録します。作成とビルドの手順は、テンプレートの theme/blocks/README.md を参照してください。

動的ブロックを基本にする

カスタムブロックは、PHP（render.php）で HTML を出力する動的ブロックを基本とします。

JavaScript の save で HTML を保存する静的ブロックは、保存した HTML が投稿本文に残ります。公開後にブロックのマークアップを変えると、保存済みの HTML と一致しなくなり、エディターで「このブロックには、想定されていないか無効なコンテンツが含まれています」と表示されます。動的ブロックは表示のたびに PHP で HTML を組み立てるため、マークアップを変えても既存の投稿に影響しません。

動的ブロックの雛形は、@wordpress/create-block の --variant dynamic で生成できます。

ACF / SCF を使う案件では、PHP のテンプレートとフィールドだけで作れる ACF Blocks を使ってもかまいません。 ACF Blocks も表示のたびに PHP で HTML を組み立てるため、動的ブロックと同じくマークアップを変えても既存の投稿に影響しません。

パターン

複数のブロックを組み合わせた定型のレイアウト（お知らせの本文、よくある質問など）は、パターンとして用意します。パターンは theme/patterns/ に PHP ファイルとして置くと、WordPress が自動で登録します。ファイル先頭のコメントに Title と Slug を書きます。

<?php
/**
 * Title: よくある質問
 * Slug: theme/faq
 * Categories: text
 */
?>
<!-- wp:heading -->
<h2 class="wp-block-heading">よくある質問</h2>
<!-- /wp:heading -->

パターンは挿入時にブロックへ展開されるため、パターンのファイルを修正しても、挿入済みの投稿は変わりません。