Struts 2 學習筆記（十一）：主題與模板機制深度解析——從目錄結構到自定義主題的包裝與繼承

Struts 2 所有 UI 標籤核心建立在「主題與模板」機制之上。本文系統梳理模板目錄結構、載入優先級、包裝與繼承兩大自定義主題方式，並分析內建四大主題特性。

模板目錄結構與載入順序

struts2-core-x.x.x.jar 內部 template/ 目錄下有五個子目錄：

• ajax、css_xhtml、simple、xhtml：四大主題目錄，含 ftl/css/js 檔案
• archive：歸檔主題，含 vm 檔案（Velocity 模板）

Struts 2 強力推薦 FreeMarker（ftl），而非 Velocity。模板目錄名由常量 struts.ui.templateDir 指定（預設 template）。載入順序：

1. Web 應用 /template/主題名/模板檔.ftl
2. CLASSPATH /template/主題名/模板檔.ftl（即 jar 內）

可用常量 struts.ui.templateSuffix 切換模板技術（ftl/vm/jsp），但 vm/jsp 需自行提供完整實作。

自定義主題兩大靈活方式

1. 利用載入優先級覆蓋（最簡單）

將自定義模板放入優先級更高的目錄，如 WEB-INF/classes/template/xhtml/text.ftl 將覆蓋 jar 內同名檔案。

2. 包裝現有主題

如 xhtml/combobox.ftl：

<#include "/${parameters.templateDir}/${parameters.theme}/controlheader.ftl" />
<#include "/${parameters.templateDir}/simple/combobox.ftl" />
<#include "/${parameters.templateDir}/xhtml/controlfooter.ftl" />

在 simple 基礎上包裝 header/footer。限制：仍需為每個 UI 組件提供完整模板檔案。類比裝飾模式（BufferedInputStream 包裝 InputStream）。

3. 繼承現有主題（最高效）

建立新主題目錄（如 custom/），僅覆寫需修改的模板（如 select.ftl），並在目錄下建立 theme.properties：

parent=xhtml

使用時：<s:form theme="custom">。表單下 select 用自定義模板，其餘沿用 xhtml。Struts 2 內建 ajax 主題即繼承自 xhtml。

四大內建主題特性對比

simple

最基礎，僅對應簡單 HTML 元素，不生成額外內容，甚至比 Struts 1 html 標籤更弱。

xhtml（預設主題）

對 simple 進行包裝與擴展（繼承）。特性：

1. 標準兩欄表格佈局（textfield、select 等）
2. 每個標籤有 label 屬性，預設左側顯示，可用 labelposition 調整
3. 自動輸出後端驗證錯誤或 JS 前端驗證錯誤

含 head.ftl 引入 JS 庫（如 Dojo）。

css_xhtml

擴展 xhtml，加入 CSS 樣式控制特性。

ajax

擴展 xhtml，每個標籤增加 Ajax 支援（基於 Dojo + DWR）。新增特性：

1. Ajax 客戶端驗證
2. 遠程表單異步提交
3. 進階 div 標籤支援局部更新
4. 進階 a 標籤支援動態載入並執行遠端 JS
5. 支援 Ajax 的 tabbedPanel
6. 提供「富客戶端」模型的 Pub-Sub 事件模型

實戰：將驗證錯誤從輸入框上方移至右側

網友常問：預設錯誤顯示在輸入框上方，如何移至右側？

追溯發現：<s:textfield> 用 xhtml/text.ftl → 包裝 simple/text.ftl → 錯誤輸出定義於 controlheader-core.ftl。解法：將這兩個檔案複製至 WEB-INF/classes/template/xhtml/ 修改。該目錄優先級高於 jar 內同名目錄。

模板中的 parameters 物件

文獻常說「表單元素有 form 屬性引用所在表單」，實際指模板中的 parameters 物件。打開 combobox.ftl、controlheader-core.ftl 可見大量 parameters.required、parameters.id 等用法。parameters 代表表單元素屬性集，類似 this：this.id、this.form.id、this.required 等。