@wordpress/create-block

Create Block は、ブロックの WordPress プラグインのひな形を作成する、公式サポートツールです。PHP、JS、CSS コード、その他、プロジェクトの開始に必要なすべてのファイルを生成します。構成不要で、モダンなビルド設定を統合します。

Create Block は create-react-app から多大な影響を受けました。称賛を @gaearon、Facebook チーム全員、そして React コミュニティに。

WordPress ブロックエディターの基本的な要素は「ブロック」です。ブロックは、プラグインが機能を登録し、エディターの機能を拡張する際に使用するメインの手段です。

Block API の詳細については ブロックエディターハンドブック を参照してください。

slug を指定するだけで作成できます。slug は、ひな形プラグインファイルの保管場所と、内部のブロック名になります。

$ npx @wordpress/create-block todo-list
$ cd todo-list
$ npm start

(node version 14.0.0 以上、npm version 6.14.4 以上が必要です)

手動でのインストールが必要な WordPress プラグインを作成します。

次のコマンドは、WordPress プラグインでブロックを登録する PHP、JS、CSS コードのプロジェクトを生成します。

$ npx @wordpress/create-block [options] [slug]

[slug] はオプションです。指定するとクイックモードとなり、ブロックの slug として識別子、ひな形ファイルの出力先、WordPress プラグインの名前に使用されます。構成の残りは以下に挙げるオプションで上書きしない限り、すべてデフォルト値が設定されます。

オプション:

-V, --version                バージョン番号の出力
-t, --template <name>        プロジェクトテンプレートタイプ名。指定可能な値: "static" (デフォルト)、"es5"、外部 npm パッケージ名、ローカルディレクトリへのパス
--namespace <value>          ブロック名の内部名前空間
--title <value>              ブロックと WordPress プラグインの表示タイトル
--short-description <value>  ブロックと WordPress プラグインの短い説明
--category <name>            ブロックのカテゴリー名
--wp-scripts                 `@wordpress/scripts` パッケージとの統合を有効化
--no-wp-scripts              `@wordpress/scripts` パッケージとの統合を無効化
--wp-env                     `@wordpress/env` パッケージとの統合を有効化
-h, --help                   使用方法の出力

サンプル:

1. 対話モード – プロジェクト名を指定しなければスクリプトは対話モードで動作します。コードが生成される前に、もっとも重要なオプションのいくつかをカスタマイズする機会が得られます。

$ npx @wordpress/create-block

2. 外部 npm パッケージ – また、テンプレートとして外部 npm パッケージも選択できます。

$ npx @wordpress/create-block --template my-template-package

3. ローカルテンプレートディレクトリ – また、テンプレートとしてローカルディレクトリを取ることもできます。

$ npx @wordpress/create-block --template ./path/to/template-directory

4. ヘルプ – 使用例の情報を出力する場合は npx が必要です。

$ npx @wordpress/create-block --help

ブロックのひな形を生成する際、少なくとも slug 名、通常は theme 名や puglin 名のどちらかと関連する namespace を指定する必要があります。多くの場合ブロックは、テーマでなく、WordPress プラグインとペアにすることを推奨します。プラグインを使用していればテーマを変更されてもすべてのブロックが稼働するからです。

static テンプレート、または wpScripts フラグを有効化した他のプロジェクトテンプレートからブロックの作成を始めた場合、作成されたディレクトリの中で以下のコマンドを実行できます。

$ npm start

開発用のビルドを開始。詳細

$ npm run build

本番用にコードをビルド。詳細

$ npm run format

ファイルをフォーマット。詳細

$ npm run lint:css

CSS ファイルを lint。詳細

$ npm run lint:js

JavaScript ファイルを lint。詳細

$ npm run plugin-zip

WordPress プラグインの zip ファイルを作成。詳細.

$ npm run packages-update

WordPress パッケージを最新版に更新。詳細

注意: webpack や Babel や ESLint などのツールのインストールや構成は必要ありません。これらは裏側で自動的に構成されるため、ユーザーはコードに集中できます。

プロジェクトの設定の共有方法をお探しですか ? npmでホストされる、または、ローカルディレクトリに、外部プロジェクトテンプレートを作成できます。この npm パッケージは、カスタム.mustacheファイルを提供できます。これは、WordPress プラグイン または、ブロックのためのツールに含まれる、デフォルトのファイルを置き換えます。また、ひな形生成プロセス中に使用されるデフォルトの構成値を上書きできます。

構成オブジェクトを返すパッケージのメインファイル (デフォルトでは index.js) の提供は必須です。いくつかのオプションを使用して、ひな形生成プロセスをカスタマイズできます。

このオプションフィールドは、WordPressプラグインシェルに関連するファイルテンプレートを上書きできます。パスは拡張子が .mustache で終わるテンプレートファイルのある場所を指します (ネストしたフォルダもサポートされます)。設定されない場合、ツールは自身のテンプレートセットを使用します。

例:

const { join } = require( 'path' );

module.exports = {
	pluginTemplatesPath: join( __dirname, 'plugin-templates' ),
};

このオプションフィールドは、個々のブロックに関連するファイルテンプレートを上書きできます。パスは、拡張子が .mustache で終わるテンプレートファイルのある場所を指します (ネストしたフォルダもサポートされます)。設定されない場合、ツールは自身のテンプレートセットを使用します。

例:

const { join } = require( 'path' );

module.exports = {
	blockTemplatesPath: join( __dirname, 'block-templates' ),
};

この設定はテンプレートから雛形の生成時、WordPress プラグインが使用する画像やフォントなどの処理の必要のない静的なアセットを準備する場合に便利です。アセットのある場所を指すパスを指定します。アセットは生成されたプラグインの assets サブフォルダーにコピーされます。

例:

const { join } = require( 'path' );

module.exports = {
	assetsPath: join( __dirname, 'plugin-assets' ),
};

defaultValues フィールドを使用してデフォルトのテンプレート構成を上書きできます。

例:

module.exports = {
	defaultValues: {
		slug: 'my-fantastic-block',
		title: 'My fantastic block',
		dashicon: 'palmtree',
		version: '1.2.3',
	},
};

テンプレートファイルでは以下の構成可能変数が使用されます。テンプレートの作者は、ユーザーが指定しない場合に使用されるデフォルト値を変更できます。

プロジェクト:

• wpScripts (デフォルト: true) – @wordpress/scripts パッケージとの統合を有効可し、package.json に共通スクリプトを追加する。
• wpEnv (デフォルト: false) – @wordpress/env パッケージとの統合を有効可し、package.json に env スクリプトを追加する。
• customScripts (デフォルト: {}) – package.json に追加するカスタムスクリプトのリスト。デフォルトのスクリプトも上書きできる。
• npmDependencies (デフォルト: []) – wpScripts が有効な時、npm install でプロジェクトにインストールされるリモート npm パッケージのリスト
• npmDevDependencies (デフォルト: []) – wpScripts が有効な時、npm install --save-dev でプロジェクトにインストールされるリモート npm パッケージのリスト

プラグインヘッダーフィールド (詳細):

• pluginURI (デフォルトなし) – プラグインのホームページ
• version (デフォルト: '0.1.0') – プラグインの現行のバージョン番号
• author (デフォルト: 'The WordPress Contributors') – プラグイン作者の名前
• license (デフォルト: 'GPL-2.0-or-later') – プラグインのライセンスの短い名前
• licenseURI (デフォルト: 'https://www.gnu.org/licenses/gpl-2.0.html') – ライセンスの完全なテキストへのリンク
• domainPath (デフォルトなし) – 翻訳へのカスタムドメインパス。(詳細)
• updateURI: (デフォルトなし) – プラグインのカスタム更新 URI。(関連 dev note)

ブロックメタデータ (詳細):

• folderName (デフォルト: .) – block.json ファイル、および、blockTemplatesPath で設定したフォルダに含まれるブロックテンプレートから生成されたオプションのブロックファイルの場所
• $schema (デフォルト: https://schemas.wp.org/trunk/block.json) – ブロック妥当性検査 (validation) で使用されるスキーマの URL
• apiVersion (デフォルト: 2) – ブロック API バージョン (関連 dev note).
• slug (デフォルトなし) – ブロック名の識別に使用されるブロックスラッグ
• namespace (デフォルト: 'create-block') – ブロック名の内部名前空間
• title (デフォルトなし) – ブロックの表示タイトル
• description (デフォルトなし) – ブロックの短い説明
• dashicon (デフォルトなし) – ブロックの識別を助けるアイコンプロパティ。(利用可能な値)
• category (デフォルト: 'widgets') – ユーザーの参照と検索のため、ブロックはカテゴリーにグループ分けされる。コアで提供されるカテゴリーは、text、media、design、widgets、theme、embed
• attributes (デフォルトなし) – ブロック属性。(詳細).
• supports (デフォルトなし) – オプションのブロック拡張サポート機能。(詳細.
• editorScript (デフォルト: 'file:./index.js') – エディタースクリプト定義
• editorStyle (デフォルト: 'file:./index.css') – エディタースタイル定義
• style (デフォルト: 'file:./style-index.css') – フロントエンドとエディターのスタイル定義

これは、Gutenberg プロジェクトの一部である、個別パッケージです。このプロジェクトは、monorepo として構成されています。複数の自己完結型ソフトウェアパッケージで構成されており、それぞれが特定の目的を持ちます。この monorepo のパッケージは npm で公開され、WordPress や他のソフトウェアプロジェクトで利用されています。

このパッケージや Gutenberg 全体へのコントリビュートの詳細については、プロジェクトのメインのコントリビューターガイドを参照ください。

原文

最終更新日: 2022年8月13日