示例：Markdown 文档中心

本示例展示如何用 MarkdownViewer 组合一个业务文档阅读器。它是页面组合方案，不是框架内置的单一组件；框架提供 MarkdownViewer、TreeView、CollapsiblePanelGroup、DockPanel、SearchBox 等基础能力，业务项目可以按自己的文档目录和权限体系重新组合。

页面结构

DockPanel
  left:
    CollapsiblePanelGroup
      文档树
      本文目录
      搜索结果
  fill:
    文档路径
    当前位置
    搜索框 + 上一处 + 下一处
    MarkdownViewer

左侧使用折叠分区是为了让正式文档、本文目录、全文搜索结果共享同一侧栏宽度。右侧由标题区、搜索区和 MarkdownViewer 组成，MarkdownViewer 负责解析和绘制 Markdown 内容，页面负责文档路由、搜索、目录同步和历史导航。

数据来源

业务项目可以把源文档和运行时静态资源分开，例如：

content/docs/**
public/docs/**
public/docs/manifest.json

构建脚本负责把源文档复制到静态资源目录，并生成包含标题、分组、顺序和相对路径的 manifest.json。文档中心运行时只读取静态资源，不要求服务器访问项目源码，也不在页面代码中手写完整文档清单。

关键能力

• 文档树按 manifest 组织，manifest 由正式文档目录生成。
• 点击文档异步加载 Markdown。
• 文档加载后构建本文目录。
• 正文滚动时同步当前 heading。
• 搜索结果以树展示。
• Enter 连续搜索跳到下一处。
• 跨文档链接可以打开对应文档。
• 图片相对路径按当前文档目录解析。
• 浏览历史支持后退和前进。

加载流程

点击文档树节点
  -> 根据 manifest doc key 找到文档相对路径
  -> 转换为 /docs 静态资源路径
  -> 拉取 Markdown 字符串
  -> 设置到 MarkdownViewer
  -> 根据解析结果重建本文目录
  -> 默认滚动到顶部
  -> 如果链接带 anchor，再滚动到对应标题

文档中心主动调用 scrollToTop() 是页面策略，不是 MarkdownViewer 的默认行为。MarkdownViewer 更新 Markdown 字符串后会保留滚动位置，业务如果希望打开新文档回到顶部，需要自己调用对应 API。

链接解析

MarkdownViewer 会把正文中的链接点击事件抛给页面。页面先处理站内文档链接，再把外部链接交给浏览器或业务自己的打开逻辑。

文档中心支持以下内部链接写法：

解析规则按当前文档路径归一化 . 和 ..，再和文档中心登记的文档路径匹配。无法匹配的站内链接不会改变当前文档；外部协议链接不按站内文档处理。

业务文档建议优先使用相对路径，减少目录迁移时的歧义。/docs/... 适合路由、测试或明确需要从静态资源根定位的场景。

图片路径

图片路径由页面根据当前文档路径解析：

• http://、https://、data: 等外部资源保持原样。
• /docs/... 从 public 根路径加载。
• ./images/a.png、../assets/a.png 等相对路径按当前 Markdown 文件所在目录解析。

文档中的图片资源应放在可随文档一起构建和部署的目录下，避免引用临时目录或本机绝对路径。

搜索行为

搜索区同时支持文档名搜索和内容搜索：

• 文档名搜索用于快速定位左侧文档树节点。
• 内容搜索会扫描已登记的正式文档，结果展示在左侧搜索结果分区。
• SearchBox 按 Enter 触发下一处匹配，不主动让输入框失焦。
• 当前匹配项使用独立颜色，和普通匹配项区分。
• 如果目标匹配项已经在可视区域内，跳转时不强制把它滚动到顶部。

目录同步

MarkdownViewer 解析标题后，页面生成本文目录树。正文滚动时，页面根据可视区域内的标题位置更新当前目录项；点击目录项时，页面调用 MarkdownViewer 的标题定位能力。

历史导航

文档中心维护页面级历史栈：

• 打开新文档或跳转到不同 anchor 时写入历史。
• 后退和前进只恢复文档路径、anchor 和滚动目标。
• MarkdownViewer 不负责业务历史栈，它只提供内容渲染和定位能力。

接入边界

• MarkdownViewer 只接受 Markdown 字符串并渲染，不负责从哪里加载文档。
• 文档树、搜索结果、历史栈、权限过滤和远程加载都属于页面或业务应用职责。
• 示例页面里的文档列表和 mock 数据不是框架 API，业务项目应该替换为自己的数据源。
• 代码示例只能引用 ds-ui 包入口导出的框架 API，不要依赖示例页面类。

注意事项

• 打开新文档后显式调用 scrollToTop()。
• manifest 只登记允许当前用户访问的业务文档。
• 增加、移动或删除文档后，应在构建阶段重新生成 manifest，并校验其中的路径都能访问。
• 文档链接失效时，优先检查路径是否相对于当前文档目录，而不是相对于仓库根目录。
• 需要展示结构图时使用 text 代码块，不要把不可运行的伪代码标记为 TypeScript。

相关文档

• MarkdownViewer
• TreeView
• CollapsiblePanelGroup
• DockPanel