Java 註釋隱藏技能：在 Javadoc 中使用 HTML/CSS 打造富文本文檔

Java 註釋隱藏技能：在 Javadoc 中使用 HTML/CSS 打造富文本文檔

大多數開發者只用 Javadoc 寫純文本，其實 Javadoc 完整支持 HTML 標簽和內聯 CSS，能生成帶鏈接、加粗、顏色、代碼高亮的專業級 API 文檔。本文揭秘這項「隱藏技能」並給出實用範例。

一、基礎對比

普通註釋

/**
 * 這是一個測試類
 */
public class Test {
    /**
     * 程序的入口
     */
    public static void main(String[] args) {
        new Test();
    }
}

IDE 中 Ctrl+Q (IntelliJ) 或懸停 (Eclipse) 顯示純文本。

二、HTML/CSS 增強版

/**
 * <a href='https://www.baidu.com' style='color:red;font-weight:900;text-decoration:underline;'>
 *   點擊跳轉百度（紅色粗體下劃線）
 * </a>
 */
public class Test {
    /**
     * <ul>
     *   <li><b>參數 1</b>: 主鍵 ID</li>
     *   <li><b>參數 2</b>: 用戶名</li>
     * </ul>
     * <p style='color:#d9534f;'><strong>注意：</strong> 此方法不支持批量操作</p>
     * @param id 主鍵
     * @return 用戶對象
     */
    public User findById(Long id) { ... }
}

三、支持的 HTML 標簽白名單

四、內聯 CSS 支持屬性

在 style 屬性中可用：

• 顏色：color:red / #ff0000 / rgb(255,0,0)
• 字重：font-weight:bold / 900
• 字體：font-family:monospace / Consolas
• 背景：background-color:#f5f5f5
• 邊距：margin:5px; padding:3px
• 邊框：border:1px solid #ccc

五、實用模板庫

1. 重要警告框

/**
 * <div style='background:#fff3cd;border:1px solid #ffc107;padding:10px;border-radius:4px;color:#856404;'>
 *   <strong>⚠ 警告：</strong> 此方法會清空緩存，請謹慎調用！
 * </div>
 */

2. 參數說明表格

/**
 * <table style='border-collapse:collapse;width:100%;'>
 *   <tr style='background:#f8f9fa;'><th style='border:1px solid #dee2e6;padding:5px;'>參數</th><th style='border:1px solid #dee2e6;padding:5px;'>類型</th><th style='border:1px solid #dee2e6;padding:5px;'>必填</th><th style='border:1px solid #dee2e6;padding:5px;'>說明</th></tr>
 *   <tr><td style='border:1px solid #dee2e6;padding:5px;'>id</td><td style='border:1px solid #dee2e6;padding:5px;'>Long</td><td style='border:1px solid #dee2e6;padding:5px;'>是</td><td style='border:1px solid #dee2e6;padding:5px;'>用戶主鍵</td></tr>
 *   <tr><td style='border:1px solid #dee2e6;padding:5px;'>name</td><td style='border:1px solid #dee2e6;padding:5px;'>String</td><td style='border:1px solid #dee2e6;padding:5px;'>否</td><td style='border:1px solid #dee2e6;padding:5px;'>用戶名</td></tr>
 * </table>
 */

3. 代碼示例塊

/**
 * 使用示例：
 * <pre style='background:#f8f9fa;border:1px solid #e9ecef;padding:10px;border-radius:4px;overflow:auto;'>
 * <code>
 * UserService service = context.getBean(UserService.class);
 * User user = service.findById(1001L);
 * System.out.println(user.getName());
 * </code>
 * </pre>
 */

六、生成文檔命令

# 生成 HTML 文檔到 docs 目錄
javadoc -d docs -sourcepath src/main/java -subpackages com.example -encoding UTF-8 -charset UTF-8 -docencoding UTF-8

七、注意事項

• HTML 必須良好形成：標簽閉合、屬性加引號
• < > 在註釋中直接寫，不要轉義為 < >
• 避免使用 <script>、<style>、<iframe> 等不安全標簽（Javadoc 會過濾）
• CSS 僅支持內聯樣式，不支持 <style> 塊和外部樣式表
• 圖片路徑相對生成的 HTML 文件位置，建議放在 doc-files 目錄