フィールドの型と選び方
17種類の入力欄を、保存したい内容から選びます。本文・文字列・画像・繰り返し・参照の違いと、入力ルールを説明します。
目次
入力欄の型は、保存する内容の種類
フィールドは入力欄、型はその欄で扱う内容の種類です。タイトルなら文字列、写真なら画像、個数なら整数というように、保存したい内容から型を選びます。型を分けると、編集画面と表示用のコードで扱いやすくなります。
以下はEmDash 1.4.0で記事の入力欄に使う17種類です。プラグインの設定フォームで使える型は別に定義されているため、そちらを作る場合はプラグイン側の仕様を確認します。
文字や数値を入れる型
| 型 | 向く内容 | 週末ノートの例 |
|---|---|---|
string | 短い文字列 | 記事タイトル |
text | 複数行の装飾しない文章 | 一覧用の短い説明 |
url | リンク先 | 参考サイトのURL |
number | 小数を含む数 | 道具の重さ |
integer | 整数 | 必要な道具の個数 |
boolean | はい・いいえ | おすすめ表示するか |
datetime | 日時 | 開催日時 |
slug | 独自に保存するスラッグ風の文字 | 外部サービス用の識別文字 |
記事には標準のURL用スラッグが別にあります。独自のslug型を足しても、記事URLが自動生成・自動修正されるわけではありません。
選択・本文・ファイルを扱う型
| 型 | 向く内容 | 選ぶときの目安 |
|---|---|---|
select | 一つ選ぶ値 | 難易度を一つ選ぶ |
multiSelect | 複数選べる値 | 対応する用途を複数選ぶ |
portableText | 見出しやリンクを持つ本文 | ブログの本文 |
image | 画像の参照 | 記事のメイン写真 |
file | PDFなどの参照 | 配布用の資料 |
reference | 別の記事などへの関連 | 記事と道具紹介を結ぶ |
json | 決まった専用欄にしない構造データ | 開発者が管理する設定値 |
repeater | 同じ項目の組を繰り返す | 材料名と分量の一覧 |
blocks | 種類のある部品を並べる | 見出し・写真・特徴一覧の構成 |
カテゴリやタグで記事を分類し、分類ごとの一覧ページも作りたい場合は、分類を管理するタクソノミーを検討します。複数の値を選ぶmultiSelectとは、役割が異なります。
自分で作った入力欄がテーマからどう見えるか、管理画面の欄と取得した値の対応表で確かめられます。
定義の共通部分
新しい入力欄の定義には、少なくとも識別名、表示名、型が必要です。次はfields配列へ入れる1件の例です。
{
"slug": "subtitle",
"label": "ひとこと紹介",
"type": "string",
"validation": { "maxLength": 80 }
}slugはコードから使う識別名、labelは編集者に見せる名前です。表示名を日本語にしても、コードから読む名前はsubtitleです。
requiredは必須かどうか、defaultValueは初期値、validationは入力値の条件です。型によって使える条件が違います。入力欄を追加する場所はコンテンツモデルと運用中の項目変更を参照してください。
入力の制限を付ける
| 対象 | 主な条件 | 用途 |
|---|---|---|
| 文字列 | minLength・maxLength・pattern | 長さや書式 |
| 数値 | min・max | 範囲 |
| 選択 | validation.options | 許可する値 |
| 画像・ファイル | allowedMimeTypes | JPEG、PDFなどの種類 |
| 繰り返し | subFieldsなど | 中に置く項目 |
| blocks | allowedTypes・maxItemsなど | 追加できる部品と数 |
選択肢は、たとえばvalidation: { options: ["beginner", "intermediate"] }のように指定します。選択肢を省くと、想定していない値も受け付ける型があります。画面で選ぶ形式になっていても、保存時に値が制限されるかは別に確認してください。
本文はHTML文字列ではない
portableTextは、段落や見出しを構造化して保存する形式です。通常のtextと違い、本文を単なる文字列として取り出してHTMLへ貼る用途ではありません。
Astro側ではemdash/uiのPortableTextへ渡します。独自の本文部品を追加する場合は、編集側の定義と表示側の部品を揃えます。ページ部品で全体を説明しています。
画像・ファイルは参照を保存する
画像欄にはメディアIDや寸法などを持つ値が入り、画像の実ファイルは保存先にあります。文字列のURLと同じつもりで処理しないようにします。
fileで取得した値には、URLなどの情報が揃っていない場合があります。必要な情報が自動で補われるとも限らないため、公式のメディア表示方法に従って、参照先のファイルURLを取得します。
referenceには関連の定義がある
referenceは、別のコレクション(同じ種類のデータをまとめる入れ物)の項目と関連付ける欄です。1.4.0では、どのコレクション同士をつなぐかを定めたrelationと結び付きます。targetCollectionを指定して新しい関連を作る方法と、relationを指定して既存の関連を使う方法があります。
テキスト欄に記事IDを保存しただけでは、正式な関連の管理にはなりません。翻訳や件数の制約も関係するため、対象コレクションを変えるときは、データを保つ移行を設計します。
型を後から変える前に
文字列で保存した「約3時間」を整数へ変えても、そのまま3になるとは限りません。古い値を調べ、変換できない値の扱いを決め、別の環境で確認します。
旧データに安全でないURLが残る場合もあるため、リンクを出す側ではsanitizeHref()を使うなど、公式の型リファレンス(別タブで開く)にある表示時の注意も確認してください。