AI Helper 文档中心

主题

UI 组件库 ​

本文引用的源码文件

本文引用的文件

更新摘要 ​

变更内容

  • 新增全屏覆盖系统，支持消息节点迁移与流式跟随滚动
  • 新增头部工具栏导出功能，支持 Word、PDF、图片、Markdown 四种格式
  • 增强复制功能，支持纯文本和富文本复制，包含 ClipboardItem API 与降级方案
  • 完善响应式设计，针对窄屏设备优化按钮布局与文字显示
  • 新增 Offscreen Document 剪贴板兼容层，解决 MV3 扩展权限限制

目录 ​

  1. 引言
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能与可访问性
  8. 样式隔离与主题适配
  9. 故障排查指南
  10. 结论

引言 ​

本文件面向"AI Helper"扩展的 UI 组件层，聚焦侧边栏界面中的 Markdown 渲染引擎、图片处理组件、图标系统、通用工具函数、样式与主题机制，以及可访问性与性能优化策略。文档以代码级实现为依据，给出架构图、流程图和关键调用链，帮助读者在不直接阅读源码的情况下理解并复用这些组件构建新的界面元素。

更新 本次更新新增了全屏覆盖系统、头部工具栏导出功能、增强的复制功能和响应式设计优化，为开发者提供了更完整的 UI 组件生态。

项目结构 ​

UI 相关能力主要分布在以下位置：

  • 侧边栏渲染与交互：src/side_panel/
  • 共享主题 Token 与主题状态：src/shared/theme.css、src/shared/theme.js
  • 第三方库按需加载：src/side_panel/libs-loader.js
  • 侧边栏主样式：src/side_panel/styles.css
  • 入口 HTML（含主题切换菜单）：side_panel.html
  • Offscreen Document 剪贴板兼容层：src/offscreen/
graph TB
A["侧边栏页面<br/>side_panel.html"] --> B["Markdown 渲染引擎<br/>markdown-render.js"]
A --> C["图片预览与编辑<br/>image-preview.js"]
A --> D["图标常量集合<br/>icons.js"]
A --> E["第三方库懒加载器<br/>libs-loader.js"]
A --> F["全局样式与响应式<br/>styles.css"]
A --> G["全屏覆盖系统<br/>message-fullscreen.js"]
A --> H["复制功能增强<br/>chat-copy.js"]
A --> I["导出功能扩展<br/>chat-export.js"]
B --> E
C --> E
F --> J["主题 Token 变量<br/>theme.css"]
K["主题状态管理<br/>theme.js"] --> J
G --> H
G --> I
H --> L["Offscreen Document<br/>offscreen.js"]

图表来源

章节来源

核心组件 ​

  • 全屏覆盖系统：负责消息节点的动态迁移、流式跟随滚动、键盘导航和退出全屏逻辑。
  • 头部工具栏导出：提供 Word、PDF、图片、Markdown 四种格式的导出功能，支持异步处理和错误恢复。
  • 增强复制功能：支持纯文本和富文本复制，包含 ClipboardItem API 使用和多种降级方案。
  • Markdown 渲染引擎：负责解析 Markdown、安全清洗、Mermaid 图表渲染、代码块复制、表格工具栏等。
  • 图像处理组件：负责图片上传、压缩、预览、多图导航、缩放平移、标注编辑等。
  • 图标系统：集中管理 SVG 图标常量，统一使用 fill="currentColor" 配合主题色。
  • 通用工具函数：日期格式化、Token 计数、文件大小格式化、字符串转义等。
  • 第三方库懒加载：按需加载 Mermaid、jsPDF、html2canvas，避免首屏体积过大。
  • 主题系统：基于 CSS 变量的亮/暗/跟随系统三态主题，支持无闪烁应用与跨页面同步。
  • Offscreen Document 剪贴板兼容层：解决 MV3 扩展权限限制，提供剪贴板读写兼容方案。

章节来源

架构总览 ​

下图展示全屏覆盖系统、头部工具栏导出、复制功能与现有组件之间的协作关系。

sequenceDiagram
participant UI as "侧边栏界面"
participant FS as "全屏覆盖系统"
participant CC as "复制功能"
participant CE as "导出功能"
participant MD as "Markdown 渲染引擎"
participant IMG as "图片处理组件"
participant LIBS as "懒加载器"
participant THEME as "主题系统"
participant OFF as "Offscreen Document"
UI->>FS : 打开全屏模式
FS->>MD : 迁移消息节点到覆盖层
FS->>CC : 绑定复制按钮事件
FS->>CE : 初始化导出菜单
CC->>OFF : 尝试剪贴板操作
OFF-->>CC : 返回成功或失败
CC->>CC : 降级到 execCommand
CE->>LIBS : 按需加载导出库
LIBS-->>CE : 返回可用库实例
CE->>MD : 获取渲染后的内容
CE->>IMG : 处理图片资源
CE->>THEME : 保持白底导出

图表来源

详细组件分析 ​

全屏覆盖系统 ​

职责包括：

  • 消息节点迁移：将当前消息 DOM 节点从聊天容器移动到全屏覆盖层，原位留注释锚点。
  • 流式跟随滚动：在流式输出中自动滚动到底部，用户上滚时暂停跟随。
  • 键盘导航：支持 Alt+F 快捷键、Esc 退出全屏、Alt+双击进入全屏。
  • 头部工具栏：集成复制按钮和导出下拉菜单。
  • 状态管理：维护全屏状态、滚动位置、锚点信息等。
flowchart TD
Start(["用户触发全屏"]) --> CheckNode{"检查消息节点"}
CheckNode --> CreateAnchor["创建注释锚点"]
CreateAnchor --> MoveNode["移动节点到覆盖层"]
MoveNode --> ShowOverlay["显示覆盖层"]
ShowOverlay --> InitToolbar["初始化工具栏"]
InitToolbar --> StartFollow["启动流式跟随"]
StartFollow --> UserAction{"用户操作"}
UserAction --> |点击复制| CopyAction["执行复制"]
UserAction --> |选择导出| ExportAction["打开导出菜单"]
UserAction --> |按Esc| CloseFullscreen["关闭全屏"]
CloseFullscreen --> RestoreNode["恢复节点位置"]
RestoreNode --> ClearState["清理状态"]

图表来源

关键实现要点：

  • 节点迁移而非克隆：保留原有事件监听器和流式更新能力。
  • 锚点机制：使用注释节点标记原位置，确保退出时能准确归位。
  • 流式跟随：通过 ResizeObserver 和 scroll 事件实现智能跟随。
  • 状态守卫：防止会话缓存在全屏期间读取不完整数据。

章节来源

头部工具栏导出功能 ​

职责包括：

  • 多格式导出：支持 Word (docx)、PDF、图片 (PNG/JPEG)、Markdown 四种格式。
  • 异步处理：使用动态导入避免首屏加载重依赖。
  • 错误恢复：提供详细的错误提示和降级方案。
  • UI 反馈：显示加载状态、成功状态和错误信息。
flowchart TD
ExportClick["点击导出按钮"] --> ShowMenu["显示导出菜单"]
ShowMenu --> SelectFormat{"选择导出格式"}
SelectFormat --> |Word| LoadDocx["加载 docx 库"]
SelectFormat --> |PDF| LoadPDF["加载 PDF 库"]
SelectFormat --> |Image| LoadCanvas["加载 html2canvas"]
SelectFormat --> |Markdown| DirectExport["直接导出"]
LoadDocx --> ProcessContent["处理内容"]
LoadPDF --> ProcessContent
LoadCanvas --> ProcessContent
ProcessContent --> RenderMermaid["渲染 Mermaid 图表"]
RenderMermaid --> ConvertSVG["转换 SVG 为图片"]
ConvertSVG --> GenerateFile["生成目标文件"]
GenerateFile --> Download["下载文件"]
Download --> ResetButton["重置按钮状态"]

图表来源

关键实现要点：

  • 惰性加载：导出功能按需 import，避免影响首屏性能。
  • 内容预处理：在导出前处理 Mermaid 图表、SVG 图片和表格。
  • 格式适配：针对不同格式采用不同的处理策略。
  • 用户体验：提供清晰的加载状态和错误提示。

章节来源

增强复制功能 ​

职责包括：

  • 双模式复制：支持纯文本和富文本两种复制模式。
  • ClipboardItem API：优先使用现代 API 同时复制多种格式。
  • 降级方案：当 ClipboardItem 不可用时回退到 execCommand。
  • Offscreen Document：在 MV3 扩展环境中提供剪贴板兼容。
flowchart TD
CopyRequest["复制请求"] --> CheckCtrl{"是否按住 Ctrl/Cmd?"}
CheckCtrl --> |是| RichText["富文本复制"]
CheckCtrl --> |否| PlainText["纯文本复制"]
RichText --> TryClipboardItem["尝试 ClipboardItem API"]
TryClipboardItem --> Success{"API 成功?"}
Success --> |是| Done["完成"]
Success --> |否| FallbackExec["execCommand 降级"]
FallbackExec --> Done
PlainText --> WriteText["navigator.clipboard.writeText"]
WriteText --> FallbackTextarea["textarea 降级"]
FallbackTextarea --> Done

图表来源

关键实现要点：

  • 智能格式检测：根据用户操作自动选择复制模式。
  • 多层降级：ClipboardItem → execCommand → textarea fallback。
  • 富文本处理：清理表格、处理 Mermaid 图表、包装样式。
  • MV3 兼容：通过 Offscreen Document 解决权限限制。

章节来源

Markdown 渲染引擎 ​

职责包括：

  • 提取并占位化 Mermaid 代码块、普通代码块、表格，再交由 marked 解析。
  • 使用 DOMPurify 进行安全清洗，禁止危险标签与事件属性。
  • 按需加载 mermaid 并渲染图表，提供缩放、拖拽、复制、下载 PNG、查看源代码等功能。
  • 为代码块添加复制按钮；为表格提供复制 Markdown、复制富文本、导出 Excel、导出图片等工具栏。
  • 将 Mermaid 图表转换为 PNG 时清理 foreignObject、移除外部资源引用，防止 Canvas 污染。
flowchart TD
Start(["输入 Markdown"]) --> Extract["提取 Mermaid/代码块/表格占位符"]
Extract --> Parse["marked 解析 + DOMPurify 清洗"]
Parse --> Restore["还原 Mermaid/代码块/表格 HTML"]
Restore --> RenderMermaid{"是否包含 Mermaid?"}
RenderMermaid --> |是| LoadLibs["按需加载 Mermaid"]
LoadLibs --> RenderChart["逐个渲染 Mermaid 容器"]
RenderChart --> Controls["添加缩放/拖拽/复制/下载/源码视图控件"]
RenderMermaid --> |否| Done(["输出 HTML"])
Controls --> Done

图表来源

关键实现要点：

  • 安全清洗：禁止 style、iframe、script、object、embed、svg 等标签，并过滤常见事件属性。
  • Mermaid 渲染重试：单个失败不影响其他图表；失败时恢复原始内容并显示友好提示。
  • 主题切换重渲染：根据当前生效主题重新初始化 Mermaid，清空已渲染 SVG 后按原始代码再次渲染。
  • 导出白底语义：SVG→PNG、html2canvas 导出均强制使用白色背景，保证离线可读性。

章节来源

图像处理组件 ​

职责包括：

  • 图片上传与压缩：根据原图尺寸动态计算目标宽高与质量，降低 Token 消耗。
  • 预览与多图导航：支持上一张/下一张、键盘左右切换、Esc 关闭。
  • 缩放与平移：滚轮缩放、鼠标拖拽平移、双击切换 1x/2x。
  • 标注编辑：画笔、橡皮擦、矩形、椭圆、箭头、直线，支持撤销与确认合成新图。
  • 附件状态同步：将压缩图与原图 URL、尺寸写入 state.attachedImages，供消息发送与历史展示使用。
flowchart TD
Upload["选择图片 Blob"] --> Read["FileReader 读取为 DataURL"]
Read --> Size["获取自然宽高"]
Size --> Params["calculateCompressionParams 计算目标尺寸与质量"]
Params --> Canvas["Canvas 绘制并 toDataURL 压缩"]
Canvas --> State["写入 state.attachedImages"]
State --> Preview["渲染缩略图列表"]
Preview --> Open["openImagePreview 打开大图预览"]
Open --> Edit{"是否进入编辑模式?"}
Edit --> |是| Tools["选择工具/颜色/粗细/透明度"]
Tools --> Draw["Canvas 绘制标注"]
Draw --> Confirm["confirmAnnotation 合成新图并替换附件"]
Edit --> |否| ZoomPan["滚轮缩放/拖拽平移/双击缩放"]

图表来源

关键实现要点：

  • 压缩策略：大尺寸图片自动降采样到 768–1280 像素区间，JPEG 质量 0.55–0.75，平衡识别效果与 Token 成本。
  • 预览交互：通过 transform translate+scale 实现高性能缩放平移，避免重排。
  • 编辑模式：双 Canvas 分层（编辑层与预览层），确认后将标注合成到原图尺寸的新图上。

章节来源

图标系统 ​

职责包括：

  • 集中定义常用 SVG 图标常量，避免重复内联。
  • 使用 fill="currentColor" 或 stroke="currentColor"，使图标随主题色变化。
  • 区分不同尺寸（16×16、24×24、1024×1024）与用途（工具调用、原型预览、导出等）。
classDiagram
class Icons {
+ICON_COPY_16
+ICON_CHECKMARK_16
+ICON_EDIT_16
+ICON_BRAIN_24
+ICON_CLOCK_24
+ICON_CHEVRON_DOWN_24
+ICON_CLOSE_24
+ICON_EXPAND_24
+ICON_STOP_24
+ICON_WRENCH_24
+ICON_IMAGE_24
+ICON_EYE_24
+ICON_EXTERNAL_LINK_24
+ICON_EDIT_PEN_24
+ICON_TRASH_24
+ICON_DOWNLOAD_24
+ICON_EXEC_24
+ICON_FILE_24
+ICON_SEARCH_24
+ICON_WRENCH_PLAIN_24
+ICON_QUOTE_1024
+ICON_EXPORT_1024
+ICON_WORD_1024
+ICON_PDF_1024
+ICON_DROPDOWN_ARROW
}

图表来源

章节来源

通用工具函数库 ​

涵盖：

  • 聊天时间格式化：相对时间与完整时间两种格式，支持中英文。
  • Token 数量格式化：紧凑显示与千分位完整显示。
  • 文件大小格式化：B/KB/MB/GB/TB 自适应。
  • 文件预览支持判断：根据扩展名判断是否可在浏览器中预览。

示例路径参考：

章节来源

第三方库懒加载 ​

职责包括：

  • 按需加载 Mermaid、jsPDF、html2canvas，避免首屏引入 3MB+ 脚本。
  • 缓存 Promise，避免重复加载。
  • 根据当前生效主题配置 Mermaid 主题。
flowchart TD
Need["需要 Mermaid/jsPDF/html2canvas"] --> Check["检查 window 上是否已有全局对象"]
Check --> |已有| Return["直接返回"]
Check --> |没有| CreatePromise["创建并缓存 Promise"]
CreatePromise --> Inject["动态插入 script 标签"]
Inject --> Success["onload 成功 → 初始化并返回"]
Inject --> Fail["onerror 失败 → 清除缓存并抛出错误"]

图表来源

章节来源

依赖关系分析 ​

  • 全屏覆盖系统依赖：
    • chat-copy.js（复制功能）
    • chat-export.js（导出功能）
    • markdown-render.js（内容渲染）
    • i18n.js（国际化）
  • 复制功能依赖：
    • offscreen.js（剪贴板兼容）
    • markdown-render.js（内容格式化）
    • utils.js（Toast 提示）
  • 导出功能依赖：
    • libs-loader.js（库加载）
    • markdown-render.js（内容处理）
    • image-preview.js（图片处理）
  • Markdown 渲染依赖：
    • DOMPurify（安全清洗）
    • marked（Markdown 解析）
    • mermaid（图表渲染）
    • html2canvas（表格导出图片）
    • theme（读取生效主题）
  • 图片处理依赖：
    • state（附件状态）
    • i18n（文案）
    • logger（日志）
  • 图标系统：
    • 纯常量，被多处 UI 模块引用，减少重复内联。
  • 主题系统：
    • theme.css 提供 CSS 变量 Token
    • theme.js 管理 preference/resolved 状态并同步到 <html data-theme>
graph LR
FS["message-fullscreen.js"] --> CC["chat-copy.js"]
FS --> CE["chat-export.js"]
FS --> MD["markdown-render.js"]
CC --> OFF["offscreen.js"]
CC --> MD
CE --> LIBS["libs-loader.js"]
CE --> IMG["image-preview.js"]
MD --> PURIFY["DOMPurify"]
MD --> MARKED["marked"]
MD --> MERMAID["mermaid"]
MD --> H2C["html2canvas"]
MD --> THEMEJS["theme.js"]
IMG --> STATE["state.js"]
IMG --> I18N["i18n.js"]
ICONS["icons.js"] --> UI["各 UI 模块"]
THEMECSS["theme.css"] --> STYLES["styles.css"]
THEMEJS --> THEMECSS

图表来源

章节来源

性能与可访问性 ​

性能优化策略 ​

  • 懒加载第三方库：仅在首次需要时注入 Mermaid/jsPDF/html2canvas，避免首屏阻塞。
  • 全屏节点迁移：使用 DOM 节点迁移而非克隆，保留事件监听器，减少内存占用。
  • 流式跟随优化：使用 ResizeObserver 和 passive 事件监听器，避免频繁重排。
  • 异步导出处理：导出功能使用动态导入，避免阻塞主线程。
  • Mermaid 渲染容错：逐个容器渲染，单个失败不影响其他图表；失败时恢复原始内容。
  • 事件委托：代码复制与表格工具栏按钮在 document 捕获阶段一次性绑定，避免大量逐钮监听。
  • Canvas 优化：图片编辑使用两个 Canvas 分层，预览层仅临时绘制，确认后合成到原图尺寸。
  • 导出白底：SVG→PNG、html2canvas 导出固定白底，避免主题色影响离线可读性。

章节来源

可访问性支持 ​

  • 全屏模式：支持 Alt+F 快捷键、Esc 退出、Alt+双击进入，提供明确的标题和描述。
  • 主题切换菜单：具备 aria-expanded 状态，配合 chevron 旋转反馈。
  • 图片预览：支持键盘操作：Esc 关闭、左右方向键切换图片。
  • 代码块复制：与表格工具栏提供明确的 title 与语义化按钮。
  • 导出与复制：失败时通过 Toast 提示用户，并提供降级方案（如自动下载）。
  • Offscreen Document：在权限不足时提供剪贴板操作的降级方案。

章节来源

样式隔离与主题适配 ​

主题 Token 体系 ​

  • 所有颜色通过 CSS 变量 Token 管理，支持亮/暗/跟随系统三态。
  • 主题值由 theme.js 写入 <html data-theme>，CSS 通过 [data-theme="dark"] 覆盖暗色值。
  • 导出物（PNG/PDF/复制富文本）保持白底黑字，不受暗黑主题影响。
flowchart TD
Pref["用户偏好 light/dark/system"] --> Resolve["resolve() 计算生效主题"]
Resolve --> Apply["apply() 设置 <html data-theme>"]
Apply --> CSSVars["theme.css 变量生效"]
CSSVars --> Components["各组件样式消费 Token"]

图表来源

章节来源

样式模块化与响应式 ​

  • 全局重置与基础样式集中在 styles.css，使用 CSS 变量控制主题。
  • 全屏覆盖系统：z-index 10005，高于会话列表面板但低于自定义确认弹窗。
  • 头部工具栏：使用 flexbox 布局，支持按钮组和对齐。
  • 导出下拉菜单：绝对定位，带阴影和动画效果。
  • 窄屏媒体查询：隐藏部分文字、仅保留图标，提升小屏可用性。
  • 浮层与下拉面板：使用 backdrop-filter 与阴影 Token，确保在不同主题下可读。

章节来源

响应式设计优化 ​

  • 窄屏适配：在 420px 以下隐藏按钮文字，仅显示图标。
  • 超窄屏适配：在 320px 以下进一步简化头部元素。
  • 移动端优化：调整触摸目标大小，优化滚动体验。
  • 弹性布局：使用 flexbox 和 grid 实现自适应布局。

章节来源

故障排查指南 ​

  • 全屏模式异常：
    • 检查消息节点是否正确迁移到覆盖层。
    • 验证锚点节点是否存在且位置正确。
    • 确认流式跟随逻辑是否正常工作。
  • 导出功能失败：
    • 检查对应库是否加载成功（docx、pdf-lib、html2canvas）。
    • 验证内容预处理是否正确（Mermaid 渲染、SVG 转换）。
    • 确认文件格式生成和下载流程。
  • 复制功能异常：
    • 检查 ClipboardItem API 是否可用。
    • 验证 Offscreen Document 权限和通信。
    • 确认降级方案是否正常工作。
  • 主题切换异常：
    • 检查 theme.js 是否正确设置 data-theme。
    • 确认 CSS 中对应覆盖规则存在。
    • 验证导出功能应保持白底，不应受主题影响。

章节来源

结论 ​

该 UI 组件库围绕全屏覆盖系统、头部工具栏导出、增强复制功能、Markdown 渲染、图片处理、图标系统与通用工具函数构建，采用 CSS 变量 Token 主题体系与按需懒加载策略，兼顾性能、可访问性与主题一致性。新增的全屏模式和导出功能为用户提供了更好的阅读体验和内容分享能力，而增强的复制功能和响应式设计则提升了整体用户体验。开发者可基于现有组件快速构建新的界面元素，同时遵循安全清洗、白底导出、事件委托与容错渲染等最佳实践。

更新 本次更新显著增强了 UI 组件的功能完整性，特别是全屏阅读体验和多格式导出能力，为 AI 对话内容的深度阅读和分享提供了强有力的技术支持。