基本的なブロックの作成

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

概要

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

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

Top ↑

はじめる前に

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

ブロックはプラグインを使用して WordPress に追加されます。そのため、以下が必要です。

  • WordPress 開発環境。セットアップガイド 参照
  • JSX の例を使用する場合、JavaScript ビルドツール (node/npm)

Top ↑

ステップバイステップガイド

Top ↑

ステップ 1: block.json の構成

静的ブロックの機能は 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 ファイルを作成します。

JSX

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

Plain

{
	"apiVersion": 2,
	"title": "Example: Basic",
	"name": "gutenberg-examples/example-01-basic",
	"category": "layout",
	"icon": "universal-access-alt",
	"editorScript": "file:./block.js"
}

Top ↑

ステップ 2: プラグインでのブロックの登録

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' );

Top ↑

ステップ 3: ブロックの edit 関数と save 関数

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

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

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

JSX

次のコードを 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>;
	},
} );

Plain

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

( function ( blocks, element ) {
	var el = element.createElement;

	blocks.registerBlockType( 'gutenberg-examples/example-01-basic', {
		edit: function () {
			return el( 'p', {}, 'Hello World (from the editor).' );
		},
		save: function () {
			return el( 'p', {}, 'Hola mundo (from the frontend).' );
		},
	} );
} )( window.wp.blocks, window.wp.element );

Top ↑

ステップ4: ビルド、または依存関係の追加

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

JSX

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

npm run build

Plain

Create the asset file to load the dependencies for the scripts. The name of this file should be the name of the js file then .asset.php. For this example, create block.asset.php with the following:

スクリプトの依存関係を読み込むアセットファイルを作成します。このファイルの名前は、js ファイルの名前に.asset.php を加えたものにする必要があります。この例では、block.asset.php を以下のように作成します。

<?php return
	array( 'dependencies' =>
		array(
			'wp-blocks',
			'wp-element',
			'wp-polyfill'
		),
		'version' => '0.1'
	);

Top ↑

ステップ5: 確認

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

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

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

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

Top ↑

まとめ

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

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

Top ↑

追加の情報

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

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

Top ↑

リソース

原文

最終更新日: