萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> JSP 程式設計

JSP 自定義標籤開發完整教程:從 TagSupport 到 Tag Library Descriptor

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

二、 JSP 容器處理自定義標籤流程

  1. 遇到 <%@ taglib prefix="mytag" uri="/WEB-INF/tlds/mytags.tld" %>,容器定位 TLD。
  2. 解析 TLD,建立 uri → TLD 映射,tag name → TagHandler Class 映射。
  3. 頁面出現 <mytag:demo attr="val">body</mytag:demo>。
  4. 容器實例化 TagHandler (池化複用),依序調用:
    1. setPageContext(pageContext) — 注入頁面上下文,可訪問 request/session/application/out 等隱含物件。
    2. setParent(parentTag) — 建立巢狀標籤關係。
    3. setXxx(value) — 為每個屬性調用 Setter (屬性名大小寫敏感)。
    4. doStartTag() — 返回 EVAL_BODY_INCLUDE (處理體內容) 或 SKIP_BODY (忽略體)。
    5. 若評估體:執行體內容 (可能包含其他標籤/EL/Scriptlet),輸出寫入 BodyContent (BodyTag) 或直接寫入 JspWriter (Tag)。
    6. doAfterBody() (BodyTag) — 迭代處理體,返回 EVAL_BODY_AGAIN 繼續或 SKIP_BODY 結束。
    7. doEndTag() — 返回 EVAL_PAGE (繼續頁面) 或 SKIP_PAGE (中止頁面輸出)。
    8. release() — 釋放資源,重置狀態,歸還池中。

三、 開發步驟實戰:建立 <mytag:repeat> 迴圈標籤

1. 標籤處理類 (繼承 TagSupport)

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; // 重置預設值,支援池化複用
    }
}

2. TLD 描述檔 (/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>

3. web.xml 註冊 TLD (可選,JSP 2.0+ 容器自動掃描 /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>

4. JSP 頁面使用

<%@ 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 次迴圈

`

四、 進階:BodyTagSupport 處理體內容轉換

需對體內容進行後處理 (如大寫轉換、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 片段等)。

五、 JSP 2.0+ SimpleTag 介面:更簡潔的開發模型

不再需要 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

七、 打包發布為 JAR (可跨專案重用)

  1. 編譯類別至 classes/com/example/tag/。
  2. 建立 META-INF/taglib.tld (名稱固定)。
  3. 打包:jar -cvf mytags.jar -C classes . META-INF/taglib.tld。
  4. 放入目標專案 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 (領域特定語言) 仍具極高價值。

copyright © 萬盛學電腦網 all rights reserved