hatake

表示

ダッシュボードにグラフを出す ​

棒・円などのグラフと、軸に使う項目。

グラフのカードは type: chart にして chart を書く。

yaml
items:
  - id: byCustomer
    type: chart
    title: 顧客別売上
    span: 2
    chart:
      kind: bar
      labelField: customer   # 横軸（凡例）になる項目
      valueField: amount     # 値になる項目
      aggregate: sum         # 同じ顧客の行をまとめて合計

labelField が「何ごとに」、valueField が「何を」、aggregate が「どうまとめるか」。

aggregate を書くかどうかで意味が変わる ​

ここがグラフで一番大事な分岐。

挙動向いているデータ
aggregate を書く同じラベルの行をまとめて1点にする明細（受注1件=1行）をそのまま渡す
aggregate を省く1行=1点になる集計済みの結果を返すエンドポイント

明細データをそのまま渡して aggregate を書き忘れると、同じ顧客が何本もの棒として並ぶ。逆に集計済みのデータに aggregate: sum を書くと二重に足される（ラベルが重複していなければ結果は同じだが、意図が読めない定義になる）。

3種類の kind ​

kind向いているもの
bar項目どうしの大小を比べる（顧客別、商品別）。既定
line時間の推移を見る（日別、月別の売上）
pie全体に対する構成比。項目が5〜6個までのとき

pie は項目が多いと読めなくなる。カテゴリが10個あるなら bar にする。

line を使うなら、ラベルが時系列に並んでいる必要がある。並び順は Repository が返した順なので、sort で並べておく。

幅を取る ​

span: 1 のままだとグラフはほぼ読めない。span: 2 以上にする。layout.columns: 4 の画面なら、グラフは 2、大きく見せたいものは 4（1行占有）が使いやすい。

集計しているのは Framework ではない ​

カードと同じで、集計クエリは投げていない。Repository が返した行を畳み込んでいるだけなので、読む行数は limit（既定 100）で決まる。

「1年分の月別売上」のようなグラフを明細から作ろうとすると、100 件しか読まないのでグラフが途中で切れる。この場合は集計済みの月別データを返すエンドポイントを用意して、aggregate を省いた line で受けるのが正しい形。

valueField を省くとどうなるか ​

件数を数えるグラフ（顧客別の受注件数など）にしたいときは aggregate: count にする。count は値の項目を見ないので valueField は要らない。

yaml
chart: { kind: bar, labelField: customer, aggregate: count }

書けるキー ​

キー書く場所型必須既定値有効なページ種別説明
chartdashboardItemobject → chart任意—dashboardPlot for a chart card.
kindchartstring （bar / line / pie ほか）任意"bar"dashboardChart kind. Open string; built-ins below.
labelFieldchartstring必須—dashboardField holding each point's label.
valueFieldchartstring任意—dashboardField holding each point's value.

この表は spec/reference.json から生成している（JSON Schema が正）。手元では npx hatake reference <キー名> で同じものが引ける。

近い例 ​

例は丸ごと写して直すのが一番速い。以下は CI で検証済み（そのまま動く形）。

ファイル種別画面どういうときに使うか
sales_dashboard.yamldashboard売上ダッシュボード件数・金額・グラフのカードを並べて、まず数字を見せたい

実物を見る ​

デモアプリの「売上ダッシュボード」がこれを使っている。 デモを開く