Gutenberg ブロック開発の基本

目的

手を動かしながら、ブロック開発の流れを理解する。
ブロック開発の用語を知る。

本記事をもとに社内勉強会を行いました。その際の動画アーカイブもご参考ください。

開発環境

Docker
NodeJS（NPM）

ブロックを作っていく

例として、アラートブロックを作っていきます。
画像のように、サイドバーからブロックの背景色を切り替えることができます。

ボイラープレートを作成

下のコマンドで、ブロックの雛形ができます。

$ npx @wordpress/create-block alert-block

wp-envを追加

WordPressの開発環境を立ち上げられるように、wp-env を追加します。

$ cd alert-block
$ npm install @wordpress/env --save-dev

package.jsonを修正

package.jsonを編集します。npm-scriptsのstartを "wp-env start && open http://localhost:8888" に置き換えます。

これで、npm startをするだけで、http://localhost:8888 で WordPressが立ち上がります。（username:admin、password:password）で管理画面にログインできます

    "scripts": {
        "start": "wp-env start && open http://localhost:8888",
        "stop": "wp-env stop",
        "destroy": "wp-env destroy",
        ...中略...,
    },

実はしれっと、stopとdestroyも追加しています。詳しくはwp-envのドキュメントを読んでください。

ブロックを登録

作成したファイルのsrc/index.jsを開くと、registerBlockTypeと書いてあります。ここでブロックを登録しています。

registerBlockType( 'create-block/alert-block', {
    apiVersion: 2,
    edit: Edit,
    save,
} );

ブロックの設定

apiVersion:2からはブロックの設定は、block.jsonで出来るようになりました。
block.jsonを開くと以下のようになっています。

{
    "apiVersion": 2,
    "name": "create-block/alert-block",
    "title": "Alert Block",
    "category": "widgets",
    "icon": "smiley",
    "description": "Example block written with ESNext standard and JSX support – build step required.",
    "supports": {
        "html": false
    },
    "textdomain": "alert-block",
    "editorScript": "file:./build/index.js",
    "editorStyle": "file:./build/index.css",
    "style": "file:./build/style-index.css"
}

色んな設定項目がありますが、詳細は、公式ドキュメントを参照してください。

ポイント

色んな設定項目がありますが、ブロックの基本は、

保存値を定義するattributes
編集画面を作るeditに設定するコンポーネント
保存時のレンダリングをするsaveに設定するコンポーネント

です。

1. CSS追加

他のファイルを詳しく見ていく前にまずCSSを追加します。

style.scssの中身を以下に置き換えてください。

alert-xxx のクラスをブロックに追加することで、背景色が切り替わるようにCSSを書きます。

.wp-block-create-block-alert-block {
    padding: 2px;
    p {
        margin-top: 28px;
        margin-bottom: 28px;
    }
}
.alert {
    position: relative;
    padding: 1rem 1rem;
    margin-bottom: 1rem;
    border: 1px solid transparent;
    border-radius: .25rem;
}
.alert-success {
    color: #0f5132;
    background-color: #d1e7dd;
    border-color: #badbcc;
}
.alert-info {
    color: #055160;
    background-color: #cff4fc;
    border-color: #b6effb;
}
.alert-warning {
    color: #664d03;
    background-color: #fff3cd;
    border-color: #ffecb5;
}
.alert-danger {
    color: #842029;
    background-color: #f8d7da;
    border-color: #f5c2c7;
}

ちなみにCSSは二種類含まれていますが、違いは以下です。

editor.scss（block.jsonのeditorStyleで指定したCSS）：編集画面のみに適用される
style.scss（block.jsonのstyleで指定したCSS）：編集画面、フロントエンドどちらにも適用される

2. attributes

保存値のスキーマを定義します。

下の属性はそれぞれの値のスキーマを定義しています。

style：ブロックの背景色を指定するクラス。
content: ブロックに入力したテキスト。

block.json に以下のように、attributesを追加します。

{
    "apiVersion": 2,
    ...中略...
    "attributes": {
        "style": {
            "type": "string",
            "default": "info"
        },
        "content": {
            "type": "string",
            "source": "html",
            "selector": "p"
        }
    }
}

詳しくは公式ドキュメントを参照。

3. edit

編集画面を作成するコンポーネントです。
このコンポーネント内でreturnする要素が編集画面に表示されます。

edit.jsを以下の内容に置き換えて下さい。

import { __ } from '@wordpress/i18n';
import { PanelBody, SelectControl } from '@wordpress/components';
import {
    InspectorControls,
    RichText,
    useBlockProps,
} from '@wordpress/block-editor';

export default function AlertEdit({ attributes, setAttributes }) {
    const { style, content } = attributes;

    const blockProps = useBlockProps({
        className: `alert alert-${style}`,
    });

    return (
        <>
            <InspectorControls>
                <PanelBody title={__('Style Settings', 'alert-block')}>
                    <SelectControl
                        value={style}
                        onChange={(value) => setAttributes({ style: value })}
                        options={[
                            {
                                label: __('Success', 'alert-block'),
                                value: 'success',
                            },
                            { label: __('Info', 'alert-block'), value: 'info' },
                            {
                                label: __('Warning', 'alert-block'),
                                value: 'warning',
                            },
                            {
                                label: __('Danger', 'alert-block'),
                                value: 'danger',
                            },
                        ]}
                    />
                </PanelBody>
            </InspectorControls>
            <div {...blockProps}>
                <RichText
                    tagName="p"
                    onChange={(value) => setAttributes({ content: value })}
                    value={content}
                />
            </div>
        </>
    );
}

4. save

保存時に呼ばれるコンポーネントです。
save.jsを以下の内容に置き換えて下さい。

import { RichText, useBlockProps } from '@wordpress/block-editor';

export default function save({ attributes }) {
    const { style, content } = attributes;

    return (
        <div {...useBlockProps.save({ className: `alert alert-${style}` })}>
            <RichText.Content tagName={'p'} value={content} />
        </div>
    );
}

これで、$ npm run buildすると、インサーターにアラートブロックが表示されます。
おつかれさまでした!

まとめ

チュートリアルで見たように、ブロック開発はの流れをまとめると、

attributesでデータスキーマを決め
editでUIを作成しsetAttributesで値を保存。
saveに保存時のコンポーネントを設定する。

になります。

その他

もっとリッチなブロックを作ろうとすると、その他に色々必要になってきます。
その際に役立つリソースや概念を紹介します。

BlockEditorの各UIの名称

https://developer.wordpress.org/block-editor/より引用

インサーター（Block Inserter）
編集エリア（Block editor content area）
サイドバー（Settings Sidebar）

サイドバーやツールバーをカスタムする時

編集画面のサイドバーやツールバーを作るためのコンポーネントがあります。

BlockControls（ツールバーに要素を追加）
InspectorControls（サイドバーに要素を追加）

公式ドキュメント

WordPressが用意しているコンポーネント

文字を入力するためのRichTextや、プルダウン形式のUIを作るSelectControlなどWordPressは様々なコンポーネントをデフォルトで用意してくれています。

何か新しいUIを追加したくなった時は、まずコンポーネントリファレンスか、StoryBookを探すのがオススメです。

サンプルコード

今回作成したブロックのサンプルコードはこちらに上げてあるので、参考にしてみて下さい。

https://github.com/vektor-inc/alert-block-tutorial

この記事を書いた人

大橋直記

和歌山在住のWordPress Plugin Developer、ベクトルでは主にGutenbergのカスタムブロックプラグインの開発を担当しています。

Core Contributor(5.1)

フルサイト編集対応ブロックテーマ

WordPress テーマ X-T9 は、WordPress 5.9 から実装されたフルサイト編集機能に対応した「ブロックテーマ」と呼ばれる新しい形式のテーマです。
ヘッダーやフッターなど、今までのテーマではカスタマイズが難しかったエリアもノーコードで簡単・柔軟にカスタマイズする事ができます。

今すぐチェック

パターンを使って

よりクオリティの高いサイトに

パターンとは、WordPressのブロックを組み合わせて作ったデザインテンプレートのようなもの。プロのデザイナーが制作したパターンを300以上公開中！コピペしながら高品質なサイトを簡単に作れます。

VK パターンライブラリを今すぐチェック

ブロックエディターで

ABテストを

自由に作成できる VK AB Testing

VK AB Testing は、ABテストを実施するための WordPress 用プラグインです。ブロックエディターでテストパターンを自由に作成でき、ランダム表示とクリック計測が可能です。Webサイトや広告などの施策の改善にぜひご活用ください。

VK AB Testing を詳しく見る

AB テストでクリック率 &
売上アップ！