JavaHelp (JH) 是 Sun 定義的純 Java 在線幫助系統規範 (JSR 197)，基於 Swing (JFC) 實現，跨平台、可嵌入 Applet/Application、支持動態更新、合並多模塊幫助集。雖然 Web 應用主流轉向瀏覽器端幫助中心，但在桌面端 (Swing/JavaFX/Eclipse RCP)、嵌入式設備、離線環境仍具不可替代價值。
helpset.hs (Helpset 入口)
├── map.jhm (Map 文件: TopicID → URL)
├── toc.xml (TOC 文件: 樹結構, target=TopicID)
├── index.xml (Index 文件: 關鍵字 → TopicID 列表)
├── search/db (搜索索引, 由 jhindexer 生成)
└── content/ (HTML 內容文件目錄)
├── intro.html
├── task/
│ ├── create.html
│ └── edit.html
└── ref/
└── api.html
<?xml version="1.0" encoding="UTF-8"?>
<helpset version="2.0">
<title>My Application Help</title>
<maps>
<mapref location="map.jhm"/>
</maps>
<view name="TOC">
<label>目錄</label>
<type>javax.help.TOCView</type>
<data>toc.xml</data>
</view>
<view name="Index">
<label>索引</label>
<type>javax.help.IndexView</type>
<data>index.xml</data>
</view>
<view name="Search">
<label>搜索</label>
<type>javax.help.SearchView</type>
<data>search</data> <!-- 索引目錄 -->
</view>
<view name="Favorites"> <!-- 自定義視圖 -->
<label>收藏</label>
<type>com.myapp.FavoritesView</type>
<data>fav.xml</data>
</view>
</helpset>
<?xml version="1.0" encoding="UTF-8"?>
<map version="2.0">
<mapID target="intro" url="content/intro.html"/>
<mapID target="task.create" url="content/task/create.html"/>
<mapID target="task.edit" url="content/task/edit.html"/>
<mapID target="ref.api" url="content/ref/api.html"/>
</map>
<?xml version="1.0" encoding="UTF-8"?>
<toc version="2.0">
<tocitem target="intro" text="快速入門"/>
<tocitem text="任務指南">
<tocitem target="task.create" text="創建對象"/>
<tocitem target="task.edit" text="編輯對象"/>
</tocitem>
<tocitem target="ref.api" text="API 參考"/>
</toc>
import javax.help.*;
import java.net.URL;
import java.awt.event.*;
public class HelpIntegration {
private HelpSet hs;
private HelpBroker hb;
public void initHelp() throws Exception {
// 1. 載入 Helpset (從 classpath/JAR/文件系統)
URL hsURL = HelpSet.findHelpSet(getClass(), "helpset.hs"); // 也支持 File/HTTP URL
hs = new HelpSet(getClass().getClassLoader(), hsURL);
hb = hs.createHelpBroker();
// 2. 上下文敏感幫助綁定 (組件級)
CSH.setHelpOnButton(helpButton, "task.create", hs); // 按鈕
CSH.setHelpOnButton(menuItem, "task.edit", hs); // 菜單項
CSH.setHelpKeyString(textField, "ref.api", hs); // 文本框 F1
CSH.setHelpIDString(dialog, "intro", hs); // 對話框
// 3. 獨立幫助窗口動作
Action showHelp = new AbstractAction("幫助文檔") {
public void actionPerformed(ActionEvent e) {
hb.setCurrentID("intro"); // 默認主題
hb.setSize(800, 600);
hb.setLocationRelativeTo(mainFrame);
hb.setDisplayed(true);
}
};
helpMenu.add(showHelp);
toolBar.add(showHelp);
// 4. 動態合並外部幫助集 (插件化)
// URL extHSURL = new URL("https://updates.myapp.com/plugins/extra.hs");
// HelpSet extHS = new HelpSet(classLoader, extHSURL);
// hs.merge(extHS); // TOC/Index/Search 自動合並
}
}
在 HTML 內容中嵌入 Swing 組件 (彈出窗口、動畫、計算器、圖表)：
<object classid="java:javax.help.Popup"
codebase="."
width="200" height="150">
<param name="content" value="content/glossary_def.html"/>
<param name="viewerActivator" value="link"/>
<param name="text" value="點擊查看術語定義"/>
<param name="windowType" value="popup"/>
</object>
自定義組件需實現 `javax.help.impl.ViewAwareComponent`，接收 `setViewData(ViewData)` 獲取上下文信息。
| 工具 | 特征 | 授權 | |
|---|---|---|---|
| Helen (Software7) | 可視化編輯、項目管理、批量導入、多語言 | 商業 | |
| HelpBreeze (SolutionSoft) | Word/FrameMaker 導入、模板驅動、腳本自動化 | 商業 | |
| JavaHelp Author (Pivotonic) | 基於 Eclipse、XML 編輯、預覽、構建 | 商業 | |
| 開源替代 | DocBook + XSLT → JavaHelp、AsciiDoc + 自定義後端、手寫 XML + Ant 構建腳本 | 免費 |
| 方案 | 適用場景 | 優勢 | 劣勢 |
|---|---|---|---|
| JavaHelp | Swing/JavaFX 桌面、嵌入式、離線、插件化幫助 | 純 Java、標準化、嵌入式、合並、輕量組件 | UI 風格老舊、HTML 支持有限 (無 HTML5/CSS3/JS)、移動端不適用 |
| Web Help Center | Web 應用、SaaS、移動端、多語言、SEO | 現代技術棧、響應式、分析統計、易維護 | 需網絡、需獨立部署、桌面應用集成需內嵌瀏覽器 |
| Eclipse Help (Infocenter) | Eclipse RCP/插件平台 | 原生集成、TOC/索引/搜索、動態插件 | 綁定 Equinox、非 Eclipse 項目引入重 |
| Markdown + 靜態站點 (Docusaurus/VitePress/GitBook) | 文檔站點、API 參考、開發者門戶 | 寫作體驗佳、版本控制、CI/CD 部署、主題豐富 | 非嵌入式、無上下文敏感、無合並機制 |
