# 【Tutorial】UI Tree 概念介紹

## 簡介

**UI Tree** 是使用 Venom 進行應用程式操作時的重要核心概念。它提供了一個層級化的框架，幫助開發者組織和操作應用程式中的各種 UI 元素，例如按鈕、文字框和列表。UI Tree 作為 **UI Automation** 的基礎，支持精確定位和操控目標元素，從而實現高效的自動化操作。

## 關於 UI Tree

**UI Tree** 是應用程式 UI 的階層結構，用來表示 UI 元素之間的邏輯關係，而每個元素都被稱為 **節點**，節點之間的父子關係構成了整體結構。

### 節點的特性
1. **層級結構**：每個節點都有父節點和子節點，形成完整的樹形結構。
2. **多樣性**：節點可代表按鈕、列表項目或輸入框等各種 UI 元素。
3. **可操作性**：透過節點，開發者可以執行點擊、拖動、輸入文字等操作。

### 與 Venom 的關聯
Venom 的 `host-object-model` API 是操作 UI Tree 的核心工具，通過它可以：
- **獲取 UI 元素**：從結構化的樹中定位目標節點（參見 [取得應用程式上的畫面內容](https://hackmd.io/@oolabsoftwarear/rJmW0WHLJl)）。
- **操作 UI 元素**：執行點擊、滾動或設置值等操作（參見 [透過 Venom 操作應用程式](https://hackmd.io/@oolabsoftwarear/By_VSpVIye)）。
- **監控 UI 變化**：實時追蹤節點的屬性變更，例如位置或名稱的更新（參見 [UI 在螢幕上的變化](https://hackmd.io/@oolabsoftwarear/rJ9SVaEUye)）。

## 如何遍歷 UI Tree

Venom 提供方法來操作 UI Tree，開發者可以使用 `traverseTree` 遍歷整棵樹，或者通過 `find` 方法定位特定的節點。

**範例**：使用 `traverseTree` 遍歷所有節點

filesExplorer.traverseTree((node) => {
    console.log(`Node ID: ${node.id}, Name: ${node.name}`);
});

**範例**：使用 `find` 方法定位特定節點

const targetNode = filesExplorer.find((element) => element.name === 'TargetFileName');
if (targetNode) {
    console.log(`Found node with ID: ${targetNode.id}`);
}

## 關於 UI 樹的範圍
Venom 提供了樹狀範圍的種類 ``UITreeScope`` 給開發者使用，請使用合理的範圍以減少效能浪費。

#### 以下為 `UITreeScope` 的範圍種類：
- **Element**：僅獲取當前節點。
- **Children**：獲取當前節點及其一層的子節點。
- **Subtree**：獲取當前節點及所有子節點。