CrossTabField.md

CrossTabField - クロス集計

モジュールのデータを「行の項目 × 列の項目」で集計して表にするフィールドです。SQL を書かずに「ステータス × 受注予定月の予測金額」「担当者ごとの件数」のような集計を表示できます。

集計は本体の集計機能でサーバー側 (データベースの GROUP BY) で行われ、権限は一覧と同じです。読めない行は数えられず、読めない項目は行・列・値・条件に使えません。

機能

• 行と列: 行・列とも複数の項目を置ける (列を置かなければ行だけの表)。日付・日時の項目は年・四半期・月・週・日 (日時は時も) の単位でまとめられる
• 値: 件数・重複を除いた件数・合計・平均・最小・最大。複数置くと列の下に並ぶ
• リンク越しの項目: 顧客Id.業種Id.Value のように、リンク先の項目でまとめたり集計したりできる
• 合計: 行ごとの合計・列ごとの合計・総計。列ごとの合計・総計は表に出ている行の分 (表が縦に足し合う)。平均や重複を除いた件数も正しく出るよう、合計は項目を減らした集計を別に実行して求める
• 値の表示形式: 値そのまま / 総計に対する割合 / 行の合計に対する割合 / 列の合計に対する割合
• 値で絞り込み・並べ替え・表示件数の上限: 「合計 2,000 万円以上の業種だけ」「金額の多い順に上位 5 社 × 月」のような表。行の項目に掛かり、その行の合計で評価する (Excel のピボットの値フィルター・並べ替えと同じ)。上限で切れたときは表の下に「全 n 行のうち m 行」と出る
• 検索フィールドと組み合わせる: 検索フィールドの「結果を表示するフィールド」に指定すると、検索条件で絞った行だけを集計する
• スクリプトから表示: 元モジュールを空にしておき、スクリプトで組んだ集計 (ModuleAggregator) を Show で渡して表示できる
• 利用者のカスタマイズ: 設計で許可すると、利用者が表の右上の「集計のカスタマイズ」ボタンで行・列・値などを自分用に変えられる (ブラウザに保存)
• セルのクリック: クリックしたセルの行・列の値を受け取って、明細の一覧へ移動するなどができる

表は与えられた幅と高さの中でスクロールし、見出し・行見出し・合計行は固定されます。表示名はこのフィールドでは出さないので、見出しが必要なら関連付けたラベル (LabelField の RelativeField) を置きます。

デザイナー設定プロパティ

プロパティ	デザイナ表示名	型	説明
SearchCondition	検索条件	SearchCondition	集計する元モジュールと条件。モジュールを空にするとスクリプトの Show 専用
DisplayName	表示名	string	関連付けたラベルが表示する名前
Setting	集計の設定 (行・列・値)	CrossTabSetting	行・列・値・値で絞り込み・並べ替え・表示件数の上限 (専用ダイアログで編集)
ShowRowTotals	行ごとの合計を表示	bool	右端に行ごとの合計を出す (デフォルト: true)
ShowColumnTotals	列ごとの合計を表示	bool	下端に列ごとの合計を出す (デフォルト: true)
ShowGrandTotal	総計を表示	bool	右下に総計を出す (デフォルト: true)
ValueDisplay	値の表示形式	CrossTabValueDisplay	Value / PercentOfTotal / PercentOfRow / PercentOfColumn
CanCustomize	利用者が集計を変更できる	bool	利用者が集計を自分用に変えられる (デフォルト: false。後述)
OnCellClick	OnCellClick	string	セルをクリックしたときのスクリプト (引数 CrossTabCell。cell.CreateSearcher() がそのセルに数えた行の条件を返すので、一覧の SetAdditionalCondition に渡して Reload() すれば明細になる。行・列にリンク越しの項目を置いた表では、その項目を一覧のモジュールにも置く。置いていないとクリック時に「「顧客 / 業種」で分けた表からは明細を表示できません」と、どのモジュールに何を置けばよいかが出る)

割合は件数と合計にだけ掛かり、平均・最小・最大・重複を除いた件数は値のまま表示します。割合の表示形式では、分母にした合計のセル (行の合計に対する割合なら右端の合計列、列の合計に対する割合なら下端の合計行、総計) は 100% になります。

集計の設定 (CrossTabSetting)

タブ	内容
行 / 列	項目。日付・日時の項目なら まとめる単位 (年・四半期・月・週・日・時)。年・四半期なら年度の開始月
値	集計方法・項目・表示名・書式。書式は候補 (整数 / 小数 1 桁 / 小数 2 桁 / パーセント / 通貨) から選ぶか、.NET の書式 (N1 P0 C0 など) を直接入力する。空なら元の項目の書式
値で絞り込み	対象の値・条件・比較する値 (例: 予測金額 ≥ 20000000)
並べ替え / 表示件数の上限	並べ替えの基準 (行・列の項目または値)・降順、集計結果のグループ数の上限

• 合計・平均は数値の項目、最小・最大は数値・日付・日時・時刻・文字の項目に使えます
• 年と四半期は、行・列の項目ごとに設定する「年度の開始月」で区切ります (4 なら 4 月〜翌 3 月が 1 年度。見出しは「2026年度」「2026年度 Q1」)。同じ表に年度の項目と暦年の項目を置けます。週は月曜始まりです
• 選択・リンクの項目は値で分類し、表には表示名 (候補の名前・リンク先の表示項目) が出ます。真偽の項目は「はい」「いいえ」などの設計した文言、数値の項目は設計した書式で出ます。空の値は「(空白)」にまとまります
• 行・列の並びは、選択の項目は候補の順、リンクの項目は表示名の順 (Id やコードの順ではありません)、日付・数値はその値の順です。「(空白)」は最後に並びます
• UTC で保存した日時 (登録日時・更新日時など) は、見ている人のブラウザのタイムゾーンで日・月・年度に区切ります
• 値の見た目は、値の書式 → 元の項目の書式 → 既定 (桁区切り・小数 2 桁まで) の順で決まります。件数は整数です
• 行と列の両方がある表では、値で絞り込み・値での並べ替え・表示件数の上限は行の項目に掛かり、その行の合計 (平均ならその行の平均) で評価します。列の項目は絞らずに全部出し、項目の順に並べます。行が無く列だけの表では列の項目に掛かります
• 割合の分母 (総計・列の合計) も表に出ている行の分です。「上位 10 社が全体の何 %」は出せません
• 表のセル (行の種類 × 列の種類 × 値の数) が 20,000 を超えると、表は描かずに「行や列の項目を減らすか、条件を絞ってください」と出ます。集計の件数そのものには上限はありません

利用者のカスタマイズ

CanCustomize をオンにすると、表の右上に「集計のカスタマイズ」ボタンが出て、利用者が自分用の集計に変えられます (スクリプトの ShowCustomDialog() でも開けます)。ボタンは集計がエラーのときも出るので、変えた設定がエラーになっても直すか「設計に戻す」で戻せます。ListField のカラムカスタマイズと同じ考え方で、変えた内容はその利用者のブラウザにだけ保存されます。全員に同じ集計を見せたいときは設計で設定します。

• 変えられるもの: 行・列・値・値で絞り込み・並べ替え・表示件数の上限・値の表示形式 (デザイナの「集計の設定」と同じ構成)
• 変えられないもの: 元モジュール、検索条件、合計の表示
• 「設計に戻す」で保存した内容を消して設計どおりに戻します。設計と同じ内容にしたときも保存は消えます
• 保存先はブラウザの localStorage で、キーは「モジュール名.フィールド名」です。同じブラウザを使う人の間では共有されます
• 設計が変わって保存内容に無い項目が含まれるようになったら、その項目を捨てて表示します。値が 1 つも残らなければ設計どおりに表示します
• OK のときに、値が無い・合計に文字の項目を選んだ などの不整合があればエラーを出し、ダイアログを開き直します
• 読めない項目を選ぶとサーバーが集計を拒否し、表の位置にエラーが出ます。カスタマイズを開き直すか「設計に戻す」で戻せます
• スクリプトの Show で集計を渡している表では、保存した内容を使わず、カスタマイズも開きません

スクリプト

// 元モジュールを空にしたクロス集計に、受注だけを 担当者 × 年度 で集計して表示する
var searcher = new ModuleSearcher<商談>();
searcher.AddEquals(m => m.ステータス.Value, "受注");

var agg = new ModuleAggregator<商談>();
agg.Where(searcher);
agg.GroupBy(m => m.商談責任者Id);
agg.GroupByYear(m => m.受注予定日);
agg.Sum(m => m.予測金額);
agg.Count("件数");
受注集計.Show(agg, 1);   // 先頭 1 つ (担当者) を行に、残り (年度) を列に

メンバー	説明
Show(aggregator)	スクリプトで組んだ集計を表示する (まとめる項目は全部行)
Show(aggregator, rowCount)	先頭 rowCount 個を行に、残りを列に置いて表示する
SetAdditionalCondition(searcher)	設計の条件に AND で条件を足して集計し直す
Reload()	集計し直す
ShowCustomDialog()	集計のカスタマイズを開く (CanCustomize がオンのときだけ)
AllowLoad	false の間は集計しない (条件を組み立ててから Reload する)
Table	今の表 (行・列・セル・各合計)
LoadError	集計に失敗したときのメッセージ

注意事項

• 集計できるのはテーブルを持つモジュールだけです (QueryField で定義したモジュールは使えません)
• SQLite では日付の列を DATE / DATETIME で宣言してください (TEXT で宣言した列は、日付の単位 (月・四半期・年など) でまとめられず、セルをクリックしたときの明細の絞り込みも効きません)
• リンク先のモジュールの行の閲覧条件は効きません (一覧のリンク表示と同じ)。隠したい項目は元モジュール側の PermissionField で制御します
• ホスト (アプリ) が本体の集計 API に対応している必要があります。対応していないホストでは、表の代わりに「ホストが集計 API を実装していない」旨のエラー (The host does not implement IModuleDataService.AggregateAsync …) が出ます。1.3.39 より前のテンプレートで作ったアプリは 集計 API の結線 を行ってください