SwiftTerm 數據流與監控機制分析報告

1. 概述

本報告旨在總結 SwiftTerm 庫中關於數據輸入 (feed)、內容獲取以及活動監控的核心機制。適用於需要集成終端模擬器並對其數據流進行控制或監聽的上層應用開發。

2. 數據輸入 (Input Mechanism)

終端模擬器的核心驅動力來自於 feed 方法，它負責將原始數據送入解析器。

核心方法

位於 Terminal.swift 及 AppleTerminalView.swift (及其平台子類) 中：

• feed(text: String): 接受字符串輸入，內部轉換為 UTF-8 字節。
• feed(byteArray: [UInt8]) / feed(buffer: ArraySlice<UInt8>): 接受原始字節數組。這是性能最高的方式，適合處理大量數據。

工作流程

• 調用: 外部調用 terminalView.feed(...)。
• 準備 (feedPrepare): 視圖層暫停部分 UI 更新，使搜索結果失效。
• 解析: EscapeSequenceParser 處理字節流，更新內部 Buffer 狀態（如光標移動、字符寫入、顏色變更）。
• 完成 (feedFinish): 觸發 updateDisplay，將變更繪製到屏幕上。

3. 數據獲取 (Data Access)

上層應用可以通過以下方式獲取終端內的文本內容：

• 獲取全部文本:

let content = terminal.getTermContents()

• 獲取選中內容:

let selected = terminalView.getSelectedText()

• 逐行訪問 (高級): 直接訪問 terminal.buffer.lines，這是一個包含 Line 對象的循環列表。每個 Line 包含富文本數據 (CharData)。

4. 活動監控 (Activity Monitoring)

若需監聽終端是否有訊息流動（例如：檢測日誌輸出、判斷是否空閒），應使用 TerminalViewDelegate 協議。

關鍵配置

默認情況下，為了性能優化，詳細的更新通知是關閉的。必須手動開啟：

terminalView.notifyUpdateChanges = true // 默認為 false

關鍵事件

實現 TerminalViewDelegate 協議並監聽以下方法：

• 畫面內容更新 (rangeChanged):

func rangeChanged(source: TerminalView, startY: Int, endY: Int)

當屏幕可視範圍內的字符發生變化時觸發。這是判斷「是否有新消息顯示」的最準確指標。

• 發生滾動 (scrolled):

func scrolled(source: TerminalView, position: Double)

當新數據導致緩衝區滾動時觸發。

• 響鈴 (bell):

func bell(source: TerminalView)

當收到 \\a (Bell) 字符時觸發。

5. 總結

• 輸入: 使用 feed。
• 輸出: 使用 getTermContents 或訪問 buffer。
• 監控: 設置 notifyUpdateChanges = true 並實現 TerminalViewDelegate.rangeChanged。