フォーム
作成フォームと編集フォームを 1 つのフラットなフィールドの集合から導き出し、ずれを生まずにフィールドをセクションにまとめ、送信後に起こることを制御します。
フォームはオブジェクトのフィールドの投影であり、2 つ目のフィールドリストではありません。 フィールドはオブジェクトで一度だけ宣言し、フォームはどのフィールドをどこに置くかを選びます。データの意味(型、検証、デフォルト、フィールドレベルのセキュリティ)がフォームに置かれることはないので、フォームがずれてデータについて偽ることはありません。
フォームビューの種類(simple、tabbed、wizard、modal など)と公開フォームの REST の契約は、ビューで扱っています。このページはレイアウトの問題、つまり作成と編集、グループ化、順序についてです。
作成フォーム ≠ 編集フォーム
新規レコードのフォームはいくつかの必須項目だけを尋ね、編集フォームはレコード全体をセクションに分けて表示するべきです。2 つのフォームを作成しないでください。 作成フォームのサブセットは、各フィールドにすでにある意図から導き出せます。
| フィールドの手がかり | 作成フォームへの影響 |
|---|---|
required: true | 作成時に表示しなければなりません |
readonly / 数式 / ロールアップ / 自動採番 / システムが記録するもの | 作成時には決して表示しません。設定できないからです |
defaultValue がある | 省略できます。自動で埋まるからです |
hidden | デフォルトではどこにも表示しません |
group | フィールドが属するセクション |
| 宣言の順序 | これがデフォルトの表示順序です。field.order はありません |
そのため、妥当な作成フォーム(編集可能で、必須または中核のフィールドを、宣言の順序で)は、何も作成しなくてもオブジェクトから自然に導かれます。省略が正解です。余分なものを何も出力しなくても、完全で正しいフォームが得られます。完全な編集フォームも導き出され、各 field.group がセクションとして具体化されます。
作成フォームを手で整えるのは、レイアウトや流れが異なる場合だけ
逃げ道は、作成のエントリポイントにバインドした名前付きのフォームビューです。これは疎な上書きとして作成します。ほとんどはフィールド名のリストです。
import { defineView } from '@objectstack/spec'
const data = { provider: 'object' as const, object: 'showcase_contact' }
export const ContactViews = defineView({
list: {
type: 'grid', data,
columns: [{ field: 'name' }, { field: 'email' }, { field: 'company' }, { field: 'stage' }],
// Bind the "+ Add record" entry point to the slim create form:
addRecord: { enabled: true, mode: 'form', formView: 'create' },
},
// Full edit form — grouped by field.group; bare strings inherit field defs.
form: {
type: 'simple', data,
sections: [
{ name: 'contact', label: 'Contact', columns: 2, fields: ['name', 'email', 'phone'] },
{ name: 'work', label: 'Work', columns: 2, fields: ['company', 'title'] },
{ name: 'status', label: 'Status', columns: 2, fields: ['stage', 'lead_score'] },
],
},
formViews: {
// Sparse create override: only the core fields, one section.
create: {
type: 'simple', data, title: 'New contact',
sections: [
{ label: 'Who is this?', columns: 1, fields: ['name', 'email', 'phone', 'company'] },
],
},
},
})バインディングは addRecord.mode: 'form' + addRecord.formView: 'create' です。formViews.create がなければ、作成のエントリはデフォルトを導き出します。あれば、作成時にはそれが優先されます。
| 本当に必要なこと | 使うもの |
|---|---|
| 作成時に尋ねるフィールドを減らす(必須 + いくつかの中核) | 純粋な導出。手で書かないでください |
| 作成時のグループ化が異なるが、小さなサブセットにすぎない | たいていはやはり導出 |
| 作成がウィザード / 多段階、作成専用の文言、条件付きの表示を持つ | formViews.create を手で書く |
目安:フィールドのサブセットが異なる → 導出する。レイアウトや流れが異なる → 上書きする。フィールドを減らすためだけに完全な作成フォームを書くと、2 つの成果物がずれる罠にまっすぐはまります。必須フィールドを追加し、作成フォームのことを忘れ、作成時に実行時の「必須フィールドがありません」が出る、という具合です。
作成のフィールドは編集のフィールドの同じ順序とグループのサブセットなので、「4 つのフィールドでクイック作成 → 保存 → 完全なレコードに着地」が視覚的に途切れません。導出はそれを無償で保ちます。
フィールドのグループ化と順序
モデルはフラットなフィールドの集合です。グリッドはフラットな列を表示します。フォームにはセクションが必要です。これは矛盾ではありません。1 つのフラットな集合を、異なるレンズを通して見ているのです。
| レンズ | フィールドの形 | 理由 |
|---|---|---|
| オブジェクトの定義 | フラット | モデルはどんなデータが存在するかを記述します |
| テーブル / グリッド | フラットな列 | グリッドはレコード × フィールドの行列です |
| フォーム / レコードページ | グループ化されたセクション | 1 件のレコードを読む人間には区切りが必要です |
グループ化の概念は 2 つあります。区別しておいてください。
1. 意味上のグループ化:field.group(オブジェクト上)。 フィールドの論理的な居場所です。モデルとともに移動し、自動生成されるフォームのデフォルトのセクション分けの元になります。
// Fields of an object; the object around them is omitted.
fields: {
name: Field.text({ label: 'Full name', group: 'contact' }),
email: Field.email({ label: 'Email', group: 'contact' }),
stage: Field.select({
label: 'Stage',
group: 'status',
options: [
{ label: 'Lead', value: 'lead' },
{ label: 'Customer', value: 'customer' },
],
}),
}2. レイアウト上のグループ化:フォームの sections(ビュー上)。 特定のフォームの明示的な配置です。どのフィールドを、どのセクションに、何列(columns)で置くか、折りたたみ可能か。field.group をデフォルトとして継承し、必要に応じてフォームごとに上書きします。
// Keys of a view container; `data` and its other keys are omitted.
form: {
type: 'simple',
sections: [
{ name: 'contact', label: 'Contact', columns: 2, fields: ['name', 'email', 'phone'] },
{ name: 'status', label: 'Status', columns: 2, fields: ['stage'] },
],
}順序は作成した順序です。 field.order はありません。オブジェクト上のフィールドの宣言の順序が、どこでもデフォルトの表示順序であり、sections(とその中のフィールド)は順序付きのリストです。
「グループ」の罠。 グリッドビューの
groupByFieldは、フィールドの値で レコード(行) をグループ化します。stage = qualifiedの行がすべてまとまります。フォームのセクションは フィールド(列) を視覚的にグループ化します。同じ言葉で、無関係な 2 つの軸です。グリッドのグループがフォームをセクションに分けることは決してありません。
送信後に起こること
送信後の体験を制御するには、フォームビューに submitBehavior を追加します。
// Keys of a form view; its other keys are omitted.
submitBehavior: {
kind: 'thank-you',
title: 'Thanks!',
message: 'A specialist will reach out within 24 hours.',
}kind | 動作 |
|---|---|
thank-you (デフォルト) | フォームを確認パネル(title、message)に置き換えます |
redirect | delayMs(デフォルト 0)の後に url へ移動します。マーケティングページに最適です |
continue | 次の回答のためにフォームをリセットします。キオスク、一括入力向けです |
next-record | キュー内の次のレコードに進みます(内部モード) |
公開フォームと内部フォームのどちらも、?prefill_<field>=<value> という URL パラメータに従います。メールのリンクやキャンペーンページからフォームに値を入れておけます。事前入力は UX の近道であって、権限のすり抜けではありません。値はやはり検証と、(公開フォームの場合は)サーバー側のフィールドのホワイトリストを通ります。
/console/f/contact-us?prefill_company=Acme&prefill_email=ada@example.com
/console/forms/quick_create?prefill_lead_source=event_booth_2026レコードの詳細はフォームのバインディングではなくロールで決まる
フォームビューをレコード詳細画面に固定するオブジェクトレベルのキーはありません。詳細のレンダリングは、オブジェクトの画面をまたぐ意味上のロールから導き出されます。nameField(表示名)、highlightFields(最も重要なフィールドの帯)、stageField(ライフサイクルの進捗ステッパー)、そして fieldGroups + Field.group(フォーム、モーダル、詳細ページで共有されるセクション分け)です。ロールから導き出せる以上の特注のレイアウトがレコードページに必要なときは、そのオブジェクトにカスタムのページを割り当てます。
アンチパターン
- 手で作成した 2 つの完全なフィールドリスト(
contact_create_form+contact_edit_form)。ずれることが確実です。 - フィールドの型 / 検証 / 選択肢をフォームで書き直すこと。 データの意味はオブジェクトにだけ置きます。
- すべてのフォームでグループ化を打ち直すこと。
field.groupを一度宣言し、本当に異なる場合だけ上書きします。 - フォームを満たすためにデータモデルに構造的な入れ子を加えること。 モデルはフラットのままにし、フォームがグループ化します。