Gutenberg Handbook 読書メモ (1)

WordPressのエディタ画面のカスタマイズのため、新エディタ「Gutenberg」のドキュメントを読んでます。覚え書きを書き残しておきます。

Introduction

https://wordpress.org/gutenberg/handbook/

  • “Gutenberg”とは、新しいWordPressエディタのコードネーム
  • リッチなレイアウトを誰でも簡単に作れるようにするのが目的
  • “Block” という概念を導入することで、ショートコードやカスタムHTMLを不要にする

The Language of Gutenberg

The Language of Gutenberg

  • Gutenbergの中心にあるのは「ブロック」の概念である
  • Gutenbergでは、記事(post)はブロックの集合からなる
  • ブロックは活版印刷における活字のようなもので、記事の編集時には必要だが、最終的に出力される記事には含まれない

ブロックはHTMLよりも高い次元にある

  • ブロックはHTMLを出力するための機能だが、ユーザが編集を助けるための機能も伴っている
  • ブロックは最終的なHTMLを出力するために必要な情報を全て保持している

2つのpost

  • Gutenbergの記事(post)はブロックのことを知っている(block-aware)
  • Gutenbergのpostは、post_contentそのものではない

ブロックのツリー

  • 実行時に、ブロックはメモリ上に保持される
  • GutenbergのpostはHTMLではなく、オブジェクトのツリーである
  • ルートノードは必要とせず、ノードのコレクションである

シリアライゼーションとHTMLコメントの目的

  • Gutenbergのデータモデルは、記事の編集中のメモリに保持されるが、レンダリング結果からは痕跡が消える
  • Gutenbergはデータモデルをpost_contentに保存できるようシリアライズする
  • シリアライズの過程では、ツリーをHTMLに変換する。その際、HTMLコメントをブロックの境界として用いる
  • 編集時には、HTMLコメントからツリーを再構築する
  • 仮に、Gutenbergに対応していないテーマを使用したとしても、最低限のコンテンツは描画されるようになっている(動的な要素は描画されない)

デリミタと式文法の構文解析

  • HTMLコメントでは、二重のハイフン(–)を除いて、文法上の制約は無い
  • ブロックの属性はJSONリテラルとしてコメントに埋め込まれる

シリアライズされたブロックの中身

ブロックがwp_contentに保存されると、その属性はコメント内に保存される

サーバサイドでレンダリングされる動的なブロックは以下のようになる:

Gutenbergのライフサイクル

要約すると、Gutenbergの記事を編集する手順は、文書を保存してツリーを生成するところから始まる。最終的に、ブロックはpost_contentに保存される。編集中、全ての操作はブロックのツリーに変更を加える。

Extensibility

Extensibility

ブロックの作成

ブロックAPIを使うことで、静的なブロック、サーバサイドでレンダリングされる動的ブロック、post_metaにデータを保存するブロックなどを作成できる。

※メモ:クライアントサイドでの動的なレンダリングはできない???

静的ブロックは以下のように作成できる。

ブロックの削除

ブラックリストの使用

以下のようなJavaScriptコードを書き、

エディタ内で読み込むようにすればよい。

ホワイトリストの使用

特定のブロック以外を無効化したい場合、以下のように書く。

inserterからブロックを隠す

inserterに表示するブロックはサーバサイドでフィルタリングできる。

ブロックの編集(実験的)

既存のブロックの挙動を変更するため、Gutenbergはフィルターを提供している:

  • registerBlockType: ブロック設定のフィルタリング
  • getSaveContent.extraProps: save関数でWP elementを返す全てのブロックに適用されるフィルタ。ブロックにpropsを追加する場合に使用する
  • BlockEdit: ブロックのedit関数で受け取ったWP elementを編集するのに使う

全てのブロックにデフォルトで背景を設定している。

エディターUIの拡張(SlotとFill)

Coming soon. とのこと(2017/12/04現在)

Block API

Block API

プラグインやテーマは、エディタに対する独自の機能や追加の機能をブロックとして登録できる

ブロック型の登録

全てのブロックは、ブロック型定義の登録を行う必要がある。これには、registerBlockType関数を使用する。

ブロック名

新しいブロック型の登録にはregisterBlockType関数を使用する。この関数は、ブロック名と設定オブジェクトを引数に取る。

ブロック名は namespace/block-name という構造になっていなければならない。namespaceはプラグインやテーマの名前である。

注意:ブロック名には小文字のアルファベットと数字、ダッシュ(-)記号のみを含み、最初の1文字目はアルファベットでなければならない

ブロック設定オブジェクトの代表的な設定は下記の通り

  • title(必須): ブロックのinserter上に表示する名前
  • category(必須): inserter上の分類。common formatting layout widgets embedのいずれか
  • icon: ブロックのアイコン WordPressのDashiconsの名前を指定するか、独自のsvg要素を指定する
  • keywords: 検索時のキーワード
  • attributes: ブロックが使用する構造化されたデータ
  • transforms: 説明なし。WIPらしい
  • useOnce: 記事ごとに1個だけしか使えない場合はtrueにする
  • supports: サポート機能を拡張する設定
    • anchor(default: false): ページ内リンクできるようにする
    • customClassName(default: true): ブロックのラッパー要素にブロック独自のクラス名をつける
    • className(default: true): .wp-block-bour-block-name という形式のクラスをつけるか
  • supportHTML(default: true): HTMLモードで編集可能か

Edit and Save

Edit and Save

editsave関数によって、ブロックがどのようにレンダリングされるか定義できる。
※以下のサンプルコードではESNextとJSXを使用している。

Edit

edit 関数はエディタを使用している際のブロックの構造を定義する。

この関数は、引数のオブジェクトから以下のプロパティを受け取ることができる。

attributes

利用可能な属性と、それに対応した値。以下のサンプルでは、contentという属性を定義して、ブロックのコンテンツとして使用している。

className

ラッパー要素のクラス名。これらはsave関数によって自動的に追加されるが、editの段階では自動的には追加されない。クラス名を明示的に受け取るにはclassNameプロパティを使用する。

focus

ブロックがフォーカスされている状態か否かを判定する。

setAttributes

ユーザの操作に応じて属性の値を更新できる。

setFocus

ToDoらしい

Save

save関数は、最終的なマークアップを決定する。これはGutenbergによってシリアライズされて、post_contentに保存される。

save関数はnullを返すこともできる。この場合、属性のみがシリアライズされ、サーバサイドでHTMLの描画処理が行われる(これを動的(dynamic)ブロックと呼ぶらしい)。

save関数もプロパティを受け取ることができる。

attributes

editと同様の使い方。保存時にコンテンツが確定し、サーバサイドでの描画が必要ない静的ブロックでは、attributesの値をsave関数でマークアップに埋め込めば良い。

「Gutenberg Handbook 読書メモ (1)」への1件のフィードバック

コメントを残す