(2024/1/20) この文書の原文は削除されました。以後は「チュートリアル: はじめてのブロック作成」を参照ください。便宜上、しばらく訳文を掲載しますが、内容は更新されず、一部古くなっていますので注意してお読みください。
ブロックは WordPress プラグインを使用してブロックエディターに追加されます。ユーザーはプラグインを作成し、インストール、有効化してブロックを使用できます。ここではまず、WordPress プラグインの構成から見ていきます。
プラグインの詳細
「WordPress プラグイン」の実体は Web サイトの wp-content/plugins
ディレクトリ内にあるファイルの集合です。このチュートリアルでは @wordpress/create-block
パッケージを使用して、必要なプラグインファイルを生成します。
ワーキングディレクトリへの切り替え
(1A) wp-env
を使う予定がなければ、ローカルの WordPress プラグインディレクトリに移動してください。たとえば Local by Flywheel (以下、Local) であれば ~\Local Sites\mywp\app\public\wp-content\plugins
です。
または
(1B) wp-env start
を使う場合、任意のプロジェクト用ディレクトリから始めることができます。wp-env
がサイトのプラグインディレクトリにマッピングします。
プラグインファイルの生成
(2) 環境の適切なディレクトリに移動後、次のコマンドを実行してプラグインファイルを生成します。
npx @wordpress/create-block gutenpride
cd gutenpride
新しいディレクトリ gutenpride
とすべての必要なプラグインファイルが作成されます。以下、プラグインファイルを見ながら説明します。一緒にファイルを確認し、内容に親しんでください。
作成されるメインのプラグインファイルは PHP ファイル gutenpride.php
です。このファイルの先頭部分には、プラグインを定義する、プラグインヘッダーコメントブロックがあります。
/**
* Plugin Name: Gutenpride
* Description: Example static block scaffolded with Create Block tool.
* Requires at least: 5.8
* Requires PHP: 7.0
* Version: 0.1.0
* Author: The WordPress Contributors
* License: GPL-2.0-or-later
* License URI: https://www.gnu.org/licenses/gpl-2.0.html
* Text Domain: gutenpride
*
* @package create-block
*/
WordPress の起動
プラグインがロードでき、動作することを確認します。
(3A) Local や他の環境であれば WordPress サイトが起動していることを確認してください。
または
(3B) wp-env
を使用する場合は、まず開発環境のセットアップ を参照してください。次に gutenpride
ディレクトリ內部から以下を実行します。
wp-env start
ローカルで WordPress を起動し、カレントディレクトリをプラグインディレクトリとして使用します。ブラウザから http://localhost:8888/wp-admin/ にアクセスしてログインします。デフォルトユーザー名は「admin」、パスワードは「password」です。
Plugin のインストールの確認
生成されたプラグインは WordPress 管理画面の「プラグイン」ページのリストに表示されます。プラグインを有効化してください。
WordPress プラグイン作成の詳細については Plugin Basics を参照してください。またプラグインヘッダーのフィールドの説明、追加可能なフィールドについては Plugin Header requirements を参照してください。
package.json
package.json
ファイルはプロジェクトの JavaScript プロパティを定義します。これは NPM で使用される標準ファイルで、プロパティや実行可能なスクリプトを含みます。ファイルやプロセスは WordPress 固有のものではありません。
package.json
ファイルは create スクリプトで作成され、依存性と必要なスクリプトを定義します。最初からある依存性は @wordpress/scripts
パッケージで、ブロック構築に必要なツールと構成をバンドルします。
package.json
には scripts
プロパティがあり、npm run (cmd)
を使用した際に実行されるコマンドが定義されています。生成された package.json
ファイルでは、2つのメインのスクリプトが wp-scripts
パッケージ内のコマンドを指しています。
"scripts": {
"build": "wp-scripts build",
"start": "wp-scripts start"
},
これらのスクリプトは npm run build
または npm run start
で実行されます。
npm run build
は1度実行すると「production ビルド」(製品ビルド) を作成します。コードを圧縮しダウンロード時間を短くしますが、このためにブラウザツールを使用してコードを読むことが難しくなります。最終の配布用としては有用ですが開発では適しません。
npm run start
を使用すると「development ビルド」(開発ビルド) が作成されます。コードは圧縮されないため、ブラウザツールを使用しても読みやすく、source maps でデバッグも容易になります。さらに development ビルドは watch プロセスを開始します。待機してファイルの変更を監視し、ファイルが更新されるたびにリビルドします。変更ごとにコマンドを実行する必要はありません。
デフォルトではビルドスクリプトはビルドする JavaScript ファイルとして src/index.js
を探し、ビルドしたファイルを build/index.js
に保存します。次のセクションではスクリプトの詳細を確認しますが、まず WordPress にロードされていることを確認しましょう。
スクリプトをロードするプラグイン
エディター内で動作するようビルドしたスクリプトをロードするには、WordPress に対してスクリプトのことを伝える必要があります。これは gutenpride.php
ファイル内の init アクションで行います。
function create_block_gutenpride_block_init() {
register_block_type( __DIR__ . '/build' );
}
add_action( 'init', 'create_block_gutenpride_block_init' );
register_block_type
関数は、これから作成するブロックを登録し、build/block.json
ファイルの editorScript
フィールドのメタデータで登録されたエディタースクリプトハンドルを指定します。エディターがブロックをロードすると、このスクリプトをロードします。ソースメタデータファイル src/block.json
はプロセス中にコピーされます。
{
"$schema": "https://schemas.wp.org/trunk/block.json",
"apiVersion": 3,
"name": "create-block/gutenpride",
"version": "0.1.0",
"title": "Gutenpride",
"category": "widgets",
"icon": "smiley",
"description": "Example static block scaffolded with Create Block tool.",
"supports": {
"html": false
},
"textdomain": "gutenpride",
"editorScript": "file:./index.js",
"editorStyle": "file:./index.css",
"style": "file:./style-index.css"
}
ブロックメタデータで提供される editorScript
に対して、ビルドプロセスは2つ目のアセットファイル build/index.asset.php
を作成します。ファイルには依存性とタイムスタンプに基づくファイルバージョンのリストが含まれています。
内部で使用される wp_register_script
は「ハンドル」と呼ばれる名前を登録し、その名前をスクリプトファイルに関連付けます。スクリプトが、他のライブラリのインクルードを必要とする場合、依存性を使用してこれを指定します。またバージョンを指定すると、ファイルが更新された場合にブラウザがリロードします。
wp_set_script_translations
関数は WordPress に、もし存在するならスクリプトの翻訳をロードするよう伝えます。詳細については翻訳と国際化を参照してください。
すべてを終えたら新しい投稿を作成してエディターを開始し、インサーターにブロックが追加されていることを確認してください。検索には /
を使うか、[+] のボックスをクリックして「Gutenpride」を検索し、ブロックを見つけてください。
トラブルシューティング
Web コンソールの使い方を学び、親しみましょう。Web コンソールでは JavaScript のエラーを表示したり、JavaScript のスニペットをテストできます。Firefox 開発ツールドキュメントを参照してください。
FireFox で開発ツールを開くにはメニューの「Web 開発」>「開発ツールを表示」を選択してください。Chrome では「その他のツール」>「デベロッパーツール」です。両方のブラウザともキーボードショートカットは Windows では Ctrl+Shift+I、Mac では Cmd+Shift+I です。Windows や Linux であれば F12 キーでも開きます。ログを参照するには「コンソール」をクリックしてください。
npm run start
を実行してください。watch プロセスが始まり、自動リビルドが行われます。src/index.js
ファイルを更新するとビルドが始まります。ブロックエディターをリロードすると変更が反映されます。
詳細についてはブロックエディターハンドブックの JavaScript 入門チュートリアルのビルドセクションを参照してください。
まとめ
この時点でプラグインを作成し有効化できました。@wordpress/scripts
への依存性を含む package.json
ではビルドとスクリプトの開始を定義しています。基本的なブロックが完成しエディターに追加できました。
次のセクション: ブロックの詳細