Skip to content

パンくず

共通レイアウトのパンくずの段の組み立て、取得中と失敗時の表示、BreadcrumbList への変換

パンくずの定義元は BreadcrumbSegment[] で、各段は name、href、current を持つ。現在地にも URL を保持し、画面では現在地をリンクにせず文字として描く(部品は @koyori-app/ui-vue の Breadcrumb)。AppBreadcrumbs は配列を描画するだけで、ルートや API 応答から段を組み直さない。

段の種類と行き先

段の組み立て方はページの種類で決まる。種類は lib/breadcrumbs.ts の breadcrumbRoute がパス名から引く。

種類 対象ページ 段
static /、/settings/profile、/settings/security、/settings/tokens、/settings/apps 画面名だけの一段
home /{tenant}、my-tasks、calendar、users/{user_id} ホーム > 画面名(/{tenant} はホームのみ)
tenant settings、settings/members、projects/new ホーム > 画面名
project プロジェクトの tasks、settings、reviews、labels、docs ホーム > プロジェクト名 > 画面名(tasks は画面名なし)
document docs/{file_id} ホーム > プロジェクト名 > ドキュメント > ドキュメント名
task tasks/{KEY-N} ホーム > プロジェクト名 > 親タスク名 > タスク名(親が無ければ親の段なし)

ホームは現在のテナントの /{tenant} へ移動する。プロジェクト名はそのプロジェクトのタスク一覧 /{tenant}/projects/{projectKey}/tasks へ、親は同じプロジェクト内のタスク詳細へ移動する。タスク一覧の既定の表示形式は List で、別のボード用ルートは無い。

Guest には tenant 種類の段を出さない。テナント全体の設定と作成の権限が無く、案内先を開けないためである。

親子関係が二段以上深くても、直近の親だけを表示する。

名前の取得元

段の名前は、ページが取得済みの応答から読む。出所は次のとおりである。

段 取得元
テナント 既存のテナント一覧
プロジェクト名 プロジェクト一覧
タスク名 詳細応答
親の名前と連番 サブタスク欄が取得する relations 応答
ドキュメント名 詳細画面が取得するファイルのメタデータ

useBreadcrumbs は QueryCache の通知を購読して同じキーの状態を読むだけで、独自の query observer や通信を作らない。そのため、パンくずのための API は無い。テナントとプロジェクトは現在のルートのパラメータで毎回照合する。

未登録のページ

共通レイアウトのルートは breadcrumbRoute に列挙する。未登録のページとエラーページでは配列を空にし、パンくずの nav を描かない。直前のページの段を引き継ぐ状態を持たないので、登録し忘れても別のタスク名を表示することは無い。

現在 breadcrumbRoute に登録していないページは、サインイン前のページ(/signin など)に加えて /settings/preferences、/settings/theme、/settings/experiments、/{tenant}/gantt である。これらのページにパンくずは出ない。

取得中と失敗時

名前の取得中は骨組みを表示する。ヘッダー内の領域は配列が空のときも高さを保つ。

テナント、プロジェクト、タスク、ドキュメントのいずれかの取得に失敗すると段をすべて落とし、ページ本体のエラー処理には影響させない。親の取得だけが失敗した場合は親の段だけを落とす。現在の親 UUID と一致しない古い relations 応答は使わない。

長い名前と狭い画面

長い名前も省略せず全文を表示する。狭い画面でも全段を一列に保ち、パンくずのリスト内を横スクロールさせて、ページ全体の横幅を広げない。

toBreadcrumbList(segments, origin) は配列を変更しない純関数である。規則は次のとおりである。

  • origin は呼び出し側が明示し、http と https のみ受け付ける
  • 末尾以外の URL を絶対 URL に変換する
  • position は 1 から連番にし、末尾の item は省く
  • 画面に表示する配列と同じ name を使う

未実装と既知の制限

公開プロジェクトのページが無いので、toBreadcrumbList はテスト以外から呼び出さず、HTML に構造化データを埋め込まない。将来公開ページを用意するときは、そのページの公開可否と origin を決めてから利用する。HTML へ埋め込む場合の script 用エスケープは、このオブジェクトへの変換とは別に実装する必要がある。

決定の記録

日付 決定 理由
2026-09-09 親は直近の 1 段だけを表示する 祖先を順に取得する通信を増やさず、直近の親へ移動を繰り返せば上位へ辿れる

Type to search…

↑↓ navigate↵ selectEsc close