一覧に列を出す
表示する列、幅、並べ替え、値の見せ方。
一覧に出す列は table.columns に並べる。並べた順がそのまま画面の左からの順になる。
page:
type: master
id: customer_master
title: 顧客マスタ
repository: customerRepository
key: code
table:
columns:
- { field: code, label: コード, width: 120, sortable: true }
- { field: name, label: 顧客名, sortable: true }
- { field: sales, label: 売上, format: currency }field がデータ側の項目名、label が画面に出る見出し。label を省くと field がそのまま出るので、業務の言葉にしたいときは書く。
幅は基本書かない
width を省くと内容に応じて配分される。書くのは「コードは短いのに広く取られてしまう」ような、見た目が崩れる列だけでいい。全列に書くと画面幅が変わったときに破綻する。
値の見せ方は format で変える
金額・日付・和暦などは、データを加工してから渡すのではなく format で指定する。加工を自分のコードでやると、同じ項目を別の画面に出したときに揃わなくなる。
- { field: sales, label: 売上, format: currency, config: { symbol: "¥" } }
- { field: updatedAt, label: 更新日, format: wareki }書ける format の一覧は下の表と、チートシートにある。足りない見せ方はプラグインで足す。
並べ替えは列ごとに許可する
sortable: true を書いた列だけ、見出しを押して並べ替えられるようになる。並べ替えの実行はデータ側に投げられるので、Repository がその指定を受け取って処理する。
columns はもう1か所ある
layout.columns（1行あたり何項目並べるか）は別物。名前が同じだけで、意味も書く場所も違う。混ざりやすいので、下の「よくある間違い」も見ておくとよい。
書けるキー
| キー | 書く場所 | 型 | 必須 | 既定値 | 有効なページ種別 | 説明 |
|---|---|---|---|---|---|---|
table | crudPage | object → table | 任意 | — | crud | The results table. |
table | masterPage | object → table | 任意 | — | master | The results table. |
table | reportPage | object → table | 任意 | — | report | Detail columns (number columns print right-aligned). |
table | searchPage | object → table | 任意 | — | search | The results table. |
columns | dashboardItem | array → column | 任意 | — | dashboard | Columns for a table card. |
columns | field | array → column | 任意 | — | crud dashboard detail form master report search wizard | Child-row grid columns, for type: subTable (master-detail). The field's value is then a list of records. |
columns | layout | integer | 任意 | 1 | crud dashboard detail form master report search wizard | Items per row on wide layouts. |
columns | table | array → column | 任意 | — | crud master report search | — |
label | action | string | 必須 | — | crud dashboard detail form master report search wizard | — |
label | column | string | 必須 | — | crud dashboard detail form master report search wizard | — |
label | field | string | 必須 | — | crud dashboard detail form master report search wizard | — |
label | filter | string | 必須 | — | crud dashboard master report search | — |
label | menuItem | string | 任意 | — | すべて | — |
label | option | string | 必須 | — | crud dashboard detail form master report search wizard | — |
label | optionsSource | string | 任意 | "name" | crud dashboard detail form master report search wizard | Field of a row to show. |
label | reportGroup | string | 必須 | — | report | Heading label shown next to the group's value. |
width | column | number | 任意 | — | crud dashboard detail form master report search wizard | Fixed width in logical pixels; omit for flexible. |
sortable | column | boolean | 任意 | false | crud dashboard detail form master report search wizard | — |
format | column | string （currency / percent / date / wareki / postal / mask ほか） | 任意 | — | crud dashboard detail form master report search wizard | Display formatter name (open string). Built-ins: currency, percent, date, wareki, postal, mask. |
format | dashboardItem | string （currency / percent / date / wareki / postal / mask ほか） | 任意 | — | dashboard | Display formatter for a metric value (open string). Built-ins: currency, percent, date, wareki, postal, mask. |
format | field | string （currency / percent / date / wareki / postal / mask ほか） | 任意 | — | crud dashboard detail form master report search wizard | Display formatter name (open string). Built-ins: currency, percent, date, wareki, postal, mask. |
この表は spec/reference.json から生成している（JSON Schema が正）。手元では npx hatake reference <キー名> で同じものが引ける。
近い例
例は丸ごと写して直すのが一番速い。以下は CI で検証済み（そのまま動く形）。
| ファイル | 種別 | 画面 | どういうときに使うか |
|---|---|---|---|
customer_master.yaml | crud | 顧客マスタ | 検索して一覧に出して、その場で登録・修正・削除まで面倒を見る画面が欲しい |
dept_master.yaml | master | 部門マスタ | コードと名前だけの小さなマスタを、最小の定義でメンテしたい |
product_search.yaml | search | 商品照会 | 検索して一覧を見るだけ（登録も更新もさせない）画面が欲しい |
customer_detail.yaml | detail | 顧客詳細 | 1件の内容を読み取り専用で表示したい（一覧から開く先） |
order_entry.yaml | form | 受注入力 | ヘッダと明細行を1画面で入力して、まとめて保存したい |
order_entry_paged.yaml | form | 受注入力（明細別テーブル） | 明細が何百行もあるので、子テーブルから外部キーで引いてページングしたい |
sales_dashboard.yaml | dashboard | 売上ダッシュボード | 件数・金額・グラフのカードを並べて、まず数字を見せたい |
sales_report.yaml | report | 売上明細表 | 一覧の印刷版が欲しい。顧客ごとに小計を出して、CSV も落としたい、紙にも刷りたい |
roles_app.yaml | app | 人事管理 | 見せる相手を役割で変えたい（画面ごと隠す・列や項目だけ隠す・押せる人を絞る） |
よくある間違い
ページ直下に columns を書く
なぜ駄目か 列は一覧（table）の持ち物。columns が有効なのは table / dashboardItem / field（明細）の中だけ。
こう直す table.columns に入れる。layout.columns（1行あたりの項目数）とは別物なので混同しないこと。
page:
type: search
id: order_search
title: 受注照会
repository: orderRepository
columns:
- { field: orderNo, label: 受注番号 }page:
type: search
id: order_search
title: 受注照会
repository: orderRepository
table:
columns:
- { field: orderNo, label: 受注番号 }form / detail / wizard / dashboard に table を書く
なぜ駄目か table（一覧）を持つのは crud / master / search / report だけ。単票やステップ入力は1件を扱うので一覧を持たない。
こう直す 一覧も要るなら crud にする。1件の中に明細行を持ちたいだけなら、field を type: subTable にして columns を書く（親子・明細）。
page:
type: form
id: order_entry
title: 受注入力
repository: orderRepository
table:
columns:
- { field: productName, label: 商品 }page:
type: form
id: order_entry
title: 受注入力
repository: orderRepository
form:
sections:
- fields:
- field: lines
label: 明細
type: subTable
columns:
- { field: productName, label: 商品 }
- { field: qty, label: 数量, type: number }spec/pitfalls.json から生成。各項目は CI で検証済み（間違いは本当に落ち、正しい方は本当に通る）。手元では npx hatake pitfalls <キー名>。
実物を見る
デモアプリの「受注照会」がこれを使っている。 デモを開く