JSP 自定義標籤完整開發指南：從 TagHandler 到 TLD 配置與部署

核心概念

開發四步驟

1. 撰寫 Tag Handler 類
2. 編寫 TLD 檔
3. web.xml 宣告標籤庫（或依賴 JAR 自動掃描）
4. JSP 頁面引入並使用

一、Tag Handler 實作

繼承 TagSupport（經典體）

package com.example.tag;
import javax.servlet.jsp.*;
import javax.servlet.jsp.tagext.*;

public class HelloTag extends TagSupport {
    private String name; // 屬性對應 setter
    public void setName(String name) { this.name = name; }

    @Override
    public int doStartTag() throws JspException {
        try {
            pageContext.getOut().print("Hello, " + (name != null ? name : "World") + "!");
        } catch (IOException e) {
            throw new JspException(e);
        }
        return SKIP_BODY; // 無 body 內容
    }

    @Override
    public int doEndTag() { return EVAL_PAGE; }
}

實作 SimpleTag（JSP 2.0+ 推薦，更簡潔）

public class HelloSimpleTag extends SimpleTagSupport {
    private String name;
    public void setName(String name) { this.name = name; }

    @Override
    public void doTag() throws JspException, IOException {
        getJspContext().getOut().print("Hello, " + (name != null ? name : "World") + "!");
    }
}

二、TLD 檔案

位置：WEB-INF/tlds/mytags.tld 或 JAR 內 META-INF/tlds/

<?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>

    <tag>
        <name>hello</name>
        <tag-class>com.example.tag.HelloTag</tag-class>
        <body-content>empty</body-content>
        <attribute>
            <name>name</name>
            <required>false</required>
            <rtexprvalue>true</rtexprvalue>
        </attribute>
    </tag>
</taglib>

三、web.xml 宣告（可選，Servlet 2.3+ 可自動掃描）

<jsp-config>
    <taglib>
        <taglib-uri>https://example.com/mytags</taglib-uri>
        <taglib-location>/WEB-INF/tlds/mytags.tld</taglib-location>
    </taglib>
</jsp-config>

四、JSP 頁面使用

<%@ taglib prefix="my" uri="https://example.com/mytags" %>
<html><body>
    <my:hello name="Developer"/>
</body></html>

進階主題

處理標籤體內容

// TagSupport
public int doStartTag() { return EVAL_BODY_INCLUDE; } // 執行 body 內容
public int doEndTag() { return EVAL_PAGE; }

// SimpleTag
public void doTag() throws JspException, IOException {
    JspFragment body = getJspBody();
    if (body != null) body.invoke(null); // 直接輸出 body
}

屬性型別轉換

基本型別、String、Enum 自動轉換；複雜型別需在 setter 中處理或實作 TagAttributeConverter。

標籤巢狀與父子通訊

// 子標籤取得父標籤
ParentTag parent = (ParentTag) getParent();
parent.addChildData(this);

部署與最佳實踐

• 將標籤庫打包為獨立 JAR，放入 WEB-INF/lib，TLD 置於 JAR META-INF/tlds/，容器自動發現。
• 命名空間 URI 採用反向域名格式（如 https://com.example/tags）避免衝突。
• 優先使用 SimpleTag：不需管理生命週期、支援片段、程式碼更簡潔。
• 大量輸出時使用 BodyContent 緩衝，避免直接寫 Out 造成效能問題。