Design Pattern: Tree View

一個通用樹狀列表元件，顯示巢狀階層資料。元件本身不認得「Site / Area / Camera」，只認得「節點」與「種類（kind）」——icon、空狀態文案、業務語意都由使用端透過資料與設定傳入。

下圖為 Tree View 的預設狀態（以 Sites 為例）：

節點類型 Node types

箭頭由「節點種類」決定，不由當下有無子項決定 Chevron is per kind

依據是 add-tree-view-component 的 Node-Kind-Driven Behavior：節點行為由它的 kind 決定（expandable / allowedChildren / terminal），不由它在樹中的深度決定；同一份 spec 的 mixed-kind 情境也明確寫著終端種類不顯示 chevron。「不由當下有無子項決定」是這套宣告的必然結果 —— kind 是靜態宣告，當下有幾個子項是資料，兩者無關。因此：

這條規則取代已上線的舊規則。 已 deploy 的 tree-view-navigation spec 寫的是「chevron 用於有子項的節點」；add-tree-view-component 已用 MODIFIED 覆寫該條要求，改成依 kind 判斷、並明訂箭頭不隨子項增減而出現或消失。因此各頁現行實作只在有子項時畫箭頭是預期的落差，不是本規則的例外。

也就是說「無箭頭」不等於「目前沒有子項」，而是「這個種類不會有子層」。真正空的容器節點會轉為空容器 Empty Container 狀態（文字與 icon 變淡，見下方節點狀態表），但箭頭仍在、仍可展開；「空」的判斷依據見下一小節，展開後是否出現一列空提示行則依 profile 而定（見下方邊界表）。

「空容器」看的是有沒有直屬資源，不是樹上有沒有子節點 Empty means holds nothing

變淡與空提示行是兩件事，判準不同，不要混為一談：

差別只在資源不是樹上節點的場域才會顯現：

• View / Floorplans sidemenu：camera、floor plan 本身就是節點，「沒有子節點」與「什麼都沒有」是同一件事，兩個判準結果相同。
• site tree（Site Management 主樹、Manage Device Access sidemenu）：樹上只有 Site / Area，指派到節點上的 device 不以節點呈現。所以一個有 10 台 camera、但沒有 Area 的 Site 不會變淡 —— 它有東西，只是那些東西不在樹上。這時變淡承載的是樹本身看不出來的資訊：這個節點是真的空的。

因此同一個節點可以「不變淡、但展開後也沒有任何列」：不變淡是因為它有直屬 device，沒有列是因為它沒有子節點（site tree 又不提供空提示行文案）。

資源只算直屬：有子孫的節點本來就有子節點，不會落入空容器的判斷。

原型現況。 VORTEX-1.0 demo（TreeViewList-demo.html）已依本判準更新：變淡同時看子節點與直屬資源，並以一個「有 device、沒有子 Area」的節點示範不變淡。Manage Device Access 的原型目前完全沒有變淡樣式，尚未跟上 —— 以本節為準。

以上依 Figma key screen 確認（2026-08-08）：Floorplans sidemenu 中 Floor 1–Floor 6、Parking lot B1 / B2 等 Floor plan 節點皆有箭頭，其中沒有 camera 的 Floor 4 展開後顯示 No cameras；沒有 floor plan 的 Area Outdoor areas 展開後顯示 No floor plans。View sidemenu 中 Camera 001–Camera 006 皆無箭頭，只有 icon + label。

名稱過長 Long names

節點名稱單行顯示、不換行；放不下時以 ellipsis 截斷（white-space:nowrap + text-overflow:ellipsis）。名稱區域佔滿該列扣掉 chevron / checkbox / icon 之後的全部剩餘寬度，所以可見字數隨縮排深度遞減 —— 越深的節點看得到的名稱越短。

hover 名稱區域顯示完整名稱。 由於名稱區域已涵蓋該列右側的所有留白，實務上只有左側的 chevron / checkbox / icon 不觸發。

只在真的被截斷時顯示。 名稱完整顯示得下時 hover 不出 tooltip —— 顯示一份與畫面上相同的文字是噪音。這與 Sites Breadcrumbs Section 01 的 tooltip 原則一致。

用平台的共用 tooltip 元件，不是瀏覽器原生 title。 樣式與定位（@color-surface07 底、@color-text01 白字、12px Regular、1px @color-outline04 邊框、4px 圓角、內距 8×12、最大寬 320、不吃滑鼠事件、游標下方 24px）由該共用元件定義，權威在 Sites Breadcrumbs Section 01，本節不重列。原生 title 的長相由作業系統決定又有延遲，明確不採用。

節點狀態 Node states

停用是繼承來的通用狀態，本 deck 的四個 profile 都沒有會停用的 Site / Area 節點。 在這個 pattern 裡「disabled」實際活著的用途只有一個：空提示行沿用它的文字色（@color-text06）與 不可互動性。節點層級的停用規則以 OpenSpec add-tree-view-component 為準，本節不擴充；要用它 之前得先有情境（例如權限或鎖定），目前沒有，所以也沒有對應的 key screen。

別和空容器混淆：空容器只是變淡，仍可選取、仍可展開。

輔助線 Indent guides

尺寸 Dimensions

字體：節點文字 Segoe UI 16px Semibold(600) line-height 1；空提示行 Segoe UI 16px Regular(400) line-height 1（不用 italic）。

邊界 Boundaries

空提示行屬 profile 層級的差異，已確定（2026-08-10）。

• site tree（site management 主樹、Manage Device Access sidemenu —— 以站點階層本身為主體的場域）：展開沒有子項的 Site / Area 不顯示任何列，直接接續下一個同層節點。
• View / Floorplans sidemenu（樹的葉層是某一類具體內容）：顯示一列空提示行。Figma key screen 可見 No cameras（沒有 camera 的 Floor plan）與 No floor plans（沒有 floor plan 的 Area）。

差別的依據是「說不說得出少了什麼」。View / Floorplans 的容器底下裝的是一種明確的內容，講得出 No cameras，這一列才有資訊量。site tree 的 Area 底下是尚未建立的下層站點結構，沒有一個具體的東西可以說「沒有」，一列泛用提示只會佔掉一個節點高度。

兩份 OpenSpec 現在是一致的：add-tree-view-component 的空提示行是「當且僅當使用端提供該 kind 的文案才顯示」，並明寫 site tree 不提供文案、不顯示提示行；Manage Device Access 的「no placeholder or hint row is shown」正是同一件事的下游結果。本節只負責記錄各 profile 對應到哪一種。

Token gap：@color-icon29（空容器 icon 變淡）尚未加入 theme-color/index.less，以 OpenSpec add-tree-view-component 為準。

TODO / 未解問題

• @color-icon29 token 尚未落地，需與前端確認補上。

規則 Behaviour

• 點擊節點 label（或 icon）＝ 選取；一次只能選一個（single-select）。
• 點擊選取不改動任何展開 / 收合狀態——使用者能點到的節點必然已經可見（其祖先本來就是展開的），無需再展開。
• 選取後，元件會通知使用端「使用者選了哪個節點」，由頁面接手做後續（例如右側面板顯示該節點對應的內容）。元件本身不決定選取後的行為。
• 點擊 chevron 只切換展開 / 收合、不影響選取（見 Section 03）。

選取的規格本身含「展開被選節點的收合祖先」；但對使用者點擊而言這一步是 no-op（能點到，代表其祖先本來就已展開）。真正會「看到祖先被展開」的情境是程式化定位選取（Section 05，定位藏在收合祖先下的目標）與搜尋命中（Section 04，展開命中節點的祖先）。

下面兩張圖分別為「選取態」與「選取 + hover 同時」（hover 為微暗背景、選取為微亮背景）：

選取「不會」做的事 釐清邊界

點擊選取只做「標記為選取」，完全不碰展開 / 收合狀態：

• 不改變被選取節點本身的展開 / 收合狀態（原本收合就維持收合）。
• 不展開被選取節點的子節點。
• 不收合其他已展開的節點。

驗收條件 QA · Given-When-Then

• Given 點擊某節點 label，Then 該節點成為唯一選取（前一個取消），且展開 / 收合狀態不變。
• Given 點擊 chevron，Then 只切換展開 / 收合、選取不變。

「選取藏在收合祖先下的節點會展開祖先」屬程式化定位選取，驗收條件見 Section 05。

元件與 Token 決策

• 選取態：文字 @color-text01、背景 @color-surface04（內層容器圓角 8px）。

點擊分離 Click separation

[chevron] [icon] [label] [counter]
 ↑ 展開 / 收合         ↑ 選取

• chevron 區：只切換展開 / 收合，不影響選取。
• label / icon / counter 區：只選取，不影響展開 / 收合。
• 整列 hover：整列背景變化。

counter 只出現在上圖的列結構裡，本 deck 沒有定義它計什麼。 它在點擊分離上與 label 同區 （點下去是選取），但「顯示哪個數字、什麼時候出現」目前沒有規則，也沒有任何 profile 在用。 要用之前得先定義，否則實作只能猜。

全部展開 / 全部收合

頂部節點計數列（「N Sites」）右側的單顆按鈕，即為「全部展開 / 全部收合」切換：

這是兩態切換，判定基準是「樹是否已全部展開」，不是「是否有任何節點展開」：

因此部分展開的樹按下按鈕是繼續展開剩下的，不是收合。這讓「一鍵看到全貌」在任何中間狀態下都只需按一次；代價是沒有「一鍵回到全收合」的捷徑，除非先展開全部。

停點與判定基準必須成對設定。 判定「已全部展開」時列入的節點範圍，必須與「全部展開」實際會展開的範圍一致。若 profile 設了停點卻仍以全樹判定，按鈕將永遠停在 Expand all、無法收合。

驗收條件 QA · Given-When-Then

• Given 點擊 chevron，Then 切換該節點展開 / 收合、選取不變。
• Given 點「全部展開」，Then 展開到設定的停點種類為止。
• Given 樹為全收合或部分展開，Then 按鈕顯示為 Expand all（chevrons-down），且點擊後展開至停點。
• Given 樹已全部展開，Then 按鈕顯示為 Collapse all（chevrons-up），且點擊後全部收合。

搜尋的過濾、命中 highlight、自動展開祖先、展開狀態快照 / 還原、以及 No Matches Found 空狀態，都是元件內建的行為；使用端只提供搜尋輸入框。以下定義這些互動規則。

搜尋流程 Flow

1. 使用者輸入 → 首次輸入時快照當前展開狀態。
2. 即時過濾（不分大小寫）。
3. 自動展開命中節點的所有祖先。
4. 命中文字以 highlight 顯示；無關分支隱藏。

過濾規則 Filter rules

清除搜尋 Clear

無命中 No Matches Found

搜尋不到任何節點時，整個樹區換成空狀態：240 寬的區塊在列表區垂直置中，由上而下是 64×64 插圖、標題、說明文字，三者間距 8px、皆置中對齊。

標題與說明的文字由使用端傳入（見下方邊界表），版面與樣式則屬本元件。

狀態與邊界

驗收條件 QA · Given-When-Then

• Given 輸入關鍵字，Then 只顯示命中節點及其祖先，其餘隱藏。
• Given 命中節點，Then 自動展開其祖先，且命中文字 highlight。
• Given 清除搜尋，Then 展開狀態恢復成搜尋前的快照。
• Given disabled 節點被命中，Then 顯示但維持不可選。
• Given 搜尋無任何命中，Then 顯示「No Matches Found」空狀態並隱藏所有節點。
• Given 選取的節點被搜尋過濾掉，Then 選取邏輯上保留，清除搜尋後恢復可見。

外部事件（例如點擊地圖上的 camera marker）可觸發 tree 選取特定節點。

流程 Flow

1. 外部觸發「定位並選取」某個目標節點。
2. 若在搜尋中，先清除搜尋、恢復展開狀態。
3. 找到目標節點 → 展開所有祖先 → 選取 → 平滑捲動到可見區。

狀態與邊界

驗收條件 QA · Given-When-Then

• Given 外部觸發定位一個收合的深層節點，Then 展開其祖先、選取、捲動到可見。
• Given 目標節點不存在，Then 靜默失敗（無錯誤、畫面不變）。
• Given 搜尋中觸發定位選取，Then 先清除搜尋並恢復展開，再執行定位選取。

TODO / 未解問題

• 鍵盤導航（方向鍵 / Enter / 空白鍵）目前不實作，設計上預留未來擴充空間。

同一個元件、不同資料與設定，撐起平台上數種樹狀情境。元件不綁定業務語意——icon 由使用端**依節點種類（kind）**傳入。

Icon 規則：Site / Area 節點一律無 icon；icon 只用來區分不同「種類」的節點。因此：Site Management 只有 site / area → 完全無 icon；View 多了 Camera 種類 → Camera 有 icon；Floorplans 有 Floor plan + Camera 兩種 → 兩者各有 icon。

Site Management Sidebar 五層、無 icon

Site > Area × 4，純文字節點（無 icon）。這是 tree-view 的首發場景，採單選、fill 選取樣式。

View Sidebar 最多六層、Camera 有 icon

Site > Area × 4 > Camera——Camera 直接掛在最深的 Area 底下（無 Floor plan 層）；Camera 由使用端依節點種類傳入 icon。

Floorplans Sidebar 最多七層、Floor plan / Camera 有 icon

Site > Area × 4 > Floor plan > Camera——比 View 多一層 Floor plan；Floor plan 與 Camera 由使用端依節點種類傳入對應 icon。

以上是「側邊欄」情境；同一個元件也用在對話框內的挑選器：

Manage Device Access by Site 多選兩態

以 Site / Area 為單位授權的權限設定也用 Tree View，採多選模式：每列 chevron 後有 20×20 兩態勾選（未勾 / 勾選；站點節點無半選，2026-07-16 起）。勾或取消一個節點會連同整個子樹一起連動（對稱 cascade）；祖先永不因子孫自動連動。checkbox 的存取語意（該節點「自己的直屬裝置」是否保有存取、隨裝置狀態即時推導）與 All sites 列保留三態的例外，規則以 Manage Device Access by Site spec 為權威，本節不重列。

此場域只有 Site / Area 兩種容器節點，因此樹上每一列都顯示 chevron——這是 Section 01 的 kind 規則直接套用的結果，不是本場域的覆寫。（樹以外的 All sites 列不是節點，沒有 chevron，見 Manage Device Access by Site。）

兩態與 OpenSpec 目前不一致，spec 待更新。 add-tree-view-component 的 Multi-Select Mode 仍寫「20x20 three-state checkbox」，那是 2026-07-16 兩態決議之前的文字。站點節點的兩態以 Manage Device Access 那份 deck 為準（原型亦為兩態）；本 deck 只記錄這個落差，不自行改寫 spec。

空提示行：不顯示。 此場域屬 site tree，展開沒有子項的 Site / Area 之後不出現任何列，直接接續下一個同層節點。這與 Site Management 主樹一致，也是 Section 01 邊界表所定的 site tree profile —— 不是本場域的覆寫，也不是實作缺口。

初次載入的展開與選取 Initial state per profile

初始展開層級與初始選取是各 profile 自己的設定，不是元件的預設行為。元件本身未設定初始 展開時，所有 root 節點皆收合（見 Section 03）。

兩者是獨立的設定：View 全收合卻仍選取第一個 Site —— 那個 Site 是 root，本來就看得到， 所以不需要展開任何節點（點擊選取不改動展開狀態的規則見 Section 02）。

這四組值的出處：由設計於 2026-08-18 確認，本 deck 是唯一記錄處。 OpenSpec 只規範 機制（defaultExpandToKind，以及未設定時全部 root 收合），沒有規範任何 surface 的實際值； 初始選取更是連機制都還沒有 —— 元件目前沒有「載入時選取某個節點」的設定，所以 View 的 「選取第一個 Site」在實作上會落在使用端。這一點需要補進 OpenSpec，見下方 TODO。

狀態與邊界

已移除的使用場景(2026-08-08): Site Management 的「Move to」目標挑選器原本列在此節,採單選 + outline 選取樣式。該挑選器已不再使用 Tree View,因此從使用場景移除;它改用單選 Site picker，規格見 Sites Related Pages 的 Section 09；使用情境與 key screen 見 Site Management spec US4。其 Figma 節點也已從檔案移除(以 get_metadata 確認)。

TODO / 未解問題

• 初始選取需要一條 OpenSpec 規範。 上表的四個展開值對應 defaultExpandToKind，但 「View 載入時選取第一個 Site」目前沒有對應的元件能力。要決定它是元件的設定（例如 defaultSelect）還是使用端的責任（頁面載入後自行呼叫選取）—— 這會影響 RD 怎麼實作。

驗收條件 QA · Given-When-Then

• Given Site Management 資料（最多五層、無 icon），Then 正確渲染且無 icon。
• Given View 資料（最多六層，Camera 有 icon），Then 依節點種類顯示 Camera icon。
• Given Floorplans 資料（最多七層，Floor plan / Camera 有 icon），Then 依節點種類顯示對應 icon。
• Given 一個沒有任何子項的 Area（Site Management 或 Manage Device Access），Then 該列仍顯示 chevron 且可點擊展開。
• Given View / Floorplans sidemenu 的 Camera 節點，Then 不顯示 chevron。
• Given Floorplans sidemenu 中沒有 camera 的 Floor plan，Then 仍顯示 chevron；展開後顯示 No cameras 空提示行。
• Given Floorplans sidemenu 中沒有 floor plan 的 Area，Then 仍顯示 chevron；展開後顯示 No floor plans 空提示行。
• Given 在 site tree（Site Management 主樹或 Manage Device Access sidemenu）展開一個沒有子項的容器節點，Then 不顯示任何列，直接接續下一個同層節點。
• Given site tree 中一個沒有 Area、但有直屬 device 的 Site，Then 該列不以空容器樣式變淡（箭頭仍在、仍可選取），展開後也不顯示任何列。
• Given site tree 中一個沒有 Area、也沒有任何直屬 device 的 Site / Area，Then 該列以空容器樣式變淡，箭頭仍在、仍可選取。
• Given Floorplans sidemenu 中一個沒有 floor plan 的 Area（資源本身即節點），Then 兩個判準結果相同：該列變淡，展開後顯示 No floor plans。
• Given 初次載入 Site Management sidebar，Then 樹全收合且沒有任何節點被選取。
• Given 初次載入 View sidemenu，Then 樹全收合，但第一個 Site 為選取態。
• Given 初次載入 Floorplans sidemenu，Then 展開到 Floor plan 那層（Floor plan 列可見、Camera 收合），且沒有任何節點被選取。
• Given 初次載入 Manage Device Access sidemenu，Then 樹全展開且沒有任何節點被選取。
• Given 在 View / Floorplans sidemenu 展開一個沒有子項的容器節點，Then 顯示一列 disabled 的空提示行，文字由使用端依 kind 提供。
• Given 節點名稱長度超過可用寬度（任一場域），Then 以 ellipsis 截斷，且 hover 名稱區域顯示完整名稱（規則見 Section 01）。
• Given 節點名稱完整顯示得下，Then hover 不顯示 tooltip。