# 【Tutorial】UI 在螢幕上的變化

## 說明

使用者在操作應用程式時，畫面必然會隨之發生變化，這些變化可能來自於以下幾種情況：
1. **使用者操作**：例如按下按鈕、輸入文字或拖動元素。
2. **應用程式動態更新**：如自動加載新內容、頁面刷新或資料更新。

這些行為會導致應用程式的 UI 結構發生改變，例如新增、刪除或更新 UI Tree 的節點，進而影響描述檔的匹配效果，可能導致目標元素無法被正確識別。

> 更多關於 UI Tree 的概念，請參考 [UI Tree 文檔](https://hackmd.io/@oolabsoftwarear/ByFompEIke)。

### 描述檔匹配的影響
> 查看更多關於 [描述檔](https://hackmd.io/@oolabsoftwarear/rJmW0WHLJl#%E4%BD%BF%E7%94%A8%E6%8F%8F%E8%BF%B0%E6%AA%94%EF%BC%88Descriptor%EF%BC%89%E5%8F%96%E5%BE%97%E7%95%AB%E9%9D%A2%E5%85%A7%E5%AE%B9) 的說明

當 UI 發生變化，描述檔的匹配數量可能也會改變，這時可註冊相關事件來監控更新。
（可參考 [這裡](#使用-UIChange-事件)）

## 發生變化的例子

以下是一些會引起 UI 變化的典型情境：

1. **頁面刷新**：當頁面重新載入，儘管載入後 UI Tree 的節點相同，但對於 Venom 先前抓取的元素，它們都會變成**過時**的，一樣需要透過 [相關事件](#使用-UIChange-事件) 更新元素。
2. **項目排序變動**：例如當使用者在檔案總管中，更改某檔案的名稱，這時檔案總管會根據新的名稱，對當前資料夾的檔案重新排序，這時便導致 UI Tree 的節點發生變化。
3. **動態載入內容**：例如無限滾動清單會隨著用戶操作新增或刪除項目。

這些情境都會使得 Venom 抓取的元素變得 **過時**，當開發者操作過時元素就會引發錯誤，為避免這種情況，請參考 [如何解決](#如何解決)。

## 如何解決

這些解決方式的最終目的是讓 Venom 能夠及時得知最新的 UI 畫面，確保應用程式狀態與操作保持同步，避免因過時引發錯誤。

### 使用 UIChange 事件

`UIChange` 用於監控 UI 結構的變化，包括節點的新增、移除或屬性更新，從而確保操作始終基於最新的畫面狀態。

**當發生以下情境會觸發事件**：
- 當子節點數量發生變化時。
- 當描述檔匹配的節點數量發生變化時。

**範例**：

filesExplorer.onUIChanged((previous, targets) => {
    console.log('UI 變更前:', previous);
    console.log('UI 變更後:', targets);
});

### 使用 updateCurrentChildren

`updateCurrentChildren` 是一種動態方法，能夠更新當前子節點的狀態，保持 UI Tree 與應用程式的一致性。這對於處理頻繁變化的節點結構特別有效。

**注意**：
- `UITreeScope` 決定了更新範圍：
- `UITreeScope.Element`：僅更新當前節點。
- `UITreeScope.Children`：更新當前節點及其直接子節點。
- `UITreeScope.Subtree`：更新當前節點及所有子節點。

**範例**：

await filesExplorer.updateCurrentChildren();
filesExplorer.children.forEach((child) => {
    console.log(`子節點 ID: ${child.id}`);
});