Zenn
🐷

Payloadのフィールドタイプの分類

に公開
Payload
tech

はじめに

Payloadのフィールドタイプとは、コレクションやグローバルのスキーマを定義するもので、下記などが該当します。

  • Text
  • Date
  • Number

上記以外にも多数のフィールドタイプが用意されており、この記事ではフィールドタイプの分類について紹介します。フィールドタイプの 分類 にフォーカスして解説しますので、すべてのフィールドタイプは解説しません。すべてのフィールドタイプについて知りたい方は、公式ドキュメントをご参照ください。

https://payloadcms.com/docs/fields/overview

フィールドタイプの分類

Payloadのフィールドタイプは、下記の3種に分類されます。Payloadでは フィールド ≠ データベースに保存されるデータ であることに注意が必要です。

Data Fields

データベースにデータを保存するために使用するフィールドタイプです。下記などのフィールドタイプがこれに該当します。一般的にCMSのフィールドというと、このData Fieldsのことを指すと思いますので、イメージしやすいかと思います。

  • Text
  • Date
  • Number
  • Upload（ファイルのこと）
  • Checkbox
  • Radio
  • Select
  • etc...

Presentational Fields

管理画面上のUIを整えるために使用するフィールドタイプです。下記などのフィールドタイプがこれに該当します。各フィールドタイプの詳細については後述します。

  • Collapsible
  • Row
  • Tabs
  • etc...

Virtual Fields

データベースに保存されていないデータを表示するために使用するフィールドタイプです。下記のフィールドタイプがこれに該当します。Joinフィールドタイプの詳細については後述します。

  • Join

Presentational Fieldsについて詳しく知る

前述した通り、Presentational Fieldsは、管理画面上のUIを整えるために使用するフィールドタイプです。各フィールドタイプを使用した場合の管理画面上での見え方と、設定方法について詳しく見ていきたいと思います。前提知識として、Payloadの設定はすべてコードで行う仕様となっているため、その点ご認識おきください。

Collapsible

折りたたみ可能な入れ子構造のUIを提供します。フィールドが多い場合に、関連するフィールドをCollapsibleでまとめて折りたためるようにすることで、サイト管理者がデータを入力しやすくなります。

Collapsibleの管理画面上のUI

下記のようなJavaScriptオブジェクトの記述で設定します。

{
  type: 'collapsible',
  label: {
    en: 'Collapsible',
    ja: '折りたたみ',
  },
  fields: [
    {
      name: 'textInCollapsible',
      type: 'text',
      label: {
        en: 'Text in Collapsible',
        ja: '折りたたみ内のテキスト',
      },
    },
    {
      name: 'dateInCollapsible',
      type: 'date',
      label: {
        en: 'Date in Collapsible',
        ja: '折りたたみ内の日付',
      },
    },
  ],
},

Row

複数のフィールドを横並びで表示するUIを提供します。

Rowの管理画面上のUI

下記のようなJavaScriptオブジェクトの記述で設定します。パーセントで各フィールドの横幅の割合を指定できます。

{
  type: 'row',
  fields: [
    {
      name: 'text1InRow',
      label: {
        en: 'Text1 in Row',
        ja: 'Row内のテキスト1',
      },
      type: 'text',
      admin: {
        width: '50%',
      },
    },
    {
      name: 'text2InRow',
      label: {
        en: 'Text2 in Row',
        ja: 'Row内のテキスト2',
      },
      type: 'text',
      admin: {
        width: '50%',
      },
    },
  ],
},

Tabs

複数フィールドのまとまりをタブで表示切り替えできるUIを提供します。

Tabsの管理画面上のUI

下記のようなJavaScriptオブジェクトの記述で設定します。

{
  type: 'tabs',
  tabs: [
    {
      label: 'Tab One Label',
      fields: [
        {
          name: 'textInTab1',
          label: {
            en: 'Text in Tab One',
            ja: 'タブ1内のテキスト',
          },
          type: 'text',
        },
      ],
    },
    {
      label: 'Tab Two Label',
      fields: [
        {
          name: 'textInTab2',
          label: {
            en: 'Text in Tab Two',
            ja: 'タブ2内のテキスト',
          },
          type: 'text',
        },
      ],
    },
  ],
},

Virtual Fieldsについて詳しく知る

前述した通り、Virtual Fieldsは、データベースに保存されていないデータを表示するために使用するフィールドタイプです。2025/05/02現在、Joinフィールドタイプのみがこれに該当します。Joinフィールドタイプについて詳しく解説したいと思います。

Join

被参照情報を表示するために使用します。

わかりにくいため、具体例を挙げて説明したいと思います。Payloadで作られたWebサイトに、下記2つのコレクションがあるとします。

  • ブログ
  • ブログタグ

このとき、ブログ → ブログタグの向きで参照情報を持ちますが、逆のブログタグ → ブログの向きでは参照情報を持ちません。しかし、ブログタグの管理画面で、そのブログタグを参照しているブログの一覧（被参照情報）を確認したいケースは多いです。そのような場合に、ブログタグにJoinフィールドを持たせることで実現できます。ブログタグ → ブログの向きでは参照情報を持っていない（データベースに保存されていない）ため、Virtualなフィールドだということです。

他にも下記のようなユースケースが考えられます。

  • 特定の商品の注文一覧を表示する
  • 特定のメディアファイルが使用されているページの一覧を表示する

まとめ

この記事では、フィールドタイプの分類について紹介しました。Payloadにおいては、データベースに保存されるものだけでなく、管理画面のUIを整える機能などもフィールドに含まれることがポイントです。Virtual Fieldsについては、この記事の説明だけでは理解し難いかと思いますので、ぜひ公式ドキュメントにも目を通していただければと思います。

参考

https://payloadcms.com/docs/fields/overview

Discussion