Package Reference - @wordpress/dataviews - 《WordPress開発者リソース》日本語

インストール
使用法
プロパティ
このパッケージへの貢献

インストール

モジュールをインストールします

npm install @wordpress/dataviews --save

使用法

const Example = () => {
   // Declare data, fields, etc.
   return (
   <DataViews
   data={ data }
   fields={ fields }
   view={ view }
   onChangeView={ onChangeView }
   defaultLayouts={ defaultLayouts }
   actions={ actions }
   paginationInfo={ paginationInfo }
   />
   );
};

WordPress Gutenbergのストーリーブックには、Dataviewsコンポーネントの実装例があります。

プロパティ

data: Object[]

作業するデータセットは、一次元配列として表されます。

例:

const data = [
   {
   id: 1,
   title: 'Title',
   author: 'Admin',
   date: '2012-04-23T18:25:43.511Z',
   },
   {
   /* ... */
   },
];

デフォルトでは、dataviewsは各レコードのidを一意の識別子として使用します。もしそうでない場合、消費者は一意の識別子を返すgetItemId関数を提供する必要があります。

fields: Object[]

フィールドは、データセット内の各レコードの可視項目を説明します。

例:

const STATUSES = [
   { value: 'draft', label: __( 'Draft' ) },
   { value: 'future', label: __( 'Scheduled' ) },
   { value: 'pending', label: __( 'Pending Review' ) },
   { value: 'private', label: __( 'Private' ) },
   { value: 'publish', label: __( 'Published' ) },
   { value: 'trash', label: __( 'Trash' ) },
];
const fields = [
   {
   id: 'title',
   label: 'Title',
   enableHiding: false,
   },
   {
   id: 'date',
   label: 'Date',
   render: ( { item } ) => {
   return <time>{ getFormattedDate( item.date ) }</time>;
   },
   },
   {
   id: 'author',
   label: __( 'Author' ),
   render: ( { item } ) => {
   return <a href="...">{ item.author }</a>;
   },
   elements: [
   { value: 1, label: 'Admin' },
   { value: 2, label: 'User' },
   ],
   filterBy: {
   operators: [ 'is', 'isNot' ],
   },
   enableSorting: false,
   },
   {
   label: __( 'Status' ),
   id: 'status',
   getValue: ( { item } ) =>
   STATUSES.find( ( { value } ) => value === item.status )?.label ??
   item.status,
   elements: STATUSES,
   filterBy: {
   operators: [ 'isAny' ],
   },
   enableSorting: false,
   },
];

各フィールドは、以下のプロパティを持つオブジェクトです：

id: フィールドの識別子。一意です。
label: UIに表示されるフィールドの名前。
getValue: フィールドの値を返す関数。デフォルトはfield[id]です。
render: フィールドをレンダリングする関数。オプションで、getValueがrenderが定義されていない場合に使用されます。
elements: フィルターとして使用する際や編集時（DataFormコンポーネント）の選択肢のリスト。以下のプロパティを持つオブジェクトの配列を期待します：
- value: フィルター対象の値のID（内部使用）
- label: アイテムのUIに表示されるテキスト。
- description: 要素を説明する長い説明文。表示されます。オプションです。
  フィールドによるフィルターを有効にするには、フィルター対象のフィールドのelementsプロパティに適切な値を設定するだけです。
type: フィールドのタイプ。「フィールドタイプ」を参照してください。
enableSorting: 指定されたフィールドでデータをソートできるかどうか。デフォルトは真です。
enableHiding: フィールドを非表示にできるかどうか。デフォルトは真です。
enableGlobalSearch: フィールドが検索可能かどうか。デフォルトは偽です。
filterBy: elementsプロパティによって有効にされたフィルターの設定。
- operators: フィールドでサポートされている演算子のリスト。
- isPrimary: プライマリフィルターであるかどうか。プライマリフィルターは常に表示され、「フィルターを追加」コンポーネントにはリストされず、リストレイアウトではセカンダリフィルターのように振る舞います。

view: object

ビューオブジェクトは、データセットがユーザーにどのように表示されるかを構成します。

例:

const view = {
   type: 'table',
   search: '',
   filters: [
   { field: 'author', operator: 'is', value: 2 },
   { field: 'status', operator: 'isAny', value: [ 'publish', 'draft' ] },
   ],
   page: 1,
   perPage: 5,
   sort: {
   field: 'date',
   direction: 'desc',
   },
   fields: [ 'author', 'status' ],
   layout: {},
};

プロパティ：

type: ビュータイプ、table、grid、listのいずれか。「レイアウトタイプ」を参照してください。
search: データセットに適用されるテキスト検索。
filters: データセットに適用されるフィルター。各アイテムは次のことを説明します：
- field: このフィルターがバインドされているフィールド。
- operator: どのタイプのフィルターであるか。「演算子タイプ」を参照してください。
- value: ユーザーによって選択された実際の値。
perPage: ページごとに表示するレコードの数。
page: 表示されるページ。
sort:
- field: データセットをソートするために使用されるフィールド。
- direction: ソートに使用する方向、ascまたはdescのいずれか。
fields: UIに表示されるフィールドのidと、表示される特定の順序。
layout: 特定のレイアウトタイプに固有の設定。

レイアウトのプロパティ

`layout`のプロパティ	テーブル	グリッド	リスト
`primaryField`: 各レイアウトで強調表示されるフィールドの`id`。非表示にはできません。	✓	✓	✓
`mediaField`: 各カードのメディアをレンダリングするために使用されるフィールドの`id`。非表示にはできません。		✓	✓
`columnFields`: 水平方向（デフォルト）ではなく、垂直にスタックしてレンダリングするフィールドの`id`のリスト。		✓
`badgeFields`: ラベルなしでバッジとしてスタイルされたフィールドの`id`のリスト。		✓
`combinedFields`: 他のフィールドを組み合わせて作成された「仮想」フィールドのリスト。「フィールドの組み合わせ」セクションを参照してください。	✓
`styles`: 各フィールド列の追加の`width`、`maxWidth`、`minWidth`スタイル。	✓

onChangeView: function

ビューは、データセットの可視状態の表現です：どのタイプのレイアウトが使用されているか（テーブル、グリッドなど）、データセットがどのようにフィルタリングされているか、どのようにソートまたはページネーションされているか。

ユーザーオプションがビューの設定（ソート、ページネーション、フィルターなど）を通じて定義されていることを確認するのは消費者の責任です。onChangeViewプロパティは、ビューの設定が変更されたときに呼び出されるコールバックを提供することを消費者に許可し、データを適切に処理します。

以下の例は、ビューオブジェクトがエンティティの抽象化を介してWordPress REST APIをクエリするためにどのように使用されるかを示しています。同じことは他のデータプロバイダーでも行うことができます。

function MyCustomPageTable() {
   const [ view, setView ] = useState( {
   type: 'table',
   perPage: 5,
   page: 1,
   sort: {
   field: 'date',
   direction: 'desc',
   },
   search: '',
   filters: [
   { field: 'author', operator: 'is', value: 2 },
   {
   field: 'status',
   operator: 'isAny',
   value: [ 'publish', 'draft' ],
   },
   ],
   fields: [ 'author', 'status' ],
   layout: {},
   } );
   const queryArgs = useMemo( () => {
   const filters = {};
   view.filters.forEach( ( filter ) => {
   if ( filter.field === 'status' && filter.operator === 'isAny' ) {
   filters.status = filter.value;
   }
   if ( filter.field === 'author' && filter.operator === 'is' ) {
   filters.author = filter.value;
   }
   } );
   return {
   per_page: view.perPage,
   page: view.page,
   _embed: 'author',
   order: view.sort?.direction,
   orderby: view.sort?.field,
   search: view.search,
   ...filters,
   };
   }, [ view ] );
   const { records } = useEntityRecords( 'postType', 'page', queryArgs );
   return (
   <DataViews
   data={ records }
   view={ view }
   onChangeView={ setView }
   // ...
   />
   );
}

actions: Object[]

各レコードに対して実行できる操作のコレクション。

各アクションは、以下のプロパティを持つオブジェクトです：

id: 文字列、必須。一意のアクション識別子。例えば、move-to-trash。
label: 文字列|関数、必須。アクションのユーザー向け説明。例えば、Move to Trash。選択されたアイテムに基づいてラベルを調整したい場合、選択されたレコードを入力として受け取る関数を提供できます。この関数は常にstring値を返す必要があります。
isPrimary: ブール値、オプション。アクションがインライン（プライマリ）でリストされるべきか、より多くのアクションメニューに隠されるべきか（セカンダリ）。
icon: プライマリアクションのために表示されるアイコン。プライマリアクションには必須であり、そうでない場合はアクションはセカンダリと見なされます。
isEligible: 関数、オプション。特定のレコードに対してアクションを実行できるかどうか。存在しない場合、アクションはすべてのアイテムに対して適格と見なされます。与えられたレコードを入力として受け取ります。
isDestructive: ブール値、オプション。アクションがデータを削除できるかどうか。この場合、UIは赤色でそれを伝えます。
callback: 関数、RenderModalが提供されていない限り必須。レコードを入力として受け取り、必要なアクションを実行するコールバック関数。
RenderModal: ReactElement、オプション。アクションがモーダルでUIをレンダリングする必要がある場合、レコードをitemとして、closeModal関数を持つコンポーネントを提供できます。このプロパティが提供されると、callbackプロパティは無視されます。
hideModalHeader: ブール値、オプション。このプロパティはRenderModalと組み合わせて使用され、モーダルのヘッダーの可視性を制御します。アクションがモーダルをレンダリングし、ヘッダーを隠さない場合、アクションのラベルはモーダルのヘッダーで使用されます。
supportsBulk: アクションがバルクアクションとして使用できるかどうか。デフォルトは偽です。
disabled: アクションが無効かどうか。デフォルトは偽です。

paginationInfo: Object

totalItems: データセット内のアイテムの総数。
totalPages: ユーザーが提供したページごとのアイテム数とデータセット内の総アイテム数を考慮した総ページ数。

search: boolean

検索入力が有効かどうか。デフォルトはtrueです。

searchLabel: string

検索入力に表示するテキスト。「検索」がデフォルトです。

getItemId: function

アイテムを受け取り、その一意の識別子を返す関数。デフォルトでは、アイテムのidを一意の識別子として使用します。そうでない場合、消費者は独自のものを提供する必要があります。

isLoading: boolean

データが読み込まれているかどうか。デフォルトはfalseです。

defaultLayouts: Record< string, view >

このプロパティは、アクティブなビュータイプに関するレイアウト情報を提供します。空の場合、すべてのレイアウトタイプ（「レイアウトタイプ」を参照）を有効にし、空のレイアウトデータを持ちます。

例えば、テーブルビュータイプのみを有効にする方法は次のとおりです：

const defaultLayouts = {
   table: {
   layout: {
   primaryField: 'my-key',
   },
   },
};

 <a name="onchangeselection-function"></a>
### onChangeSelection: function
ユーザーが1つ以上のアイテムを選択したことを示すコールバックで、アイテムをパラメータとして受け取ります。これまでのところ、`````list`````ビューのみがこれを実装しています。  
 <a name="types"></a>
## タイプ
<a name="layouts"></a>
### レイアウト
- `````table`````: ビューはテーブルレイアウトを使用します。 
- `````grid`````: ビューはグリッドレイアウトを使用します。 
- `````list`````: ビューはリストレイアウトを使用します。
 <a name="fields"></a>
### フィールド
> `````enumeration`````タイプは、フィールド.elementsメタデータと冗長であると見なされ、削除されました。新しいタイプが近日中に導入される予定です。 <a name="combining-fields"></a>
## フィールドの組み合わせ
`````table`````レイアウトは、既存のフィールドを組み合わせて「仮想」フィールドを作成する能力を持っています。  
各「仮想フィールド」は、`````id`````と`````label`````（オプションで`````header`````の代わりに）を提供する必要があり、これらは他のフィールドと同じ意味を持ちます。  
さらに、次のものを提供する必要があります：  
- `````children`````: 組み合わせるフィールドの`````id`````のリスト 
- `````direction`````: どのようにスタックするべきか、`````vertical`````または`````horizontal

例えば、siteフィールドを定義する方法は次のとおりです。これはtitleとdescriptionフィールドの組み合わせであり、表示されません：

{
   fields: [ 'site', 'status' ],
   layout: {
   combinedFields: [
   {
   id: 'site',
   label: 'Site',
   children: [ 'title', 'description' ],
   direction: 'vertical',
   }
   ]
   }
}

演算子

許可されている演算子：

演算子	選択	説明	例
`is`	単一アイテム	`EQUAL TO`。アイテムのフィールドが単一の値に等しい。	著者はAdmin
`isNot`	単一アイテム	`NOT EQUAL TO`。アイテムのフィールドが単一の値に等しくない。	著者はAdminではない
`isAny`	複数アイテム	`OR`。アイテムのフィールドが値のリストに存在する。	著者は任意：Admin、Editor
`isNone`	複数アイテム	`NOT OR`。アイテムのフィールドが値のリストに存在しない。	著者はなし：Admin、Editor
`isAll`	複数アイテム	`AND`。アイテムのフィールドがリスト内のすべての値を持つ。	カテゴリはすべて：Book、Review、Science Fiction
`isNotAll`	複数アイテム	`NOT AND`。アイテムのフィールドがリスト内のすべての値を持っていない。	カテゴリはすべてではない：Book、Review、Science Fiction

isとisNotは単一選択演算子であり、isAny、isNone、isAll、およびisNotALlは複数選択です。デフォルトでは、演算子が宣言されていないフィルターはisAnyおよびisNone複数選択演算子をサポートします。フィルターは単一選択と複数選択演算子を混在させることはできません。単一選択演算子が有効な演算子のリストに存在する場合、複数選択演算子は破棄され、フィルターは1つ以上のアイテムを選択することを許可しません。

レガシー演算子inおよびnotInは非推奨となり、近日中に削除される予定です。その間、isおよびisNot演算子として機能します。

このパッケージへの貢献

これはグーテンベルクプロジェクトの一部である個別のパッケージです。このプロジェクトはモノレポとして整理されています。特定の目的を持つ複数の自己完結型ソフトウェアパッケージで構成されています。このモノレポ内のパッケージはnpmに公開され、WordPressや他のソフトウェアプロジェクトで使用されています。

このパッケージやグーテンベルク全体への貢献について詳しく知りたい場合は、プロジェクトの主な貢献者ガイドをお読みください。