型検証

type は属性によって保存されるデータの型を示します。データがどこに保存されるかは source フィールドによって定義されます。

type は必須ですが、enum が提供されている場合は不要です。type は enum と一緒に使用できます。

type フィールドは次のいずれかでなければなりません:

  • null
  • boolean
  • object
  • array
  • string
  • integer
  • number (同じく integer)

object の有効性は source によって決まります。例については、以下の query の詳細を参照してください。

列挙型検証

属性は固定された値のセットの1つとして定義できます。これは enum によって指定され、許可された値の配列が含まれます:

例: 例 enum。 

  1. {
  2.    size: {
  3.    enum: [ 'large', 'small', 'tiny' ]
  4.    }
  5. }

値のソース

属性ソースは、保存された投稿コンテンツから属性値がどのように抽出されるかを定義するために使用されます。これにより、保存されたマークアップからブロックのJavaScript表現へのマッピングメカニズムが提供されます。

利用可能な source 値は次のとおりです:

– (no value) – source が指定されていない場合、データはブロックの コメント区切り に保存されます。

– attribute – データはHTML要素の属性に保存されます。

– text – データはHTMLテキストに保存されます。

– html – データはHTMLに保存されます。これは通常 RichText によって使用されます。

– query – データはオブジェクトの配列として保存されます。

– meta – データは投稿メタに保存されます（非推奨）。

source フィールドは通常 selector フィールドと組み合わせて使用されます。セレクター引数が指定されていない場合、ソース定義はブロックのルートノードに対して実行されます。セレクター引数が指定されている場合、それはブロック内の一致する要素に対して実行されます。

selector はHTMLタグであるか、querySelector でクエリ可能なものである必要があります。クラスやID属性などが含まれます。以下に例を示します。

例えば、selector が img の場合、img 要素に一致し、img.class は img 要素に一致し、class クラスを持っています。

内部的には、属性ソースは hpq によって提供される機能のスーパーセットです。これは、HTMLマークアップをオブジェクト形状に解析し、クエリするために使用される小さなライブラリです。

要約すると、source はコンテンツ内のデータが保存される場所を決定し、type はそのデータが何であるかを決定します。保存されるデータの量を減らすためには、通常、コメント区切り内の属性としてではなく、HTML内にできるだけ多くのデータを保存する方が良いです。

属性ソース

attribute ソースを使用して、マークアップ内の属性から値を抽出します。属性は attribute フィールドによって指定され、これは必ず提供されなければなりません。

例: ブロックのマークアップ内に見つかった画像から src 属性を抽出します。

保存されたコンテンツ: 

  1. <div>
  2.    Block Content
  4.    <img src="https://lorempixel.com/1200/800/" />
  5. </div>

属性定義: 

  1. {
  2.    url: {
  3.    type: 'string',
  4.    source: 'attribute',
  5.    selector: 'img',
  6.    attribute: 'src',
  7.    }
  8. }

ブロック内で利用可能な属性: 

  1. { "url": "https://lorempixel.com/1200/800/" }

マークアップからのほとんどの属性は string 型になります。HTML内の数値属性は依然として文字列として保存され、自動的には変換されません。

例: ブロックのマークアップ内に見つかった画像から width 属性を抽出します。

保存されたコンテンツ: 

  1. <div>
  2.    Block Content
  4.    <img src="https://lorempixel.com/1200/800/" width="50" />
  5. </div>

属性定義: 

  1. {
  2.    width: {
  3.    type: 'string',
  4.    source: 'attribute',
  5.    selector: 'img',
  6.    attribute: 'width',
  7.    }
  8. }

ブロック内で利用可能な属性: 

  1. { "width": "50" }

唯一の例外は、属性の存在を確認する場合です（例えば、disabled 属性が button にある場合）。その場合、型 boolean を使用でき、保存された値はブール値になります。

例: ブロックのマークアップ内に見つかったボタンから disabled 属性を抽出します。

保存されたコンテンツ: 

  1. <div>
  2.    Block Content
  4.    <button type="button" disabled>Button</button>
  5. </div>

属性定義: 

  1. {
  2.    disabled: {
  3.    type: 'boolean',
  4.    source: 'attribute',
  5.    selector: 'button',
  6.    attribute: 'disabled',
  7.    }
  8. }

ブロック内で利用可能な属性: 

  1. { "disabled": true }

テキストソース

text を使用して、マークアップから内部テキストを抽出します。HTMLは textContent のルールに従って返されることに注意してください。

例: ブロックのマークアップ内に見つかった figcaption 要素から content 属性を抽出します。

保存されたコンテンツ: 

  1. <figure>
  2.    <img src="/image.jpg" />
  4.    <figcaption>The inner text of the figcaption element</figcaption>
  5. </figure>

属性定義: 

  1. {
  2.    content: {
  3.    type: 'string',
  4.    source: 'text',
  5.    selector: 'figcaption',
  6.    }
  7. }

ブロック内で利用可能な属性: 

  1. { "content": "The inner text of the figcaption element" }

別の例として、text をソースとして使用し、.my-content クラスをセレクターとして使用してテキストを抽出します:

例: ブロックのマークアップ内に見つかった .my-content クラスを持つ要素から content 属性を抽出します。

保存されたコンテンツ: 

  1. <div>
  2.    <img src="/image.jpg" />
  4.    <p class="my-content">The inner text of .my-content class</p>
  5. </div>

属性定義: 

  1. {
  2.    content: {
  3.    type: 'string',
  4.    source: 'text',
  5.    selector: '.my-content',
  6.    }
  7. }

ブロック内で利用可能な属性: 

  1. { "content": "The inner text of .my-content class" }

HTMLソース

html を使用して、マークアップから内部HTMLを抽出します。テキストは innerHTML のルールに従って返されることに注意してください。

例: ブロックのマークアップ内に見つかった figcaption 要素から content 属性を抽出します。

保存されたコンテンツ: 

  1. <figure>
  2.    <img src="/image.jpg" />
  4.    <figcaption>The inner text of the <strong>figcaption</strong> element</figcaption>
  5. </figure>

属性定義: 

  1. {
  2.    content: {
  3.    type: 'string',
  4.    source: 'html',
  5.    selector: 'figcaption',
  6.    }
  7. }

ブロック内で利用可能な属性: 

  1. { "content": "The inner text of the <strong>figcaption</strong> element" }

クエリソース

query を使用して、マークアップから値の配列を抽出します。配列のエントリは selector 引数によって決定され、ブロック内の各一致する要素は、2番目の引数である属性ソースのオブジェクトに対応する構造を持つエントリを持ちます。

query フィールドは実質的にネストされたブロック属性定義です。さらにネストすることも可能ですが（必ずしも推奨されるわけではありません）。

例: ブロックのマークアップ内の各画像要素から src と alt を抽出します。

保存されたコンテンツ: 

  1. <div>
  2.    <img src="https://lorempixel.com/1200/800/" alt="large image" />
  3.    <img src="https://lorempixel.com/50/50/" alt="small image" />
  4. </div>

属性定義: 

  1. {
  2.    images: {
  3.    type: 'array',
  4.    source: 'query',
  5.    selector: 'img',
  6.    query: {
  7.    url: {
  8.    type: 'string',
  9.    source: 'attribute',
  10.    attribute: 'src',
  11.    },
  12.    alt: {
  13.    type: 'string',
  14.    source: 'attribute',
  15.    attribute: 'alt',
  16.    },
  17.    }
  18.    }
  19. }

ブロック内で利用可能な属性: 

  1. {
  2.    "images": [
  3.    { "url": "https://lorempixel.com/1200/800/", "alt": "large image" },
  4.    { "url": "https://lorempixel.com/50/50/", "alt": "small image" }
  5.    ]
  6. }

メタソース（非推奨）

属性は投稿のメタから取得できますが、メタ属性ソースは非推奨と見なされます。代わりに EntityProvider および関連するフックAPI を使用する必要があります。これは メタブロックの作成方法 に示されています。

属性は、ブロックの保存された投稿コンテンツ内の表現ではなく、投稿のメタから取得できます。このため、meta キーの下に対応するメタキーを指定する属性が必要です。

属性定義: 

  1. {
  2.    author: {
  3.    type: 'string',
  4.    source: 'meta',
  5.    meta: 'author'
  6.    },
  7. },

ここから、メタ属性はブロックによって任意の属性と同じインターフェースを使用して読み書きできます: 

  1. edit( { attributes, setAttributes } ) {
  2.    function onChange( event ) {
  3.    setAttributes( { author: event.target.value } );
  4.    }
  6.    return <input value={ attributes.author } onChange={ onChange } type="text" />;
  7. },

考慮事項

デフォルトでは、メタフィールドは投稿オブジェクトのメタから除外されます。これは、フィールドを明示的に可視化することで回避できます: 

  1. function gutenberg_my_block_init() {
  2.    register_post_meta( 'post', 'author', array(
  3.    'show_in_rest' => true,
  4.    ) );
  5. }
  6. add_action( 'init', 'gutenberg_my_block_init' );

さらに、WordPressはデフォルトで次のように動作します:

  • メタデータをユニークなものとして扱わず、代わりに値の配列を返します;
  • そのデータを文字列として扱います。

どちらかの動作が望ましくない場合、同じ register_post_meta 呼び出しに single および/または type パラメータを補完することができます: 

  1. function gutenberg_my_block_init() {
  2.    register_post_meta( 'post', 'author_count', array(
  3.    'show_in_rest' => true,
  4.    'single' => true,
  5.    'type' => 'integer',
  6.    ) );
  7. }
  8. add_action( 'init', 'gutenberg_my_block_init' );

オブジェクトまたは配列を属性に使用したい場合は、string 属性タイプを登録し、JSONを仲介として使用できます。構造化データを保存する前にJSONにシリアライズし、その後サーバーでJSON文字列をデシリアライズします。データの整合性については責任を持つことを忘れないでください。適切にサニタイズし、欠落データに対応するなどしてください。

最後に、属性を設定する際にはデータの型を尊重してください。フレームワークはメタの型キャスティングを自動的に行わないためです。ブロック属性の不正な型付けは、保存後も投稿が汚れたままになる原因となります（cf. isEditedPostDirty, hasEditedAttributes）。例えば、authorCount が整数の場合、イベントハンドラーが異なる種類のデータを渡す可能性があるため、値は明示的にキャストする必要があります: 

  1. function onChange( event ) {
  2.    props.setAttributes( { authorCount: Number( event.target.value ) } );
  3. }

デフォルト値

ブロック属性にはデフォルト値を含めることができ、type と source がブロックコンテンツ内の何にも一致しない場合に使用されます。

値は default フィールドによって提供され、値は属性の期待される形式と一致する必要があります。

例: 例 default 値。 

  1. {
  2.    type: 'string',
  3.    default: 'hello world'
  4. }
  1. {
  2.    type: 'array',
  3.    default: [
  4.    { "url": "https://lorempixel.com/1200/800/", "alt": "large image" },
  5.    { "url": "https://lorempixel.com/50/50/", "alt": "small image" }
  6.    ]
  7. }
  1. {
  2.    type: 'object',
  3.    default: {
  4.    width: 100,
  5.    title: 'title'
  6.    }
  7. }