Struts 2 透過「主題」機制將標籤渲染為 HTML，預設使用 XHTML 主題（表格佈局）。本文詳細講解如何切換主題、自訂模板（FreeMarker/Velocity/JSP）、建立新主題，以及完整的國際化（i18n）實作流程：資源檔命名、訊息查找順序、標籤庫用法、多語言切換範例。

一、主題模板機制

1. 預設行為

渲染為 XHTML 主題的表格結構：

  Name:
  

2. 指定主題的優先級順序

1. 標籤屬性 theme="..."
2. 包含表單的 <s:form theme="...">
3. 頁面作用域屬性 theme
4. 請求作用域屬性 theme
5. 會話作用域屬性 theme
6. 應用程式作用域屬性 theme
7. struts.properties 中 struts.ui.theme（預設 xhtml）

3. struts.properties 全域配置

# Standard UI theme
struts.ui.theme = xhtml
# Directory where theme template resides
struts.ui.templateDir = template
# Default template type: ftl, vm, or jsp
struts.ui.templateSuffix = ftl

二、主題運作原理

Struts 標籤 + 關聯模板檔 = 最終 HTML

• 每個標籤對應一個模板檔：s:textfield → text.ftl、s:password → password.ftl...
• 模板檔位於 struts2-core-x.y.z.jar/template/{theme名稱}/。
• 預設為 FreeMarker（.ftl），可改用 Velocity（.vm）或 JSP（.jsp）。

三、建立自訂主題

1. 複製現有主題（如 xhtml）到專案類別路徑：WebContent/WEB-INF/classes/template/mytheme/
2. 修改所需模板檔。例如修改 control.ftl 加入表格邊框：

修改 form.ftl 引用新主題的控制模板：
<#include "/${parameters.templateDir}/mytheme/control.ftl" />

struts.properties 設定新主題：
struts.ui.theme = mytheme
struts.ui.templateDir = template
struts.ui.templateSuffix = ftl
四、國際化（i18n）完整實作
1. 資源檔命名規則
bundlename_language_country.properties
# 例：
global.properties          # 預設（英語）
global_zh_TW.properties    # 繁體中文
global_zh_CN.properties    # 簡體中文
global_fr.properties       # 法文
global_es.properties       # 西班牙文
bundlename 可為 Action 類名、介面、父類、Model、Package、struts.properties、global。
2. 訊息查找順序（優先級遞增）

ActionClass.properties
Interface.properties
SuperClass.properties
model.properties
package.properties
struts.properties
global.properties
3. 訪問訊息的四種方式

方式
語法
說明

<s:property>
<s:property value="getText('key')" />
從預設資源包取值
<s:text>
<s:text name="key" />
從 struts.properties 定義的包取值
<s:i18n>
<s:i18n name="pkg.bundle"><s:text name="key"/></s:i18n>
推入指定資源包至值棧
UI 標籤 key 屬性
<s:textfield key="global.name" />
自動查找 label、tooltip 等



五、多語言切換完整範例

1. 資源檔（CLASSPATH 根目錄）
# global.properties
global.heading = Select Locale
global.name = Name
global.age = Age
global.submit = Submit
global.success = Successfully authenticated

# global_zh_TW.properties
global.heading = 選擇語系
global.name = 姓名
global.age = 年齡
global.submit = 送出
global.success = 驗證成功

# global_es.properties
global.heading = Seleccionar locale
global.name = Nombre
global.age = Edad
global.submit = Enviar
global.success = Autenticado correctamente

2. Action 類
// LocaleAction.java - 處理語系切換
public class LocaleAction extends ActionSupport {
    public String execute() { return SUCCESS; }
}

// EmployeeAction.java - 處理表單提交
public class EmployeeAction extends ActionSupport {
    private String name; private int age;
    public String execute() { return SUCCESS; }
    // getter/setter 略
}

3. JSP 視圖
<%@ taglib prefix="s" uri="/struts-tags" %>




zh_TW
en
es
繁體中文 | English | Español


    
    
    



4. 成功頁面


5. struts.xml

    
    
    
        
            /index.jsp
        
        
            /index.jsp
            /success.jsp
        
    


六、部署驗證

Export WAR → 部署 Tomcat。
訪問 https://localhost:8080/ContextPath/index.jsp。
點擊語系連結，觀察標籤、提示訊息即時切換。
提交表單，成功頁面顯示對應語系的成功訊息。


七、總結

主題機制分離「標籤邏輯」與「HTML 渲染」，支援 FreeMarker/Velocity/JSP 多種模板引擎。
自訂主題只需複製現有主題並修改所需模板，配合 struts.ui.theme 切換。
國際化核心：資源檔命名規範、查找順序、<s:i18n> 作用域隔離、request_locale 參數驅動語系切換。
實戰建議：將通用訊息放 global.properties，業務特定訊息放 Action/Package 層級資源檔，避免單一檔案過大。