(旧)WordPress プラグイン

(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
 */

プラグインがロードでき、動作することを確認します。

(3A) Local や他の環境であれば WordPress サイトが起動していることを確認してください。

または

(3B) wp-env を使用する場合は、まず開発環境のセットアップ を参照してください。次に gutenpride ディレクトリ內部から以下を実行します。

wp-env start

ローカルで WordPress を起動し、カレントディレクトリをプラグインディレクトリとして使用します。ブラウザから http://localhost:8888/wp-admin/ にアクセスしてログインします。デフォルトユーザー名は「admin」、パスワードは「password」です。

生成されたプラグインは WordPress 管理画面の「プラグイン」ページのリストに表示されます。プラグインを有効化してください。

WordPress プラグイン作成の詳細については Plugin Basics を参照してください。またプラグインヘッダーのフィールドの説明、追加可能なフィールドについては Plugin Header requirements を参照してください。

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 ではビルドとスクリプトの開始を定義しています。基本的なブロックが完成しエディターに追加できました。

次のセクション: ブロックの詳細

原文

最終更新日: 2024年1月20日