@wordpress/create-block

Create Block は公式でサポートされるブロック作成方法です。WordPress プラグインを使用してブロックを登録します。Create Block はモダンなビルド設定を提供します。構成は必要ありません。PHP、JS、CSS コード、その他、プロジェクトの開始に必要なすべてのファイルを生成します。

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

説明

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

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

クイックスタート

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

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

(node version 12.0.0 以上、npm version 6.9.0 以上が必要です)

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

使用方法

次のコマンドはブロックを登録する PHP、JS、CSS コードを生成します。

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

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

オプション:

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

サンプル:

  1. 対話モード – プロジェクト名を指定しなければスクリプトは対話モードで動作します。コードが生成される前に、もっとも重要なオプションのいくつかをカスタマイズする機会が得られます。
$ npx @wordpress/create-block
  1. ES5 テンプレート – ESNext や JSX サポートを有効化するビルド手順 (npm start) を実行したくない場合は ES5 テンプレートを選択できます。
$ npm init @wordpress/block --template es5
  1. ヘルプ – 使用例の情報を出力する場合は npx が必要です。
$ npx @wordpress/create-block --help

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

使用可能なコマンド

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

$ npm start

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

$ npm run build

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

$ npm run format

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

$ npm run lint:css

CSS ファイルを lint 詳細

$ npm run lint:js

JavaScript ファイルを lint 詳細

$ npm run packages-update

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

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

外部テンプレート

バージョン 0.19.0 からは npm でホストされた外部テンプレートを使用できます。パッケージはブロックのひな形生成プロセスで使用される .mustache ファイルを含む必要があります。

テンプレート構成

構成オブジェクトを返すパッケージのメインファイル (デフォルトでは index.js) が必須です。少なくとも templatesPath フィールドを含む必要があります。

templatesPath

テンプレートファイルの場所を示すパスを指定する必須フィールド。ネストしたフォルダーもサポートされます。.mustache 拡張子のないすべてのファイルは無視されます。

例:

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

module.exports = {
    templatesPath: join( __dirname, 'templates' ),
};

assetsPath

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

例:

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

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

defaultValues

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

例:

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

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

  • apiVersion (デフォルト: 2) – 参照 https://make.wordpress.org/core/2020/11/18/block-api-version-2/
  • slug (デフォルトなし)
  • namespace (デフォルト: 'create-block')
  • title (デフォルトなし) – ブロックの表示タイトル
  • description (デフォルトなし) – ブロックの短い説明
  • dashicon (デフォルトなし) – ブロックの識別を助けるアイコンプロパティ。参照 https://developer.wordpress.org/resource/dashicons/
  • category (デフォルト: 'widgets') – ユーザーの参照と検索のため、ブロックはカテゴリーにグループ分けされる。コアで提供されるカテゴリーは、textmediadesignwidgetsthemeembed
  • author (デフォルト: 'The WordPress Contributors')
  • license (デフォルト: 'GPL-2.0-or-later')
  • licenseURI (デフォルト: 'https://www.gnu.org/licenses/gpl-2.0.html')
  • version (デフォルト: '0.1.0')
  • wpScripts (デフォルト: true)
  • wpEnv (default: false)
  • npmDependencies (デフォルト: []) – npm install でプロジェクトにインストールされるリモート npm パッケージのリスト
  • editorScript (デフォルト: 'file:./build/index.js')
  • editorStyle (デフォルト: 'file:./build/index.css')
  • style (デフォルト: 'file:./build/style-index.css')

WP-CLI

もう1つの開発者をラクにしてくれる方法が WP-CLI です。WP-CLI は WordPress に対する多くの操作をコマンドラインから実行できますが、その中の1つ wp scaffold block はこのツール、特に ES5 テンプレートの開始ラインとして使用されました。

原文

Code is Poetry.

最終更新日: