↓の続き。今回はリファレンスをざっくり。
Gutenberg Handbook 読書メモ (1)
Gutenberg Handbook 読書メモ (2)
Attributes
https://wordpress.org/gutenberg/handbook/reference/attributes/
ソース(source)
属性のsource
はブロックの属性の値の取得方法を定義する。
それぞれのsource
は、第1引数にセレクタを取る(オプショナル)。セレクタが指定されると、source
は、ブロック内で対応する要素を取得する。
内部では、source
はhpqライブラリのスーパーセットとなっている。
attribute
attribute
を使うと、マークアップから属性を取得できる。
以下の例では、img
タグからsrc
属性を抜き出している。
{
url: {
source: 'attribute',
selector: 'img',
attribute: 'src',
}
}
// { "url": "https://lorempixel.com/1200/800/" }
text
text
を使うと、マークアップの内側のテキストを取得できる。
{
content: {
source: 'text',
selector: 'figcaption',
}
}
// { "content": "The inner text of the figcaption element" }
html
html
を使うとマークアップの内側のHTMLを取得できる。
{
content: {
source: 'html',
selector: 'figcaption',
}
}
// { "content": "The inner text of the <strong>figcaption</strong> element" }
children
children
を使うとマッチした要素の子ノードを取得できる。Editable
コンポーネントとの組み合わせでよく使われる。
{
content: {
source: 'children',
selector: 'p'
}
}
// {
// "content": [
// "Vestibulum eu ",
// { "type": "strong", "children": "tortor" },
// " vel urna."
// ]
// }
query
query
を使うと、複雑なセレクタでマークアップから値を取得できる。
以下では、それぞれのimg
要素からurl
とalt
属性を抜き出している。
{
images: {
source: 'query'
selector: 'img',
query: {
url: { source: 'attribute', attribute: 'src' },
alt: { source: 'attribute', attribute: 'alt' },
}
}
}
// {
// "images": [
// { "url": "https://lorempixel.com/1200/800/", "alt": "large image" },
// { "url": "https://lorempixel.com/50/50/", "alt": "small image" }
// ]
// }
Meta
記事のメタデータ(post meta)から属性を取得することもできる。
attributes: {
author: {
type: 'string',
source: 'meta',
meta: 'author'
},
},
このようにすると、ブロックからメタ属性に対して読み書きできるようになる。
edit( { attributes, setAttributes } ) {
function onChange( event ) {
setAttributes( { author: event.target.value } );
}
return <input value={ attributes.author } onChange={ onChange } />;
},
検討事項
デフォルトでは、メタフィールドは記事のオブジェクトのメタデータからは除外されている。この制限は、フィールドを明示的に可視化することで回避可能である。
function gutenberg_my_block_init() {
register_meta( 'post', 'author', array(
'show_in_rest' => true,
) );
}
add_action( 'init', 'gutenberg_my_block_init' );
さらに、WordPressは以下のようなデフォルト設定になっている点に注意が必要。
- メタデータをユニークなものとしては扱わず、値の配列を返す
- データを文字列として扱う
どちらの振る舞いも望ましくないなら、register_meta
関数の呼び出しを以下のようにすることで、補うことができる。
function gutenberg_my_block_init() {
register_meta( 'post', 'author_count', array(
'show_in_rest' => true,
'single' => true,
'type' => 'integer',
) );
}
add_action( 'init', 'gutenberg_my_block_init' );
最後に、属性に値を設定する際はデータの型に注意が必要である。
function onChange( event ) {
props.setAttributes( { authorCount: Number( event.target.value ) } );
}
Blocks support by themes
https://wordpress.org/gutenberg/handbook/reference/theme-support/
基本的に、ブロックのスタイルのカスタマイズはテーマ側のCSSで行うことができる。しかし、一部の機能はテーマ側での明示的な有効化(オプトイン)が必要になる。
function mytheme_setup_theme_supported_features() {
add_theme_support( 'gutenberg', array(
'wide-images' => true,
) );
}
add_action( 'after_setup_theme', 'mytheme_setup_theme_supported_features' );
Meta Boxes
https://wordpress.org/gutenberg/handbook/reference/meta-box/
※色々書いているけど一旦飛ばす
Glossary
https://wordpress.org/gutenberg/handbook/reference/glossary/
用語集
- 属性ソース(Attribute sources): ブロックの属性の形を記述するオブジェクト
- 属性(Attributes): ブロックの現在の状態を表現するオブジェクト
- ブロック(Block): マークアップの単位を表す抽象的な用語。ブロックは組み合わせて使用され、Webページのコンテンツやレイアウトを構成する。
- ブロックの名前(Block name): ブロック型のユニークな識別子
- ブロック型(Block type): ブロックの振る舞いの定義
- 動的ブロック(Dynamic block): 保存時にコンテンツが確定せず、記事が表示されるタイミングで描画されるブロック
- Editable: リッチエディタ機能を提供するコンポーネント
- Inspector: ブロック設定用のUIコンポーネント
- 記事の設定(Post settings): 記事編集画面のサイドバーのこと
- シリアライゼーション(Serialization): 記事の保存時にブロックの属性オブジェクトをHTMLマークアップに変換するプロセス
- 静的ブロック(Static Block): 記事の保存時に内容が確定するブロック
- TinyMCE: リッチエディタ(WYSIWYGエディタ)
- ツールバー(Toolbar): ブロックの上に表示される一連のボタンのこと
Design Priciples
https://wordpress.org/gutenberg/handbook/reference/design-principles/
抽象的な話なので割愛
History
https://wordpress.org/gutenberg/handbook/reference/history/
内容がないので割愛
Coding Guidelines
https://wordpress.org/gutenberg/handbook/reference/coding-guidelines/
Gutenbergのコードに関することなので割愛。
Testing Overview
https://wordpress.org/gutenberg/handbook/reference/testing-overview/
JSはnpm test
でテストが実行できる。
Jestのスナップショットテストを使っていて、スナップショットテストを使う際のベストプラクティス等について言及してある。
FAQ
https://wordpress.org/gutenberg/handbook/reference/faq/
いずれ公式で訳されるはず。