夜雨聆风
用户按F1,帮助文档打开首页?上下文敏感帮助终于解决了这个老问题
你有没有遇到过这种崩溃场景：
用户打电话来问”这个按钮怎么用？”，你说”按F1看帮助”。用户按了F1，打开的是一本800页手册的首页。然后用户说：”我找不到啊！”
你心里想：帮助文档写了，你不会翻吗？
但冷静想想——这真的是用户的错吗？
帮助文档写得再好，用户找不到，等于没写。这就是软件行业长期存在的一个痛点：帮助系统和产品界面是割裂的。
先看一个真实场景
一家工业自动化公司，有3条产品线：PLC编程软件、HMI组态软件、运动控制软件。每条产品线都有独立的软件界面，但底层通信协议的文档是共用的。
用户在PLC软件里按F1，想看通信配置——结果打开的是整本手册首页，得自己翻到第37章。用户在HMI软件里按F1，也是一样。
文档团队很委屈：我们写了啊，800页呢。用户也很委屈：我找不到啊。
如果帮助文档能”知道”用户当前在哪个界面，自动跳到对应的页面呢？
这就是上下文敏感帮助（Context-Sensitive Help）做的事。
终于不用让用户翻目录了！
怎么实现？三步搞定
第一步：在DITA文件里绑定ID
DITA提供了一个专门的标签 <resourceid>，用来建立”界面元素”和”帮助主题”之间的映射关系。
你可以在DITA映射里绑定：
<maptitle="App Help"><topicrefhref="app-help1.dita"type="task"><topicmeta><!-- appname=你的应用名，appid=当前界面的唯一标识 --><resourceidappname="myapp"appid="functionid1"/></topicmeta></topicref></map>
也可以在DITA主题里绑定：
<taskid="app-help1"><title>My App Help</title><prolog><!-- 同样可以在这里绑定 --><resourceidappname="myapp"appid="functionid1"/></prolog></task>
看起来复杂？其实就两个属性：appname 和 appid。
两个位置有什么区别？映射级别的绑定会覆盖主题级别的绑定。如果两个地方都写了appid，系统优先认映射里的。
第二步：通过URL调用
应用程序端只需要一个URL就能触发帮助跳转：
http://localhost/webhelp/cshelp.html?contextId=functionid1&appname=myapp几个要点：
- contextId 参数大小写不敏感
- 还可以拼接锚点，比如
contextId=functionid1#anchor，直接跳到页面的指定章节 - appname 是可选的，主要用于多应用场景
⚠️ 注意：旧版用的是 index.html，已被弃用。虽然还能用，但未来会移除，建议直接用 cshelp.html。
第三步：生成WebHelp
这一步最省心。Oxygen生成WebHelp Responsive输出时，会自动生成一个叫 context-help-map.xml 的映射文件。这个文件记录了所有contextId和HTML页面的对应关系，应用程序集成的时候直接读取就行。
contextId优先级：记不住没关系，大部分场景用appid就够了
如果你在DITA文件里同时存在多种ID标识方式，系统按以下优先级取值：
- 优先级1（最高）：<resourceid> 标签的 appid 属性
- 优先级2：<resourceid> 标签的 id 属性（如果同时存在appid，id会被忽略）
- 优先级3（兜底）：主题根元素的id属性——当没有声明任何 <resourceid> 时自动使用
💡 但要注意：兜底ID必须在整个DITA项目中唯一，否则会触发警告，帮助系统会失效。可以通过设置参数 webhelp.csh.disable.topicID.fallback=true 关闭兜底机制。
<resourceid> 的使用规则
这个标签的用法挺灵活的：
- 一个appname可以对应多个appid（一个应用有多个功能点）
- 一个appid也可以对应多个appname（同一个帮助主题被多个应用共用）
- 但在同一个根映射中，appid + appname 的组合必须唯一
回到前面那个工业自动化的场景：
-
把通信协议的DITA主题写一份 -
在映射里分别为三条产品线绑定不同的appid，指向同一个主题 -
各产品线的应用分别通过不同的contextId调用
一份文档，三个入口，精准匹配。
小结
上下文敏感帮助解决的不是”能不能写帮助文档”的问题，而是”用户能不能快速找到帮助”的问题。
从软件团队的角度看，核心价值有三点：
- 降低用户查找成本：从”翻目录”变成”直接跳转”
- 支持多产品线复用：一份DITA内容服务多个应用
- 集成简单：URL调用 + 自动生成的映射文件
你们产品的帮助系统，现在还是”打开首页让用户自己翻”吗？
A. 是的，用户经常投诉找不到帮助B. 我们做了跳转，但是硬编码的，维护很痛苦C. 我们已经用了上下文敏感帮助，真香D. 还不知道有这个功能，马上试试
评论区选个字母～
摩拿科技是专业的结构化文档和智能内容工具和服务提供商，提供Oxygen XML Editor等专业工具及配套服务，协助企业文档结构化转型落地，欢迎访问官网了解。