CHAPTER 06

カスタムフィールド設定ガイド

記事や固定ページに自由な入力項目(画像、価格、スペック等)を追加・設定する手順を解説します。

カスタムフィールド設定ガイド

コンテンツタイプのschema_defへJSON配列を保存すると、記事編集画面へ専用入力欄を追加できます。記事ごとの入力値はaihp_contents.fieldsへJSONオブジェクトとして保存されます。

基本形

[
  {
    "key": "subtitle",
    "label": "サブタイトル",
    "type": "text",
    "required": false,
    "help": "記事タイトルの下に表示します"
  }
]
プロパティ必須内容
key必須小文字英字で始まる英小文字・数字・アンダースコア。最大64文字
label必須管理画面に表示する名称
type必須対応する9種類のいずれか
required任意省略時はfalse
help任意入力欄の下に表示する説明

title、content、slug、statusなどの標準項目名は、カスタムフィールドのkeyに使用できません。

対応する9種類

type入力欄保存値
text1行入力文字列またはnull
textarea複数行入力文字列またはnull
number数値JSON数値またはnull
date日付YYYY-MM-DDまたはnull
datetime日時YYYY-MM-DDTHH:MMまたはnull
checkboxチェックtrueまたはfalse
select選択肢optionのvalueまたはnull
fileファイル/uploads/{ランダム名}またはnull
repeater繰り返しJSON配列

各タイプの例

text

{ "key": "website", "label": "Webサイト", "type": "text", "format": "url" }

formatはurl、email、telを指定できます。

textarea

{ "key": "summary", "label": "概要", "type": "textarea" }

改行を保持した文字列として保存し、任意HTMLとしては扱いません。

number

{
  "key": "price",
  "label": "価格",
  "type": "number",
  "min": 0,
  "max": 1000000,
  "step": 100
}

min、max、stepは任意です。

date・datetime

{ "key": "event_date", "label": "開催日", "type": "date" }
{ "key": "event_at", "label": "開催日時", "type": "datetime" }

存在しない日付や形式の違う値は保存できません。

checkbox

{ "key": "new_flg", "label": "NEW表示", "type": "checkbox" }

旧名称checkは使用できません。

select

{
  "key": "kind",
  "label": "種別",
  "type": "select",
  "options": [
    { "value": "news", "label": "ニュース" },
    { "value": "event", "label": "イベント" }
  ]
}

DBにはvalueを保存し、HTMLではfields.kindでvalue、fields.kind_labelでlabelを参照できます。

file

{
  "key": "eye_catch",
  "label": "アイキャッチ",
  "type": "file",
  "accept": ["image/jpeg", "image/png", "image/webp"],
  "max_size_mb": 5
}
  • acceptは必須です。
  • JPEG、PNG、GIF、WebP、PDFを使用できます。
  • 実際のMIMEタイプをサーバーで検証します。
  • 保存名は元ファイル名ではなくランダム名です。
  • 新しいファイルを選ばない更新では、既存パスを維持します。
  • 差し替え前の古いファイルは自動削除しません。

repeater

{
  "key": "faq_list",
  "label": "FAQ",
  "type": "repeater",
  "fields": [
    { "key": "question", "label": "質問", "type": "text", "required": true },
    { "key": "answer", "label": "回答", "type": "textarea", "required": true }
  ]
}

子項目ではtext、textarea、number、date、datetime、checkbox、selectを使用できます。repeaterの入れ子とrepeater内のfileは使用できません。

HTMLへ表示する

記事詳細と外部一覧パーツ:

<time data-aihp="fields.event_date">2026-01-01</time>
<img data-aihp-src="fields.eye_catch" src="/assets/img/noimage.png" alt="">

インライン記事一覧:

<time data-aihp="loop.fields.event_date">2026-01-01</time>

repeater:

<dl data-aihp-loop="fields.faq_list">
  <div>
    <dt data-aihp="loop.question">質問</dt>
    <dd data-aihp="loop.answer">回答</dd>
  </div>
</dl>

保存時の検証

  • schemaにないkeyは保存しません。
  • requiredの空値はエラーです。
  • checkboxのrequired: trueはチェック必須です。
  • number、date、datetime、selectはschemaに従って検証します。
  • 不正なJSONを空データへ自動変換しません。
  • fields直下はJSONオブジェクトでなければなりません。
  • 旧データの空配列[]だけは空オブジェクト相当として読み込めます。

schemaを変更する前に、既存記事の値が新しい定義で扱えることを確認してください。