属性
タイプの妥当性検証
属性の必須フィールドは type
フィールドのみです。type
は属性の中に保存されるデータの型を表します。
type
フィールドに指定する値は以下でなければなりません。
- null
- boolean
- object
- array
- number
- string
- integer
詳細については WordPress REST API ドキュメント を参照してください。
一般的なソース
「属性ソース」は保存された投稿コンテンツからどのようにブロックの属性値を取り出すかを定義します。属性ソースは、保存済みのマークアップからブロックの JavaScript 表現をマップする方法を提供します。
属性ソースを指定しない場合、属性はブロックの コメントデリミッター に保存され、ロード時に読み出されます。
属性ソースオブジェクト内で指定するキーの名前は自由に付けられます。属性ソース定義の結果は各キーの値として割り当てられます。
selector
引数がない場合、ソース定義はブロックのルートノードに対して実行されます。selector
引数がある場合はブロック内に含まれる selector
で指定された要素に対して実行されます。
セレクターは HTML タグのほか、クラスや id 属性など照会できるものであれば何でも指定できます。以下の例を参照してください。
実装から見た場合、属性ソースは hpq が提供する機能の上位セットとなる小さなライブラリーです。HTML マークアップをパースし、オブジェクト形式にクエリーします。
attribute
マークアップから属性の値を取り出すには attribute
を使用します。
例: ブロックのマークアップ内の画像から src
属性を取り出す。
{
url: {
type: 'string',
source: 'attribute',
selector: 'img',
attribute: 'src',
}
}
// { "url": "https://lorempixel.com/1200/800/" }
マークアップのほとんどの属性タイプは string
です。HTML の数字の属性も文字列として保存され自動では変換されません。
{
width: {
type: 'string',
source: 'attribute',
selector: 'img',
attribute: 'width',
}
}
// { "width": "50" }
例外は button
の disabled
属性のような、属性の存在を確認する場合です。この場合にはタイプ boolean
を使うことができ保存した値も boolean になります。
{
disabled: {
type: 'boolean',
source: 'attribute',
selector: 'button',
attribute: 'disabled',
}
}
// { "disabled": true }
text
マークアップから内部のテキストを取り出すには text
を使用します。
{
content: {
type: 'string',
source: 'text',
selector: 'figcaption',
}
}
// { "content": "The inner text of the figcaption element" }
次の例では source として text
、selector として .my-content
クラスを使用してテキストを抽出しています。
{
content: {
type: 'string',
source: 'text',
selector: '.my-content',
}
}
// { "content": "The inner text of .my-content class" }
html
マークアップから内部の HTML を取り出すには html
を使用します。
{
content: {
type: 'string',
source: 'html',
selector: 'figcaption',
}
}
// { "content": "The inner text of the <strong>figcaption</strong> element" }
RickText
内から複数のタグ名に合致する內部 HTML を取り出すには multiline
プロパティを使用してください。
{
content: {
type: 'string',
source: 'html',
multiline: 'p',
selector: 'blockquote',
}
}
// { "content": "<p>First line</p><p>Second line</p>" }
query
マークアップから値の配列を取り出すには query
を使用します。配列のエントリーは selector 引数で決定され、ブロック内で合致した各要素は、2番目の引数、属性ソースのオブジェクトに対応して構造化されたエントリーを持ちます。
例: ブロックのマークアップ内の各画像要素から src
と alt
を取り出す。
{
images: {
type: 'array',
source: 'query',
selector: 'img',
query: {
url: {
type: 'string',
source: 'attribute',
attribute: 'src',
},
alt: {
type: 'string',
source: 'attribute',
attribute: 'alt',
},
}
}
}
// {
// "images": [
// { "url": "https://lorempixel.com/1200/800/", "alt": "large image" },
// { "url": "https://lorempixel.com/50/50/", "alt": "small image" }
// ]
// }
meta
属性は保存された投稿コンテンツ内のブロック表現からだけでなく、投稿のメタ情報からも取り出すこともできます。このとき属性は 対応するメタキーを meta
キーに指定する必要があります。
attributes: {
author: {
type: 'string',
source: 'meta',
meta: 'author'
},
},
メタ属性は任意の属性と同じインターフェースを使用してブロックから読み書きできます。
ESNext
edit( { attributes, setAttributes } ) {
function onChange( event ) {
setAttributes( { author: event.target.value } );
}
return <input value={ attributes.author } onChange={ onChange } type="text" />;
},
ES5
edit: function( props ) {
function onChange( event ) {
props.setAttributes( { author: event.target.value } );
}
return el( 'input', {
value: props.attributes.author,
onChange: onChange,
} );
},
考慮点
デフォルトではメタフィールドは投稿オブジェクトのメタから除外されます。これを回避するにはフィールドを明示的に見えるようにします。
function gutenberg_my_block_init() {
register_post_meta( 'post', 'author', array(
'show_in_rest' => true,
) );
}
add_action( 'init', 'gutenberg_my_block_init' );
さらに WordPress のデフォルトに注意してください。
- 1つのメタデータを単一として扱わず、代わりに値の配列を返します。
- データを文字列として扱います。
どちらの動きも希望しない場合には、同じ register_post_meta
を single
かつまたは type
パラメータを指定して呼び出します。
function gutenberg_my_block_init() {
register_post_meta( 'post', 'author_count', array(
'show_in_rest' => true,
'single' => true,
'type' => 'integer',
) );
}
add_action( 'init', 'gutenberg_my_block_init' );
引数にオブジェクトまたは配列を使用したい場合には string
属性タイプを登録し JSON を中継役に使用します。まず構造化データを JSON にシリアライズして保存し、サーバー側で JSON 文字列をデシリアライズします。このときデータの整合性に責任があることに注意してください。適切なサニタイズや失われたデータの調節などが必要です。
最後に属性を設定する差にはデータのタイプを尊重してください。なぜならフレームワークは自動でメタの型変換を実行しないためです。ブロック属性の誤った型は保存した後も投稿を dirty のままにします (参照 isEditedPostDirty
、hasEditedAttributes
)。たとえば authorCount
が integer なら、イベントハンドラは異なる種類のdataを渡す可能性があるため、値を明示的に型変換する必要があります。
function onChange( event ) {
props.setAttributes( { authorCount: Number( event.target.value ) } );
}
最終更新日: