編輯 | 究查 | 歷程 | 原始

UI 視圖與介面呈現模組 (UI View) 深度分析

CB_IMGPSScanImp.pas 中,「UI 與介面呈現模組」主要負責與使用者的視覺互動,這是作為 ActiveX 控制項的核心表現形式。它管理了表單的佈局、多國語言切換、快捷鍵操作以及各種滑鼠拖拉 (Drag and Drop) 與捲動行為。

以下是針對 UI View 模組的深度組成與分類分析:


1. 核心版面與容器管理 (Layout & Container Management)

職責:定義整個 ActiveX 控制項的視覺區塊,並透過階層式的 Panel 進行排版管理,確保在不同解析度下能正確顯示。
核心實作特性
* ActiveX 窗體繼承TCB_IMGPSScanX 繼承自 TActiveForm,並實作 ICB_IMGPSScanX 介面,是所有 UI 元件的根容器。
* Panel 排版系統:使用大量的 TPanel (如 Panel1, Panel2, Panel9 等) 與 TSplitter (如 Splitter1, Splitter2) 來分割畫面:
* 頂部/底部工具列:放置各種操作按鈕 (TBitBtn, TButton)。
* 左側樹狀區:放置文件結構清單 (TreeView1)。
* 右側工作區:通常包含影像預覽或細節設定面板 (Panel9, ScrollBox1)。
* 動態模式切換:透過 DisplayModeGoViewMode 根據不同的視圖模式 (VMode) 動態調整右側影像預覽區塊的排列方式 (如 1x1, 1x2, 2x2 等),並控制各 imgp (Panel) 的顯示與隱藏。

2. 影像預覽與互動視窗 (Image Viewer & Interaction)

職責:提供高效能的影像顯示功能,支援大圖縮放、拖曳平移、局部放大以及多頁縮圖並排顯示。
核心實作特性
* Envision 影像元件:深度依賴 EnImgScr (TImageScrollBox) 來處理大型 TIFF/JPEG 影像的渲染與捲動。
* 多圖預覽管理
* 主影像 (ISB1) 與縮圖陣列 (ISB2 ~ ISB8)。
* 背景生成黑白影像 (ISB_BW) 供內部條碼辨識或影像處理使用,而不影響前端彩色顯示。
* 動態建立/釋放:CreatePreViewISBFreePreViewISB 負責根據案件頁數動態產生縮圖物件。
* 滑鼠行為模式 (Mouse Mode)
* 透過 ViewMouseMode 函式切換 TImageScrollBox 的狀態,例如:放大鏡 (mmAmplifier)、框選縮放 (mmZoom)、手形拖曳 (mmDrag)、旋轉 (mmR90, mmR180, mmR270) 或刪除 (mmDelete)。
* 對應工具列按鈕 (FC0 ~ FC6) 的點擊事件 (FC0Click ~ FC6Click) 來切換這些游標模式。
* 滑鼠與滾輪事件
* 處理自定義的滾輪捲動 (WMMOUSEWHEEL),同步捲動 ScrollBox1 或放大縮小影像 (ZoomPercent)。
* 處理影像上的點擊 (ISBClick) 與拖拉排序 (ISBDragDrop, ISBDragOver)。
* 在影像上繪製選取框 (PaintShape, FreeShapeobj)。

3. 案件與文件樹狀檢視 (Case & Document TreeView)

職責:以階層式樹狀結構呈現當前掃描或下載的「案件 -> 文件 -> 頁面」,並提供豐富的右鍵選單功能以管理這些節點。
核心實作特性
* TTreeView 結構維護
* NewTreeNode:頂層節點(如:新件、異動件)。
* MyTreeNode1:案件層級 (CaseID)。
* MyTreeNode2:文件層級 (DocNo/DocDir)。
* MyTreeNode3:表單/頁面層級 (FormID)。
* 視覺狀態回饋:依據節點的狀態改變圖示 (ImageIndex),例如:未配號、檢核失敗、完成檢核、或標記為被引用 (GetUseCase) 的文件。
* 節點資料綁定與更新
* 利用 DrawDocItem2 根據實體的 .dat 設定檔重新長出整棵樹。
* 利用 NewTreeNodeRefresh, MyTreeNode1Refresh 等更新節點後方的筆數或頁數統計。
* 右鍵選單與節點操作
* 根據選中的節點層級,動態顯示/隱藏 PopupMenu1 的選項 (PopupMenu1Popup)。
* 支援在樹狀圖上的拖拉移動 (TreeView1DragDrop) 以改變影像歸屬。

4. 多國語言與本地化引擎 (I18N & Localization)

職責:將 UI 介面上的所有寫死字串抽離,透過外部設定檔實現多國語言的動態切換。
核心實作特性
* 語言檔載入:在初始化時透過 HTTP/FTP 下載最新的語言包 (Language.LngLngPath)。
* 動態介面翻譯InitialLanguage 函式。
* 利用 TMemIniFile 讀取語言檔。
* 遍歷表單上的所有元件 (Components),判斷其類型 (TButton, TBitBtn, TMenuItem, TLabel, TListView, TRadioGroup 等)。
* 將元件的 Name 作為 Key 去 Ini 檔中尋找對應的翻譯字串,並替換其 CaptionHint

5. 系統狀態與進度回饋 (Status & Progress Feedback)

職責:在進行耗時的網路傳輸、影像處理或資料庫比對時,鎖定 UI 並給予使用者明確的等待提示,避免重複操作。
核心實作特性
* 全域 UI 鎖定 (DataLoading)
* 當執行耗時任務時,將滑鼠游標改為漏斗 (crHourGlass)。
* 停用主要的控制面板 (Panel1.Enabled := False, Panel2.Enabled := False)。
* 顯示中央的進度提示面板 (Panel22Panel8)。
* 動態文字更新:透過 Timer2 定期在進度提示文字 (ShowText) 後方加上點號 (...),營造系統正在運作的視覺效果。
* 狀態列 (StatusBar1):顯示當前版本號 (GetCurrentVersionNo)、登入使用者名稱、引用狀態,以及浮動授權 (License) 的剩餘額度。


💡 未來重構與微服務化建議

若要將此「UI View 模組」進行現代化重構 (例如轉向 Web 介面或更清晰的架構),建議考量以下方向:

  1. MVC / MVVM 架構解耦:目前的程式碼將按鈕點擊事件 (Controller)、資料讀取 (Model) 與畫面更新 (View) 混雜在同一個 Pas 檔中。應將邏輯抽離,讓 UI 只負責「顯示資料」與「轉發命令」。
  2. TreeView 虛擬化 (Virtualization):若案件內包含極多頁面,頻繁的 DrawDocItem2 清空並重建樹狀節點會導致效能低落。建議改用 Virtual TreeView 或資料綁定 (Data Binding) 的方式,只渲染可見節點。
  3. 分離多國語言引擎:將 InitialLanguage 的邏輯獨立為一個全局的 Translator 服務,避免每個 Form 或 Frame 都需要自己實作載入邏輯。
  4. Web 相容性評估
    • 由於深切依賴 TImageScrollBox 的 Windows GDI 渲染與特定的滑鼠狀態 (TMouseMode),若要轉為 Web (HTML5/Canvas),需尋找或實作對應的 Web Image Viewer 套件。
    • ActiveX 特有的 COM 介面 (TActiveForm, safecall) 將被淘汰,改以 WebSocket 或 REST API 提供狀態更新,前端由 React/Vue 等框架接手渲染。