カスタムフィールド設定ガイド
記事や固定ページに自由な入力項目(画像、価格、スペック等)を追加・設定する手順を解説します。
カスタムフィールド設定ガイド
コンテンツタイプの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 | 入力欄 | 保存値 |
|---|---|---|
text | 1行入力 | 文字列または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を変更する前に、既存記事の値が新しい定義で扱えることを確認してください。