【WordPress】registerBlockTypeの書き方についてのメモ

WordPressのブロック登録について、registerBlockType の記述方法が公式のドキュメントだけでは覚えられなかったのでメモ。

ブロック登録 registerBlockType

registerBlockType( 'namespace/block-name', {});
  • namespaceはプラグイン・テーマ名
  • block-nameは各ブロックの名前

ブロック構成

上記の {} の中に、key : value の組み合わせで入れていく

  • title:ブロック名
  • description(任意):ブロックの説明文
  • category:<後述>ブロックが属するカテゴリ
  • icon(任意):<後述>ブロックのアイコン
  • keywords(任意):ブロック検索に使えるキーワード
  • styles(任意):<後述>ブロックにスタイルのバリエーションをつけるための設定
  • attributes(任意):<後述>編集可能なブロックを使うときには必ず使う様々な設定
  • example(任意):ブロック選択時に表示するプレビューの設定
  • transform(任意):ブロック変換の変換元・変換先の設定
  • parent(任意):<後述>入れ子の親になれるブロックを指定
  • support(任意):<後述>ブロックの機能(配置・html編集モードなど)のON/OFF設定

カテゴリー category

どのブロックカテゴリーに登録するかを選ぶ。

category : 'common',
  • common:一般ブロック
  • formatting:フォーマット
  • layout:レイアウト要素
  • widgets:ウィジェット
  • embed:埋め込み

また、カスタムブロックカテゴリーを作成すれば、そこに登録させることもできる。

 

アイコン icon

ブロックのアイコン。Dashicon か SVGを設定できる。実は色設定などもできる。

icon: 'book-alt',
//または
icon: {
    background: '#7e70af',
    foreground: '#fff',
    src: <svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path fill="none" d="M0 0h24v24H0V0z" /><path d="M19 13H5v-2h14v2z" /></svg>,
} ,

Dashicons

 

スタイル styles

ブロックにスタイルのバリエーションを持たせるのに使う。
nameの部分がclass名としてブロックの囲み要素につくので、それを使ってCSSでスタイリングする。

styles: [
   { name: 'default', label: '角丸', isDefault: true },
   { name: 'outline', label: '枠線' },
],
ブロックのスタイルバリエーション

 

属性 attributes

属性(attributes)はeditやsaveメソッドにアクセスさせるために必要なもの。
つまり編集可能なブロックで、ブロックの内容を変更・保存するために必要なもの。

attributes: {
    content: {
        type: 'string',
        source: 'attribute',
        selector: 'img',
        attribute: 'src',
    }
}
  • 属性名: 好きな名前(上記ではcontent)
  • type: 値の種類、文字列なら’string’。数値なら’number’など
  • source: 変更・保存するもの。text, html, attribute, query(type:arrayの時に使う),meta(記事のメタ属性)
  • selector: htmlタグやclass名。sourceがhtmlの時に使う。
  • attribute: 属性(alt とか srcとか)名。sourceがattributeの時に使う。

※後述するsupport でalign(配置)を使えるようにすると、align属性が使えるようになる。

attributes: {
    align: {
        type: 'string',
        default: 'right'
    },
}

 

親 parent

特定のブロックの中でしか使ってほしくないブロックの時に設定する。(スライドショーブロックの中に、スライド画像ブロックを作る ような)

parent: [ 'core/columns' ],

[] の中に記述したブロックの中でしか選択肢に出てこなくなる。

 

サポート support

ブロックがどの機能をサポートするかを設定する

align(配置)

初期値はfalse。trueとするか、[] で left, center , right, wide, full から選ぶ。デフォルト値を設定したいときは前述のattributesを使う

alignWide

初期値はtrue。ブロックに対して幅広の配置を有効にする設定。(テーマ側にadd_theme_support( 'align-wide’ )が無いと効果が無い)

anchor

初期値はfalse。ブロックに自由なid名(アンカーリンク用のアンカー)を設定できるようにする設定。

anchor

customClassName

初期値はtrue。ブロックに自由なclass名を設定できるようにする。

customClassName

className

初期値はtrue。ブロックに .wp-block-***(ブロック名) というclassをつける。

出力されるHTML上はすごい状態になるが、他のプラグインのブロックなどとのブロック名が混ざる(CSSが混ざる)のを避けるために有用。

html

初期値はtrue。HTMLとして編集 の機能を使えるようにする。

HTMLとして編集

inserter

初期値はtrue。インサーター(+ボタンで選べるブロックの一覧)に表示させるかどうか。

multiple

初期値はtrue。1つの投稿につき1回しか使わなせないときは、falseにする。(標準の「続きを読む」ブロックは非複数のブロック)

reusable

初期値はtrue。再利用可能なブロックに変換してほしくないときは、falseにする。

 

 

参考文献

Block Registration

【Gutenberg カスタムブロック】registerBlockTypeのattributes設定(WordPress)