Struts 2 select/doubleselect/updownselect 標籤資料顯示完整指南

Struts 2 UI 標籤 (<s:select>、<s:doubleselect>、<s:updownselect> 等) 功能強大但文檔不夠詳細。本文針對實戰常見的 List/Map/Set 集合資料綁定、listKey/listValue 屬性映射、雙層聯動、排序選擇 進行完整解析與範例示範。

一、HTML 原生 select 基礎回顧

<select name="sex">
  <option value="man">男</option>
  <option value="women">女</option>
</select>

• name：表單提交參數名
• value：提交至伺服器的值
• 選項內容：使用者看到的顯示文字

二、Struts 2 <s:select> 核心屬性

三、Action 準備資料：ClientUserAction

public class ClientUserAction extends ActionSupport {
    private List<Client> clients;  // Client: id, clientId, clientName
    private List<User> users;      // User: userid, username

    public String queryClientID() {
        Map session = ActionContext.getContext().getSession();
        String userid = (String) session.get("userid");
        setUsers(DAOFactory.getEmployeeInstance().queryUidUserid());
        setClients(DAOFactory.getClientInstance().queryByAll(userid));
        return SUCCESS;
    }
    // getter/setter 略
}

四、JSP 頁面綁定範例

<s:form action="clientuser_changeClient" method="post">

  <!-- 1. 單選下拉：客戶 ID -->
  <s:select list="clients" name="clientuser.clientId"
       listKey="clientId" listValue="clientId"
       label="選擇你將要轉讓的客戶" required="true" />

  <!-- 2. 單選下拉：受讓同事 -->
  <s:select list="users" name="clientuser.userid"
       listKey="userid" listValue="userid"
       label="將要轉讓給同事" required="true" />

  <!-- 3. 雙層聯動：第一層選客戶，第二層顯示該客戶相關資料 -->
  <s:doubleselect list="clients" name="client.clientId"
       listKey="clientId" listValue="clientId"
       doubleName="client.clientName" doubleList="clients"
       doubleListKey="clientName" doubleListValue="clientName" />

  <!-- 4. 上下移動排序：所有客戶 ID -->
  <s:updownselect label="All Clients ID" list="clients"
       listKey="clientId" listValue="clientId"
       headerKey="0" headerValue="--所有客戶編號--"
       moveUpLabel="向上" moveDownLabel="向下" selectAllLabel="全選" />

  <!-- 5. 上下移動排序：所有客戶名稱 -->
  <s:updownselect label="All Clients Name" list="clients"
       listKey="clientName" listValue="clientName"
       headerKey="0" headerValue="--所有客戶姓名--" />

  <s:submit value="確認轉讓" onclick="alert('轉讓後你就失去了該客戶');" />
</s:form>

五、listKey/listValue 映射規則詳解

範例：Client 物件

public class Client {
    private String clientId;
    private String clientName;
    // getter/setter
}
// JSP
<s:select list="clients" listKey="clientId" listValue="clientName" />
// 生成
<option value="C001">客戶一</option>
<option value="C002">客戶二</option>

六、<s:doubleselect> 雙層聯動深度解析

機制

• 第一層：list + listKey/listValue
• 第二層：doubleList 為 OGNL 表達式，top 代表第一層選中的物件
• 內部用 JavaScript 實現聯動

正確用法：Map 結構

// Action 準備 Map<String, List<Client>>
Map<String, List<Client>> clientMap = new HashMap<>();
clientMap.put("GROUP_A", groupAClients);
clientMap.put("GROUP_B", groupBClients);

// JSP
<s:doubleselect list="clientMap" name="group"
     listKey="key" listValue="key"
     doubleName="client" doubleList="clientMap[top.key]"
     doubleListKey="clientId" doubleListValue="clientName" />

錯誤用法修正

原文中 doubleList="clients" 且 doubleListKey="clientName" 邏輯錯誤，應改為上述 Map 結構或：

<s:doubleselect list="clients" name="client.clientId"
     listKey="clientId" listValue="clientId"
     doubleName="client.clientName"
     doubleList="top.clientDetails"  // 假設 Client 有 clientDetails 屬性
     doubleListKey="detailId" doubleListValue="detailName" />

七、<s:updownselect> 排序選擇

• 生成雙列表箱：可用項目 / 已選項目
• 支援上移/下移/全選按鈕 (可自訂標籤)
• 提交時 name 參數包含已選項目順序的值陣列

八、常見問題與解決

九、最佳實踐建議

1. 資料來源統一命名：Action 中集合屬性名與 JSP list 值一致
2. POJO 實作 toString()：除錯時方便查看物件內容
3. 大量資料分頁/懶載入：避免一次載入數萬筆選項導致頁面巨大
4. 主題切換：theme="simple" 關閉預設表格佈局，自行控制 CSS
5. 國際化：headerValue="%{getText('please.select')}" 從資源檔取值