Home / Handbook / ブロックエディターハンドブック / 開発者ドキュメント / ブロック API リファレンス / 属性

属性

タイプの妥当性検証

属性の必須フィールドは 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 ) } );
}

最終更新日: 2020年6月20日

WordPress.org

日本語

ようこそ

P2 の使い方

お問い合わせ

属性