UX Spec

Sites Breadcrumbs

Amy TangJul 11 2026
Open Spec Changes
No dedicated OpenSpec change(display convention; rule lives in the consumer specs + design docs)
Prototype
device-picker-dialog-demo.html(以 Design Pattern: Device Picker 為例)
Figma
Dev Mode for Developers(以 Design Pattern: Device Picker 為例)
View Mode for Managers(以 Design Pattern: Device Picker 為例)

Visual basis: vortex-1.0 — verify behavior / copy / structure, not pixel style.

Context

Why we're building this

Across the VORTEX Portal several surfaces must show where a device lives — which site, down its area hierarchy — in a space too narrow for the full path. A device row in the Device Picker result list, a camera in Customized View edit mode, and the Alarm source list all need the same answer: render the device's site path as a single-line breadcrumb, and when it does not fit, truncate it by one shared rule.

Documenting that rule once — as a convention, not per surface — keeps the consumers consistent and gives QA a single contract to verify against. That matters most for the Alarm source list, which has no key screen of its own: the developer built it straight from this rule, so the rule is the spec QA checks it by.

Section 01

截斷規則

一個 device 的所在位置以 site 路徑呈現:從根層一路接到最末層(該 device 所屬的 site / area)。當容器夠寬就完整顯示;不夠時,依固定優先序逐步截斷,直到放得下。

真實範例(以 Device Picker 結果列為例)—— 裝置依所屬 site 分組,每組上方一條 breadcrumb 標頭:

bc-example
Device Picker 結果列的 site 分組 breadcrumb 標頭 — 最末層葉為白色、上層灰色以「>」相接(以 Design Pattern: Device Picker 為例)

優先序 Priority

由高到低(越高越不會被截斷):

  1. 最後一層(當前 site/葉) — 永遠完整顯示,不截斷。
  2. 第一層(root branch) — 盡量完整顯示。
  3. 倒數第二層 — 次優先。
  4. 中間層級 — 最先被截斷。

截斷步驟 Steps

逐步執行,直到內容放得下容器寬度:

步驟 動作 範例
0 全部顯示 USA branch > San Francisco > East area > Building-A > Basement
1 中間層級名稱以 ellipsis 截斷(每個上層最小寬度 40px) USA branch > San Fran… > East a… > Building-A > Basement
2 將最低優先的中間層折疊為「…」(從第二層開始折疊) USA branch > … > East area > Building-A > Basement
3 繼續折疊更多中間層 USA branch > … > Building-A > Basement
4 極端情況:只保留 root + 當前 USA branch > … > Basement

細節 Details

  • 最末層(葉) 永遠以粗體白色顯示、不設寬度上限、永不截斷(葉的區別在顏色,不是更粗)。
  • 根層與中間層為灰色,以「>」分隔符相接。
  • 折疊符「…」不可點擊;hover 時以 tooltip 顯示完整路徑。
  • 分隔符「>」為 12×12 的 icon,不隨空間壓縮。
  • 整條不換行;超出容器範圍即依上表逐步截斷。

驗收條件 QA · Given-When-Then

  • Given 容器寬度足夠,Then 完整顯示整條 site 路徑,不截斷。
  • Given 空間不足,Then 依優先序截斷:最末層與根層保留最久,中間層最先被縮短/折疊。
  • Given 最末層(葉),Then 永遠完整、以粗體白色顯示、不設寬度上限。
  • Given 中間層被折疊為「…」,Then 該符號不可點擊,hover 顯示完整路徑 tooltip。
  • Given 任何情況,Then 整條不換行。
Section 02

使用場景

同一條截斷規則(見 Section 01)套用在三個需要顯示 device 所屬 site 路徑的地方。前兩處有 key screen;第三處沒有出圖,開發時直接沿用前兩處的規則實作。

1 · Customized View(編輯模式)

在自訂 View 的編輯模式裡,每個 Camera 以 breadcrumb 標示它所屬的 site 路徑,方便使用者 在多站環境下辨識來源。

bc-customview
Customized View 編輯模式 — 每個 Camera 以 by-site breadcrumb 標示所屬 site 路徑(key-screen 14)

2 · Device Picker 結果列

Device Picker 右側結果清單依所屬 site 分組,每組上方一條 breadcrumb 標頭(見 Section 01 的截圖)。這是本規則最完整、可直接對照的實例。

詳細結構見 Design Pattern: Device Picker 的「結果清單」一節。

3 · Alarm · Select sources(無 key screen)

System > Alarm > Select sources 透過 Device Picker 挑選來源,選定後的裝置清單同樣以 by-site breadcrumb 呈現。此頁沒有專屬 key screen;開發時直接沿用場景 1、2 的規則。 因此 QA 驗收此頁時,以 Section 01 的截斷規則為準,而非比對截圖。

以截斷規則為準:本頁無 key screen,行為以 Section 01 的規則定義為契約。

Site 階層的另一種呈現

Breadcrumb 是壓成一行的線性路徑。Site 階層還有可展開的樹狀呈現(初始展開層級、 全部展開/收合、搜尋自動展開匹配路徑),其唯一權威定義在 Design Pattern: Tree View,此處不重述。

驗收條件 QA · Given-When-Then

  • Given Customized View 編輯模式,Then 每個 Camera 以 by-site breadcrumb 標示來源,且套用 Section 01 的截斷規則。
  • Given Device Picker 結果列,Then 裝置依 site 分組、每組一條 breadcrumb 標頭,套用 Section 01 的截斷規則。
  • Given Alarm · Select sources 的裝置清單,Then 以 by-site breadcrumb 呈現,行為以 Section 01 的規則為準(無 key screen)。