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

> Documentation Index
> Fetch the complete documentation index at: https://docs.koyori.app/llms.txt
> Use this file to discover all available pages before exploring further.

# パンくず

パンくずの定義元は `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 応答は使わない。

## 長い名前と狭い画面

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

## BreadcrumbList への変換

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

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

## 未実装と既知の制限

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

## 決定の記録

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

Source: https://docs.koyori.app/dev/frontend/breadcrumbs/index.mdx
