前言：從代碼到運行 — 完成自動完成組件的最後一公里
前九篇已完成自動完成組件的核心邏輯：Facelet 復合組件、JavaScript 事件處理、Java 端監聽器、托管 Bean、數據模型。本文演示如何在 Eclipse + GlassFish 環境中導入、部署、運行該組件，並總結 JSF 2 復合組件 + Ajax 的核心優勢與擴展方向。
1. 環境準備
- Eclipse IDE for Java EE Developers (3.6 Helios 或更新)
- GlassFish Server Tools 插件：Help → Eclipse Marketplace → 搜索 "GlassFish" 安裝
- GlassFish 3.1+ (支援 JSF 2.0/2.1)
- 本文配套源碼目錄結構：
autoComplete/ (Web 專案根目錄)
src/java/ (Java 源碼)
web/ (Facelet、JS、CSS)
web/resources/util/autoComplete.xhtml (復合組件定義)
2. 導入專案到 Eclipse
- File → New → Dynamic Web Project
- Project name: `autoComplete`
- Target Runtime: GlassFish 3.x (Java EE 6)
- Dynamic Web Module version: 3.0 (或 2.5)
- Configuration: Default Configuration for GlassFish
- EAR Membership: 不勾選
- Next → Context root: `autoComplete`、Content directory: `web`、Java source: `src/java`、取消 Generate web.xml
- Finish
3. 關聯 GlassFish Runtime
- 右鍵專案 → Run As → Run on Server
- 選擇 "GlassFish 3.x Java EE 6"
- Finish
4. 運行效果驗證
Eclipse 啟動 GlassFish，部署應用，瀏覽器打開：
`https://localhost:8080/autoComplete/faces/index.xhtml`
操作演示
- 在「Locations」輸入框輸入 `Al` → 下拉列表即時顯示以 `Al` 開頭的虛構國家名 (Albania、Algeria 等)。
- 繼續輸入 `Bar` → 列表縮小為 `Bar` 開頭項目。
- 點擊列表項或鍵盤選中 → 輸入框填入完整名稱、列表隱藏。
- 輸入框失焦 200ms 後列表自動隱藏 (防誤觸)。
5. 核心技術回顧：JSF 2 復合組件 + Ajax 的優勢
| 傳統做法 (JSF 1.x / 手工) | JSF 2 復合組件 + Ajax |
|---|
| 需編寫 `UIComponent`、`Renderer`、`.taglib.xml`、`.tld`、JS 文件、註冊 `faces-config.xml` | 單一 `.xhtml` (Facelet) 定義組件結構、行為、Ajax、JS — **零 Java 基礎設施代碼** |
| Ajax 需手工整合第三方 JS 庫 (Dojo、jQuery、RichFaces) | 內建 `jsf.ajax.request()`、`` 標準化，**無第三方依賴** |
| 組件狀態管理複雜，易衝突 | 命名空間隔離 (`cc.attrs`、`cc.clientId`)，**多實例共存無衝突** |
| JS 與 Java 端耦合緊密 | JS 僅負責觸發 Ajax 傳參，邏輯在 Java 端監聽器，**關注點分離** |
6. 擴展方向：打造生產級自動完成組件
- 最小輸入長度觸發：`` JS 端判斷。
- 防抖/節流優化：`setTimeout` + `clearTimeout` (已實現 350ms) → 可配置化。
- 鍵盤導航：↑/↓ 選擇、Enter 確認、Esc 關閉 (增強 `onkeydown`)。
- 異步數據源：支援 `List`、`List`、JPA 實體、REST 端點 (屬性 `valueExpression`)。
- 模板自定義：`` + `` 插槽，允許調用方自定義下拉項渲染。
- 無障礙 (ARIA)：`role="combobox"`、`aria-expanded`、`aria-activedescendant`。
- 主題樣式化：CSS 變量 / PrimeFaces ThemeRoller 兼容。
- 整合 ``：允許外部 Ajax 行為觸發組件更新 (下篇專題)。
7. 總結
JSF 2 的**復合組件**機制將「組件開發」從繁重的 Java 基礎設施代碼中解放出來，讓開發者專注於**面向聲明的組件定義**：Facelet 標記定義結構，內建 Ajax 引擎處理通信，Java 監聽器封裝業務邏輯，JavaScript 僅作為薄觸發層。自動完成組件僅用 ~200 行代碼 (含 JS/Java/Facelet) 即實現了生產可用的交互體驗，展示了 JSF 2 在**組件化、Ajax 化、可重用**三大維度的工程效能飛躍。
系列延伸閱讀：
【責任編輯：立方】
