検索条件を出す
検索欄に並べる条件と、比較のしかた（等値・部分一致・範囲）。
検索欄に並べる条件は search.filters に書く。並べた順に画面に出る。
page:
type: search
id: product_search
title: 商品照会
repository: productRepository
search:
layout: { columns: 3 }
filters:
- { field: name, label: 商品名, type: text, operator: contains }
- field: category
label: カテゴリ
type: select
operator: equals
options:
- { value: food, label: 食品 }
- { value: drink, label: 飲料 }field がデータ側の項目名、type が入力欄の種類、operator が比較のしかた。
operator を省くと部分一致になる
既定は contains。名前や住所を探す欄はそれでいいが、コードや区分を探す欄では意図と違う。「A001」で検索したら「A0012」も出てくる。コードや選択肢は equals を明示する。
日付や金額の範囲は between、複数選択で絞るなら in。
- { field: orderDate, label: 受注日, type: date, operator: between }
- { field: status, label: 状態, type: select, operator: in, options: [...] }検索でしか使えない演算子、条件でしか使えない演算子
operator は検索条件（filters）と表示条件（visibleWhen / enabledWhen）の両方に出てくるが、使える演算子が違う。
| 検索条件 | 表示条件 | |
|---|---|---|
between startsWith endsWith | 使える | 使えない |
isEmpty isNotEmpty | 使えない | 使える |
値を2つ取る（between）ものは入力欄が2つ必要なので検索専用、値を取らない（isEmpty）ものは検索欄として置き場がないので条件専用、と考えると覚えやすい。
検索条件を組み立てるのは Framework、実行するのは Repository
入力された値は「項目・演算子・値」の組として Repository へ渡る。それを SQL や API のクエリにするのは Repository 側。バックエンド（Java / TypeScript）には同じ組を受け取ってクエリを組む道具が用意されている。
select には options が要る
select radio multiSelect は options を書かないと選ぶものが無い。値はデータに入る値、ラベルは画面に出る文字。マスタから引いてくる選択肢は、いまは定義に書けないのでプラグインで足す。
どこに書くか
filters は search の中。ページ直下に書いても効かない（下の「よくある間違い」参照）。search を持てるのは crud master search dashboard report の5種別で、form や detail には検索欄という概念がない。
書けるキー
| キー | 書く場所 | 型 | 必須 | 既定値 | 有効なページ種別 | 説明 |
|---|---|---|---|---|---|---|
search | crudPage | object → search | 任意 | — | crud | The search area: filters plus their layout. |
search | dashboardPage | object → search | 任意 | — | dashboard | Filters applied to every card's query. |
search | masterPage | object → search | 任意 | — | master | The search area: filters plus their layout. |
search | reportPage | object → search | 任意 | — | report | Output conditions, passed to the repository as filters. |
search | searchPage | object → search | 任意 | — | search | The search area: filters plus their layout. |
filters | dashboardItem | object → dashboardItem.filters | 任意 | — | dashboard | Fixed filter values merged into the query. |
filters | search | array → filter | 任意 | — | crud dashboard master report search | — |
operator | condition | string （equals / notEquals / gt / gte / lt / lte / contains / in / isEmpty / isNotEmpty ほか） | 任意 | — | crud dashboard detail form master report search wizard | Built-ins: equals, notEquals, gt, gte, lt, lte, contains, in, isEmpty, isNotEmpty. |
operator | filter | string （equals / notEquals / contains / startsWith / endsWith / gt / gte / lt / lte / between / in ほか） | 任意 | "contains" | crud dashboard master report search | Match operator (open string). Built-ins: equals, notEquals, contains, startsWith, endsWith, gt, gte, lt, lte, between, in. |
options | field | array → option | 任意 | — | crud dashboard detail form master report search wizard | — |
options | filter | array → option | 任意 | — | crud dashboard master report search | Options for select-style filters. |
layout | dashboardPage | object → layout | 任意 | — | dashboard | Card grid width. Defaults to 2 columns. |
layout | search | object → layout | 任意 | — | crud dashboard master report search | — |
layout | section | object → layout | 任意 | — | crud detail form master | — |
layout | wizardStep | object → layout | 任意 | — | wizard | — |
この表は spec/reference.json から生成している（JSON Schema が正）。手元では npx hatake reference <キー名> で同じものが引ける。
近い例
例は丸ごと写して直すのが一番速い。以下は CI で検証済み（そのまま動く形）。
| ファイル | 種別 | 画面 | どういうときに使うか |
|---|---|---|---|
customer_master.yaml | crud | 顧客マスタ | 検索して一覧に出して、その場で登録・修正・削除まで面倒を見る画面が欲しい |
product_search.yaml | search | 商品照会 | 検索して一覧を見るだけ（登録も更新もさせない）画面が欲しい |
customer_form.yaml | form | 顧客入力 | 一覧を持たない単票の入力画面が欲しい（新規と編集を1枚で） |
customer_wizard.yaml | wizard | 顧客登録 | 項目が多いので入力をステップに分けて、1ステップずつ検証したい |
sales_dashboard.yaml | dashboard | 売上ダッシュボード | 件数・金額・グラフのカードを並べて、まず数字を見せたい |
よくある間違い
ページ直下に filters を書く
なぜ駄目か 検索条件は search の持ち物。ページ直下の filters は無い（ダッシュボードのカードの filters は「固定の絞り込み値」で別物）。
こう直す search.filters に入れる。
page:
type: search
id: order_search
title: 受注照会
repository: orderRepository
filters:
- { field: status, label: 状態 }page:
type: search
id: order_search
title: 受注照会
repository: orderRepository
search:
filters:
- { field: status, label: 状態 }spec/pitfalls.json から生成。各項目は CI で検証済み（間違いは本当に落ち、正しい方は本当に通る）。手元では npx hatake pitfalls <キー名>。
実物を見る
デモアプリの「受注照会」がこれを使っている。 デモを開く