JSP 自定義標籤 (Custom Tag) 將 Java 邏輯封裝為聲明式 XML 標籤,實現「邏輯與表現分離」,是 JSP 2.0 前構建可重用元件的核心機制。本文系統講解標籤庫架構、開發流程、核心 API、生命週期與實戰範例。
| 術語 | 定義 | 對應檔案/類別 |
|---|---|---|
| 標籤 | XML 元素,如 <mytag:hello> | JSP 頁面中使用 |
| 標籤庫 | 功能相關標籤的集合 | 一組 .tld + 處理類 JAR |
| 標籤庫描述符 (TLD) | XML 配置,映射標籤名 → 處理類、屬性、體內容類型 | /WEB-INF/tlds/mytags.tld 或 JAR 內 /META-INF/taglib.tld |
| 標籤處理類 | 實作標籤行為的 Java 類 | 繼承 TagSupport / BodyTagSupport 或實作 Tag/BodyTag / SimpleTag |
<%@ taglib prefix="mytag" uri="/WEB-INF/tlds/mytags.tld" %>,容器定位 TLD。uri → TLD 映射,tag name → TagHandler Class 映射。<mytag:demo attr="val">body</mytag:demo>。TagHandler (池化複用),依序調用:setPageContext(pageContext) — 注入頁面上下文,可訪問 request/session/application/out 等隱含物件。setParent(parentTag) — 建立巢狀標籤關係。setXxx(value) — 為每個屬性調用 Setter (屬性名大小寫敏感)。doStartTag() — 返回 EVAL_BODY_INCLUDE (處理體內容) 或 SKIP_BODY (忽略體)。BodyContent (BodyTag) 或直接寫入 JspWriter (Tag)。doAfterBody() (BodyTag) — 迭代處理體,返回 EVAL_BODY_AGAIN 繼續或 SKIP_BODY 結束。doEndTag() — 返回 EVAL_PAGE (繼續頁面) 或 SKIP_PAGE (中止頁面輸出)。release() — 釋放資源,重置狀態,歸還池中。<mytag:repeat> 迴圈標籤package com.example.tag;
import javax.servlet.jsp.JspException;
import javax.servlet.jsp.tagext.TagSupport;
public class RepeatTag extends TagSupport {
private int times = 1; // 預設 1 次
public void setTimes(int times) { this.times = times; }
@Override
public int doStartTag() throws JspException {
if (times <= 0) return SKIP_BODY;
// 將迴圈計數器暴露給頁面 (可選)
pageContext.setAttribute("repeatIndex", 0);
return EVAL_BODY_INCLUDE; // 處理體內容
}
@Override
public int doAfterBody() throws JspException {
Integer index = (Integer) pageContext.getAttribute("repeatIndex");
if (index == null) index = 0;
index++;
if (index < times) {
pageContext.setAttribute("repeatIndex", index);
return EVAL_BODY_AGAIN; // 重新評估體
}
return SKIP_BODY; // 結束迴圈
}
@Override
public void release() {
super.release();
times = 1; // 重置預設值,支援池化複用
}
}
/WEB-INF/tlds/mytags.tld)<?xml version="1.0" encoding="UTF-8"?>
<taglib xmlns="https://java.sun.com/xml/ns/javaee" version="2.1">
<tlib-version>1.0</tlib-version>
<short-name>mytag</short-name>
<uri>https://example.com/mytags</uri> <!-- 唯一 URI,JSP 引用時使用 -->
<tag>
<name>repeat</name>
<tag-class>com.example.tag.RepeatTag</tag-class>
<body-content>JSP</body-content> <!-- empty | JSP | tagdependent -->
<attribute>
<name>times</name>
<required>true</required>
<rtexprvalue>true</rtexprvalue> <!-- 支援 EL 運算式 -->
<type>int</type>
</attribute>
</tag>
</taglib>
/WEB-INF/**/*.tld)<jsp-config>
<taglib>
<taglib-uri>https://example.com/mytags</taglib-uri>
<taglib-location>/WEB-INF/tlds/mytags.tld</taglib-location>
</taglib>
</jsp-config>
<%@ taglib prefix="mytag" uri="https://example.com/mytags" %>
<html><body>
<mytag:repeat times="3">
<p>第 ${repeatIndex + 1} 次迴圈</p>
</mytag:repeat>
</body></html>
輸出:三段 `
第 1 次迴圈
第 2 次迴圈
第 3 次迴圈
`需對體內容進行後處理 (如大寫轉換、HTML 過濾、壓縮) 時,繼承 BodyTagSupport,重寫 doAfterBody():
public class UpperCaseTag extends BodyTagSupport {
@Override
public int doAfterBody() throws JspException {
BodyContent body = getBodyContent(); // 取得體內容緩衝區
String content = body.getString(); // 獲取字串
if (content != null) {
try {
// 輸出轉換後內容到父層輸出流 (可能是另一個 BodyContent 或 JspWriter)
body.getEnclosingWriter().write(content.toUpperCase());
} catch (IOException e) {
throw new JspException(e);
}
}
return SKIP_BODY; // 體已處理完畢
}
}
TLD 中 <body-content>tagdependent</body-content> 表示體內容**不由容器解釋**,原樣傳給處理類 (適合模板語言、SQL 片段等)。
不再需要 doStartTag/doAfterBody/doEndTag 狀態機,僅實作 doTag() 一個方法,透過 getJspBody().invoke(null) 執行體內容。
public class SimpleRepeatTag extends SimpleTagSupport {
private int times = 1;
public void setTimes(int times) { this.times = times; }
@Override
public void doTag() throws JspException, IOException {
JspFragment body = getJspBody();
for (int i = 0; i < times; i++) {
pageContext.setAttribute("idx", i);
body.invoke(null); // 輸出到當前 JspWriter
}
}
}
TLD 僅需將 tag-class 指向此類,body-content 仍為 JSP。
| TLD 屬性元素 | 說明 | 對應 Java |
|---|---|---|
<name> | 屬性名 (JSP 中使用) | Setter 方法名 setXxx() (JavaBeans 慣例) |
<required> | true/false,是否必填 | 無直接對應,容器驗證 |
<rtexprvalue> | true/false,是否接受運算式 (${...}、<%= %>) | Setter 參數型別需可從 String 轉換 (PropertyEditor) |
<type> | 屬性完整類別名 (如 java.lang.String) | Setter 參數型別 |
<fragment> | true 表示屬性值為 JspFragment (JSP 2.0+) | Setter 參數型別 JspFragment |
<deferred-value>/<deferred-method> | 支援延遲求值 EL (JSP 2.1+,如 JSTL c:forEach varStatus) | ValueExpression / MethodExpression |
classes/com/example/tag/。META-INF/taglib.tld (名稱固定)。jar -cvf mytags.jar -C classes . META-INF/taglib.tld。WEB-INF/lib/,容器自動掃描 META-INF/taglib.tld,JSP 直接用 uri 引用無需 taglib 指令指定路徑。自定義標籤將 Java 邏輯封裝為聲明式標籤,是 JSP 時代「前後端分離」的先驅實踐。雖現代框架 (Thymeleaf、FreeMarker、JSP Tag Files、Facelets、Blazor Components) 提供更強大的元件模型,但理解 TagSupport/BodyTagSupport/SimpleTag 生命週期、TLD 映射機制、體內容處理流程,對維護舊系統、閱讀 JSTL/Struts2 標籤庫原始碼、設計 DSL (領域特定語言) 仍具極高價值。