wp-block-development

WP ブロック開発

使用する場面

次のようなブロック作業でこのスキルを使用します。

• 新しいブロックの作成、または既存ブロックの更新
• block.json（scripts/styles/supports/attributes/render/viewScriptModule）の変更
• 「ブロックが無効／保存されない／属性が保持されない」問題の修正
• 動的レンダリング（render.php / render_callback）の追加
• ブロックの非推奨化と移行（deprecated バージョン）
• ブロックのビルドツール（@wordpress/scripts、@wordpress/create-block、wp-env）

必要な入力

• リポジトリのルートと対象（プラグイン、テーマ、またはサイト全体）。
• ブロック名／名前空間と配置場所（分かっている場合は block.json のパス）。
• 対象の WordPress バージョン範囲（特にモジュール／viewScriptModule を使用する場合）。

手順

0) トリアージとブロックの場所の特定

1. トリアージを実行します。
   • node skills/wp-project-triage/scripts/detect_wp_project.mjs
2. ブロックを一覧表示します（決定論的なスキャン）。
   • node skills/wp-block-development/scripts/list_blocks.mjs
3. 変更するブロックルート（block.json を含むディレクトリ）を特定します。

このリポジトリがサイト全体（wp-content/ が存在する場合）なら、どのプラグイン／テーマにブロックが含まれているかを明確にしてください。

1) 新しいブロックを作成する（必要な場合）

新しいブロックを作成する場合は、構造を手作業で組み立てるのではなく、スキャフォールディングを使用してください。

• @wordpress/create-block を使用して、最新のブロック／プラグイン構成をスキャフォールディングします。
• 最初から Interactivity API が必要な場合は、インタラクティブテンプレートを使用します。

以下を読みます。

• references/creating-new-blocks.md

スキャフォールディング後：

1. ブロック一覧表示スクリプトを再実行し、新しいブロックルートを確認します。
2. 残りの手順（モデルの選択、メタデータ、登録、シリアル化）に進みます。

2) apiVersion 3 を確保する（WordPress 6.9+）

WordPress 6.9 では、block.json スキーマで apiVersion: 3 が必須になります。apiVersion が 2 以下のブロックは、SCRIPT_DEBUG が有効なときにコンソール警告が発生します。

重要な理由：

• WordPress 7.0 では、ブロックの apiVersion にかかわらず、投稿エディターが iframe 内で動作します。
• apiVersion 3 にすると、iframe 内のエディターでブロックが正しく動作します（スタイルの分離、ビューポート単位、メディアクエリー）。

移行： バージョン 2 から 3 への変更は、通常、block.json の apiVersion フィールドを更新するだけです。ただし、次の点に注意してください。

• iframe エディターを有効にしたローカル環境でテストします。
• スタイルハンドルが block.json に含まれていることを確認します（iframe に読み込まれないスタイルは適用されません）。
• 特定の window に関連付けられたサードパーティ製スクリプトでは、スコープの問題が発生することがあります。

以下を読みます。

• references/block-json.md（apiVersion とスキーマの詳細）

3) 適切なブロックモデルを選択する

• 静的ブロック（マークアップを投稿コンテンツに保存）：save() を実装し、属性のシリアル化を安定させます。
• 動的ブロック（サーバー側でレンダリング）：block.json の render（または PHP の render_callback）を使用し、save() は最小限にするか null にします。
• フロントエンドのインタラクティブな動作：
  • 対応している場合は、最新のモジュールベースのビュースクリプトに viewScriptModule を使用します。
  • 主に data-wp-* ディレクティブやストアを扱う場合は、wp-interactivity-api も使用します。

4) block.json を安全に更新する

ブロックの block.json を変更し、登録内容がメタデータと一致していることを確認します。

フィールドごとのガイダンスについては、以下を読みます。

• references/block-json.md

よくある問題：

• name を変更すると互換性が損なわれます（安定した API として扱ってください）。
• 保存済みマークアップを変更する際に deprecated を追加しないと、「ブロックが無効」になります。
• 属性を追加する際に、ソース／シリアル化を正しく定義しないと、「属性が保存されない」問題が発生します。

5) ブロックを登録する（サーバー側を推奨）

特に次の場合は、メタデータを使用した PHP による登録を推奨します。

• 動的レンダリングが必要な場合
• 翻訳（wp_set_script_translations）が必要な場合
• アセットの条件付き読み込みが必要な場合

以下を読み、適用します。

• references/registration.md

6) 編集／保存／レンダリングのパターンを実装する

ラッパー属性のベストプラクティスに従ってください。

• エディター：useBlockProps()
• 静的な保存：useBlockProps.save()
• 動的レンダリング（PHP）：get_block_wrapper_attributes()

参照：

• references/supports-and-wrappers.md
• references/dynamic-rendering.md（動的な場合）

7) 内部ブロック（ブロックの構成）

ブロックがほかのブロックを内包する「コンテナー」である場合は、内部ブロックを第一級の機能として扱ってください。

• useInnerBlocksProps() を使って、内部ブロックをラッパーのプロパティに統合します。
• 内部マークアップを変更する場合は、マイグレーションも考慮してください。

参照：

• references/inner-blocks.md

8) 属性とシリアライズ

属性を変更する前に、次の点を確認してください。

• 属性値がどこにあるか（コメント区切り文字、HTML、コンテキスト）を確認します。
• 非推奨の meta 属性ソースは避けます。

参照：

• references/attributes-and-serialization.md

9) マイグレーションと非推奨化（「Invalid block」を回避する）

保存済みのマークアップまたは属性を変更する場合：

1. deprecated エントリーを追加します（新しいものから古いものの順）。
2. 古いバージョン用の save を用意し、必要に応じて属性を正規化する migrate を用意します。

参照：

• references/deprecations.md

10) ツールと検証コマンド

リポジトリで既に使われているものを優先してください。

• @wordpress/scripts（一般的）→ 既存の npm スクリプトを実行します。
• wp-env（一般的）→ ローカルの WP と E2E に使用します。

参照：

• references/tooling-and-testing.md

検証

• ブロックが挿入ツールに表示され、正常に挿入できます。
• 保存して再読み込みしても「Invalid block」が発生しません。
• フロントエンドの出力が想定どおりです（静的：保存済みマークアップ、動的：サーバー出力）。
• 想定される場所（エディターとフロントエンド）でアセットが読み込まれます。
• トリアージで推奨されているリポジトリの lint／ビルド／テストを実行します。

失敗のパターン／デバッグ

問題が発生した場合は、まず次を確認してください。

• references/debugging.md（よくある失敗と最速の確認方法）
• references/attributes-and-serialization.md（属性が保存されない場合）
• references/deprecations.md（変更後にブロックが無効になる場合）

エスカレーション

上流の動作やバージョンサポートに確信が持てない場合は、まず公式ドキュメントを確認してください。

• WordPress Developer Resources（Block Editor Handbook、Theme Handbook、Plugin Handbook）
• 最先端の動作については、Gutenberg リポジトリのドキュメント