WordPress では、複数の投稿データ(リスト)を取得する場合は getEntityRecords 、単一の投稿データを取得する場合はgetEntityRecord という便利な API が用意されています。

例えば Gutenberg のブロック開発では、この API を利用することで、指定した条件に合致する投稿の一覧を表示するカスタムブロックを作成できます。

getEntityRecords で指定できるパラメータ(クエリ)

getEntityRecords 関数を使用してJavaScript(React) 経由で WordPress の記事一覧を抽出する場合、getEntityRecords の実態は WordPress の REST API を使用してエンティティを作成しているため、抽出条件を指定する各パラメータは、WordPress の REST API (/wp-json/wp/v2/posts) で指定可能なパラメータと共通しています。

参考 : https://developer.wordpress.org/rest-api/reference/posts/#arguments

このうち、記事を取得する対象期間を指定するためのafter(指定日時より後を対象), before(指定日時より前を対象) パラメータを指定する場合、値には ISO8601 形式に準拠するフォーマットの日付用文字列を与える必要があります。
ISO8601 形式とは、日付と時刻をセパレータ「T」で区切って YYYY-MM-DDThh:mm:ss という書式に変換された文字列です。

最も簡単に ISO8601 形式に近い書式を得るには、日付と時刻を文字列型に変換する toLocaleString メソッドにスウェーデンのロケール( sv-SE )を指定すると便利です。

new Date().toLocaleString( 'sv-SE' ).replace( ' ', 'T' )

例えば、2030年4月25日20時1分45秒であれば、「2030-04-25T20:01:45」というフォーマットに変換した日付の文字列を before, after, modified_before または modified_after の値として指定します。

getEntityRecord で取得できる投稿データ

getEntityRecord関数 (WordPress の REST API) を使用して投稿データを取得した場合、デフォルトでは以下のフィールドが含まれます。

デフォルトのフィールド

参考 : https://developer.wordpress.org/rest-api/reference/posts/#schema

これらのフィールドは、投稿タイプが post の場合のものとなり、カスタム投稿タイプやページには、これらのフィールドの一部が含まれない場合があります。

独自のフィールドを追加する

先述のデフォルトのフィールドでは、例えばカテゴリ名や寄稿者名、コメント数、アイキャッチ画像(投稿サムネイル)のURLが含まれないため、getEntityRecord 関数を利用して一般的なアーカイブページのような、アイキャッチ画像、タイトル、カテゴリ名、メタ情報などが並んだ投稿リストを表示する場合、情報が不足しています。

これを補うには、PHP にてフィールドを追加するためのregister_rest_field という関数を利用をして、必要な投稿データを取得する処理(関数)を、rest_api_init というアクションフィルターにフックすることで、getEntityRecord から取得される投稿データに目的のデータを値に持つ独自のフィールドを追加しておくことで対応できます。

例えば、アイキャッチ画像を JavaScript(React)から PHP(REST API) で取得してその結果を受け取りたい場合は、以下のように REST API を登録しておきます。

// 投稿サムネイル(アイキャッチ)を取得するための関数を登録
function myplugin_register_rest_fields() {
  register_rest_field( 'post', 
    'post_image_url',  // 追加するフィールド名
    array(
      'get_callback'    => 'mytheme_get_post_image_url',  // コールバック関数
      'update_callback' => null,
      'schema'          => null,
  ) );
}
add_action( 'rest_api_init', 'myplugin_register_rest_fields' );
 
// 投稿サムネイルを取得するコールバック関数(フィールドに渡す値を返す)
function myplugin_get_post_image_url( $post ) {
  if ( has_post_thumbnail( $post[ 'id' ] ) ) {
    // アイキャッチ画像のデータを取得
    $img_urls = wp_get_attachment_image_src( get_post_thumbnail_id( $post[ 'id' ] ), 'full' );
    // フルサイズの画像(URL)を返す
    return $img_urls[0];
  }
  return false;
}

これで post_image_url というカスタムフィールドが投稿データに追加されました。
これにより、JavaScript から getEntityRecords や getEntityRecord で抽出した記事一覧(配列)の各投稿データについて、追加したカスタムフィールド( post_image_url )を参照することでアイキャッチ画像のURLを受け取ることができます。

import { useSelect } from "@wordpress/data";
 
// 記事一覧を取得する関数
const getPostsByQuery = ( props ) => {
  const {
    query,
    postType
  } = props;
 
  const filteredPosts = useSelect( ( select ) => {
    const { getEntityRecords } = select( 'core' );
    return getEntityRecords( 'postType', postType, query );
  } );
 
  return filteredPosts;
}
 
// クエリパラメータ例
const query = {
  orderby: 'modified',  // 並び順
  per_page: 10,  // 記事取得数
  author: 1,  // 対象の寄稿者(ID)
  search: "Gutenberg",  // 検索ワード
  categories: [ 4, 12, 20 ]  // 対象カテゴリ(ID)
};
 
// クエリパラメータを元に記事一覧を取得(対象投稿タイプ: post )
const posts = getPostsByQuery( { query, postType: 'post' } );
 
if ( posts && Array.isArray( posts ) ) {
  posts.forEach( ( post, index ) => {
    // post.post_image_url を参照するとアイキャッチ画像のURLが得られる
    console.dir( post.post_image_url );
  } )
}

同様に、PHP にて register_rest_field で JavaScript から参照したい投稿のデータを渡すカスタムフィールドを登録しておくことで、例えば寄稿者の細かなプロフィール情報やカテゴリーリンクのリストなど、デフォルトのフィールドでは取得できない不足しているデータを getEntityRecords や getEntityRecord の API を介して JavaScript で扱えるようになります。