文档嵌入组件 uldoc-help.js

uldoc-help.js 是奥宏文档系统对外提供的 JS 嵌入组件。把它引入到任意第三方网站后，你就能在那个网站的任意位置插入一个 <uldoc-help> 标签，用户 hover 或点击这个标签，会弹出一个面板，直接显示奥宏文档里对应的文章。

零依赖（不依赖 Vue / React / jQuery），样式通过 Shadow DOM 完全隔离，不会污染你的网站。

核心思路

把奥宏文档当成你产品的"内容后台"：

你的产品里有哪些功能需要解释，就在奥宏文档里为每个功能写一篇文章
在产品页面里用 <uldoc-help page-path="文章UID"> 标签，把对应的文章嵌入到功能旁边
用户使用产品时，看到问号图标或带下划线的文字，hover/click 就能阅读说明

关键点：文章内容是写在奥宏文档里的（用编辑器维护、支持版本/多语言/搜索），uldoc-help 只负责把它们显示到你的网站上。文档更新了，所有嵌入位置自动同步，不用改代码。

完整工作流（5 步）

Step 1：规划文档结构

在奥宏文档里创建一个项目，按你产品的功能模块搭分组结构。例如你的产品是个后台管理系统，文档结构可以是：

我的产品帮助文档
├── 用户管理（分组）
│   ├── 角色说明
│   ├── 添加用户
│   └── 批量导入
├── 订单管理（分组）
│   ├── 订单状态
│   └── 退款流程
└── 数据统计（分组）
    ├── 报表导出
    └── 自定义指标

每个叶子页面（不是分组）就是一个可以嵌入的功能点说明。

Step 2：为每个功能点写文档（站在使用者角度）

打开编辑器，为每个功能创建一个页面，内容要回答用户最关心的三个问题：

这是什么：这个功能/字段是干什么的
怎么操作：步骤化、配截图
有什么要注意：常见误区、限制、关联功能

写作原则：面向使用者而不是开发者。不要写"这个接口返回什么 JSON"，要写"上传图片时支持哪些格式、最大多少 MB"。

手动写费时间？用 MCP 让 AI 助手帮你：奥宏文档支持 MCP 协议，你可以让 Claude / Cursor 等 AI 助手直接读写这个项目的文档，批量生成、润色、翻译都可以。详见 MCP 接入指南。

Step 3：拿到每个页面的 page-path

page-path 就是奥宏文档里页面的 UID。两种获取方式：

从阅读页 URL：在奥宏文档里打开目标页面，浏览器地址栏 /read/{home}/{project}/{lang}/{version}/{page-path}.html，最后一段（去掉 .html）就是 page-path。例如 mcp-access-guide。
从编辑器：编辑器左侧页面树点击页面，能看到 UID 字段（也可在编辑器里自定义修改）。

Step 4：在你的网站引入 uldoc-help.js

<script src="https://doc.ulthon.com/cdn/uldoc-help.js"></script>
<script>
  UlDocHelp.init({
    homeName: 'augushong',          // 你的奥宏文档 home name
    projectUid: 'ulthon-document',  // 文档项目 UID
    lang: 'zh-cn',                  // 默认语言
    version: '1.0.0'                // 默认版本
  });
</script>

放在 <head> 或 </body> 前都可以。init 是可选的，但建议加上，避免每个标签都写一遍参数。

Step 5：在功能旁边插入 `<uldoc-help>` 标签

<h2>用户管理</h2>
<p>
  当前角色：
  <select>...</select>
  <uldoc-help page-path="role-introduction" title="角色说明" mode="icon"></uldoc-help>
</p>

完成。用户访问这个页面时，select 旁边会出现一个问号图标，点击就弹出"角色说明"那篇文档。

元素属性

属性	必填	说明
`page-path`	是	目标页面的 UID，获取方式见上文 Step 3
`home-name`	否	文档所有者 home name，未填则用 `init` 默认值
`project-uid`	否	项目 UID，未填则用 `init` 默认值
`lang`	否	语言标识，默认 `default`（项目默认语言）
`version`	否	版本号，默认 `main`
`title`	否	气泡标题，也是 `icon` / `inline` 模式下的文字
`desc`	否	气泡描述文本
`mode`	否	显示模式，可选 `default` / `icon` / `inline`，默认 `default`

只要 home-name + project-uid + page-path 三者齐备，点击就会打开面板；缺任一项时元素只能显示气泡。

三种显示模式（选哪个）

模式	视觉	适用场景
`default`	文字 + 虚下划线，hover 变蓝	嵌在段落正文里，作为某个词的解释链接
`icon`	蓝色圆形问号图标	表单字段标签旁、表格表头、按钮旁的辅助提示
`inline`	蓝色背景小标签	行内的功能标签，例如"使用指南"按钮

选择建议：

字段、表单项的术语解释 → icon
段落里某个词需要展开说明 → default
单独的功能入口/操作引导 → inline

代码示例：

<!-- default：嵌在段落里 -->
<uldoc-help page-path="welcome" title="快速开始">点击查看快速开始</uldoc-help>

<!-- icon：表单字段旁 -->
<label>用户名
  <uldoc-help page-path="faq" title="命名规则" desc="字母数字下划线" mode="icon"></uldoc-help>
</label>

<!-- inline：作为标签 -->
<p>支持
  <uldoc-help page-path="project-settings" title="自定义配置" mode="inline"></uldoc-help>
  多种参数
</p>

交互行为

桌面端（视口宽度 >= 768px）

hover 元素：延迟 200ms 显示气泡（含 title / desc / "查看详情"）
点击元素：打开侧栏面板，加载对应文档
多 tab：点击不同 page-path 的元素会在面板里新增 tab；点击相同 page-path 的元素会切换到已存在的 tab
ESC 键：关闭整个面板
关闭 tab：点击 tab 上的 ×；关最后一个 tab 时面板整体销毁

手机端（视口宽度 < 768px）

第一次点击元素：显示气泡
第二次点击同一元素：打开底部面板（65vh 高度，顶部圆角）
点击面板外部区域可关闭面板

手机端不响应 hover。

文档内容写作建议

被嵌入的文档应该站在使用者角度写，否则用户点了问号看到一堆技术细节会立刻关掉。

写法对比

好（使用者角度）：

角色说明

角色决定了用户在系统里能看到什么、能做什么。系统内置 3 种角色：管理员、编辑、访客。 修改用户角色：用户管理 → 点击用户 → 角色 → 保存。

不好（开发者角度）：

角色说明

角色存储在 user.role_id 字段，关联 role 表。查询时使用 User::with('role')->find($id)。

第二种写法对使用者毫无价值，应该放在开发者文档里，不要嵌入到产品 UI。

一篇文档对应一个功能点

不要把"用户管理的所有事"塞进一篇文档。拆细：

add-user - 如何添加用户
edit-user-role - 如何修改用户角色
delete-user - 如何删除用户
batch-import - 如何批量导入

这样每个 <uldoc-help> 标签可以精确指向用户当前需要的那块内容。

延伸：用 MCP 让 AI 助手帮你维护文档

为产品搭一套帮助文档最大的成本是写：一个后台系统可能有几十上百个功能点，全靠人工在编辑器里逐篇写、配图、翻译，工作量很大。

奥宏文档内置 MCP 服务，可以让 AI 助手（如 Claude、Cursor）直接读写你的文档项目：

让 AI 根据产品需求文档/PRD 批量生成功能说明
让 AI 翻译已有文档到其他语言
让 AI 根据用户反馈持续更新文档内容
让 AI 校对润色已有的文档

生成完成后，所有通过 uldoc-help 嵌入的位置会自动同步到最新版本——AI 写的内容直接出现在你的产品 UI 里，无需任何代码改动。

开始使用：参见 MCP 接入指南。

进阶用法

仅作为气泡提示（不打开面板）

如果你只需要一个轻量的术语解释，不需要打开完整文档，可以不写 page-path：

<uldoc-help title="MCP" desc="Model Context Protocol，模型上下文协议">MCP</uldoc-help>

点击不会打开面板，只显示气泡。

不同语言/版本

同一个标签可以指定不同的语言或版本，覆盖默认值：

<!-- 强制显示英文版 -->
<uldoc-help page-path="welcome" lang="en" title="Get Started">Get Started</uldoc-help>

<!-- 指定旧版本（适合老用户） -->
<uldoc-help page-path="welcome" version="0.9.0" title="v0.9 入门">查看旧版入门</uldoc-help>

全局 API

方法	说明
`UlDocHelp.init(options)`	设置全局默认配置（`homeName` / `projectUid` / `lang` / `version`）
`UlDocHelp.getDefaults()`	读取当前默认配置

与其他集成方式的区别

需求	推荐方式
在自己网站嵌入本文档的某个页面	uldoc-help.js（本文档）
让 AI / LLM 读写文档	MCP（见 MCP 接入指南）
编程式调用接口管理文档	API + API Token（见 API Token 管理）
把外部网页嵌入到本文档的某个页面	iframe 块（见 iframe 嵌入）

完整最小示例

可以直接复制运行：

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>我的产品后台</title>
</head>
<body>
  <!-- 引入 + 初始化 -->
  <script src="https://doc.ulthon.com/cdn/uldoc-help.js"></script>
  <script>
    UlDocHelp.init({
      homeName: 'augushong',
      projectUid: 'ulthon-document',
      lang: 'zh-cn',
      version: '1.0.0'
    });
  </script>

  <h1>用户管理</h1>

  <p>
    用户分为多种角色
    <uldoc-help page-path="member-roles" title="角色说明">（查看角色说明）</uldoc-help>
  </p>

  <p>
    <label>用户名
      <uldoc-help page-path="faq" title="命名规则" desc="字母数字下划线" mode="icon"></uldoc-help>
    </label>
    <input type="text">
  </p>

  <p>
    支持配置
    <uldoc-help page-path="project-settings" title="项目设置" mode="inline"></uldoc-help>
    多种参数
  </p>
</body>
</html>

测试页面

本地测试页面随项目源码提供：

public/cdn/test-uldoc-help.html - 含 init 的完整示例
public/cdn/test-uldoc-help-no-init.html - 不调用 init 的最小示例

通过 php think serve 或任意静态服务器打开测试。