(旧) 基本的なブロックの作成

(2024/6/16) この文書の原文は削除されました。以後は「ブロック開発の基本原理」以下を参照ください。便宜上、しばらく訳文を掲載しますが、内容は更新されず、一部古くなっていますので注意してお読みください。

このガイドでは、投稿にメッセージを表示する基本的なブロックの作成方法を説明します。このメッセージは決め打ちで、ユーザーはメッセージを編集できません。このガイドは、ブロックの登録と読み込み方法の解説を目的とします。

ブロックには大きく分けて静的ブロックとダイナミックブロックがありますが、このガイドでは静的ブロックに焦点を当てます。静的ブロックは、HTML コンテンツを投稿に挿入し、投稿と一緒に保存するために使用されます。ダイナミックブロックは、フロントエンドでレンダーれる際に、その場でコンテンツを構築します。ダイナミックブロックガイドを参照してください。

このガイドではブロックだけを取り上げていますが、完全なセットアップについては ブロックの作成チュートリアル をご覧ください。

静的ブロックは JavaScript で実装されているため、JavaScript の基礎知識があると便利です。復習のためにJavaScript 入門 を参照してください。

ブロックはプラグインを使用して WordPress に追加されます。そのため、WordPress の開発環境が必要です。セットアップガイドを参照してください。

このチュートリアルではブロックの作成に JSX を使用する方法と、プレーンな JavaScript を使用する方法の2つの方法を紹介します。JSX ではビルド処理が必要なため、JavaScript ビルドツール (node/npm) が必要です。セットアップの詳細については、以下の「ステップ 0」を参照してください。

注意: このステップは、以降のステップで JSX のサンプルを使用する場合にのみ必要です。プレーンな JavaScript のサンプルを使用する場合は、ビルドステップなしで実行できるため、「ステップ 1: block.json の構成」に進んでください。

JSX のサンプルを使用する前に、プロジェクトをセットアップする必要があります。プロジェクトディレクトリで以下を実行してください。

npm init

このコマンドは package.json ファイルを作成します。

次に、開発の依存として package.json に @wordpress/scripts を追加する必要があります。これは以下で実行できます。

npm install @wordpress/scripts --save-dev

次に、package.json の scripts プロパティに以下の2行を追加します。

"start": "wp-scripts start",
"build": "wp-scripts build"

以上で準備ができました。

静的ブロックの機能は JavaScript で定義しますが、設定などのメタデータは block.json ファイルで定義する必要があります。

基本の設定は以下のとおりです。

• apiVersion: ブロック API バージョン
• title: インサーターに表示されるブロックのタイトル
• name: ブロックを定義する一意の名前
• category: インサーターでのカテゴリー (text, media, design, widgets, theme, embed)
• icon: ブロックで表示される Dashicon アイコン
• editorScript: ブロックでロードする JavaScript ファイル

block.json ファイルをプラグインに追加する必要があります。新しいプラグインを作成するには、WordPressの /wp-content/plugins/ にディレクトリを作成します。

そこに基本的な block.json ファイルを作成します。

{
	"apiVersion": 3,
	"title": "Example: Basic (ESNext)",
	"name": "gutenberg-examples/example-01-basic-esnext",
	"category": "layout",
	"icon": "universal-access-alt",
	"editorScript": "file:./build/index.js"
}

block.jsonがあれば、ブロックの登録は、PHPの1つの関数を呼び出すだけで済みます。ブロックと editorScript プロパティで指定された JavaScript ファイルがエディタに読み込まれます。

以下のように、完全なプラグインファイル index.php を作成します。同じ PHP コードが、JSX と Plain の両方のコードで機能します。

<?php
/**
 * Plugin Name: Gutenberg examples 01
 */
function gutenberg_examples_01_register_block() {
	register_block_type( __DIR__ );
}
add_action( 'init', 'gutenberg_examples_01_register_block' );

ブロックエディターでは、editorScript エントリが自動的にキューに入れられます。このファイルには、ブロック登録のためのJavaScript 部分が含まれ、ブロックの2つの重要な関数、 edit と save 関数を定義します。

edit 関数は、ブロックが挿入されたときにエディタに表示されるコンポーネントです。

save 関数は、ブロックが返し、post_content に保存される、最終的なマークアップを定義するコンポーネントです。

次のコードを src/index.js に追加してください。

/**
 * WordPress dependencies
 */
import { registerBlockType } from '@wordpress/blocks';

// Register the block
registerBlockType( 'gutenberg-examples/example-01-basic-esnext', {
	edit: function () {
		return <p> Hello world (from the editor)</p>;
	},
	save: function () {
		return <p> Hola mundo (from the frontend) </p>;
	},
} );

ブロックを登録するには、register_block_type() で使用したディレクトリと同じディレクトリに、スクリプトのファイル名で始まるアセットのphpファイルが必要です。

スクリプトとアセットファイルをビルドします。 依存関係やビルドバージョンの追跡に使用されます。

npm run build

エディターを開いて、新しいブロックを追加してください。インサーターに title を使用して、表示されます。
挿入されると、メッセージ「Hello World (from the editor)」が表示されます。

投稿を保存して、公開された投稿を見ると、メッセージ「Hola mundo (from frontend)」が表示されます。

トラブルシューティング – もし、問題が発生した場合は、以下を試してみてください。

• ファイル名が正しく、適切に読み込まれていることを確認してください。
• ブラウザの開発者コンソールで、エラーを確認してください。
• JSXを使用する場合は、変更するたびに忘れずにビルドしてください

最も基本的な静的ブロックを紹介しました。block-development-examples リポジトリには、両方の完全な例があります。

• JSX ビルドの基本的な例
• Plain な JavaScript の基本的な例,

注意: 例には、翻訳機能を含む完全なブロックのセットアップがあります。本番用のブロックでは例に従ってください。このガイドでは、簡便性と、ブロックの非常に基本的な部分に焦点を当てるため、国際化は省かれています。

ブロックを作成する際の注意点です。

• ブロック名には、プラグインに固有の名前空間をプレフィックスとして付ける必要があります。これは、複数のプラグインが同じ名前のブロックを登録した際に、衝突を防ぎます。この例では、名前空間は block-development-examples です。
• ブロック名は、小文字の英数字またはダッシュのみを含み、文字で始まらなければなりません。例: my-plugin/my-custom-block.

• block.json メタデータリファレス ドキュメント
• ブロック edit と save 関数リファレンス
• Dashicons アイコンセット

原文

最終更新日: 2024年6月17日