目的

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

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

開発環境

  • Docker
  • NodeJS(NPM)

ブロックを作っていく

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

スクリーンショット 2021-03-18 10.45.04.png

ボイラープレートを作成

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

$ 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",
        ...中略...,
    },

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

スクリーンショット 2021-03-18 10.52.03.png

ブロックを登録

作成したファイルの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すると、インサーターにアラートブロックが表示されます。
おつかれさまでした!

まとめ

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

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

になります。

その他

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

BlockEditorの各UIの名称

quick-view-of-the-block-editor.png

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

  1. インサーター(Block Inserter)
  2. 編集エリア(Block editor content area)
  3. サイドバー(Settings Sidebar)

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

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

  • BlockControls(ツールバーに要素を追加)
  • InspectorControls(サイドバーに要素を追加)

公式ドキュメント

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

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

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

スクリーンショット 2021-03-18 11.36.12.png

サンプルコード

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

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

Follow me!

初心者でも簡単!無料WordPressテーマ

100%GPL / 商用利用可能

Lightning は WordPress公式ディレクトリに登録されているカスタマイズ性の高いテーマです。
デモデータも配布されているので、ビジネスサイトの雛形が数分でセットアップできます。

VWSオンラインコミュニティー

オンラインコミュニティでは、より良いテーマ・プラグイン開発のため、機能改善・追加要望などの書き込み大歓迎です!
ユーザー同士の交流や意見交換の場としてもお気軽にご参加ください。
※質問はフォーラムでのみ対応となります。