AionUi Preview 模块深度解析多 Tab 文件预览编辑系统与 Agent 流式更新机制【免费下载链接】AionUiOpen-source 24/7 Cowork app for OpenClaw, Hermes, Claude Code, Codex, OpenCode and 20 more CLI Agent | Customize your assistants | Team them upStar if you like it!项目地址: https://gitcode.com/GitHub_Trending/ai/AionUiPreview 模块是 AionUi 桌面端packages/desktop内置于会话页Conversation的文件预览与编辑子系统它让用户在 Agent 协作过程中无需切换窗口即可查看、编辑工作区中的 Markdown、代码、图片、PDF、Office 文档等多种文件并通过多 Tab 架构、分屏预览、实时流式更新与快捷键体系提供接近 IDE 的体验。读完本文你将掌握 Preview 模块的完整架构、Tab 生命周期与去重策略、Agent 写入文件的流式刷新与防抖机制、保存冲突的乐观并发处理以及如何基于其 Context 与自定义 Hooks 扩展新的文件类型与工具栏能力。一、模块概览Agent 工作流中的文件中枢Preview 模块位于packages/desktop/src/renderer/pages/conversation/Preview是 AionUi 会话页面的核心子模块之一。它的定位可以从三句话概括查看支持 Markdown、代码、图片、Diff、PDF、Word、Excel、PPT、HTML、URL 等多种格式的渲染编辑对 Markdown、代码、HTML 等文本类文件提供实时编辑能力CodeMirror 6 集成联动Agent 写文件时自动刷新预览、保存时与后端做乐观并发校验、并与会话发送框双向集成。该模块在 Agent 长时运行24/7 Cowork场景下尤其关键Agent 正在向工作区写入文件时Preview 面板会自动跟进内容变化用户无需手动刷新即可看到最新产物。二、多 Tab 管理2.1 Tab 生命周期Preview 模块采用多 Tab 架构每个文件在独立的 Tab 中显示同时打开多个文件互不干扰智能 Tab 复用相同文件不会重复打开Tab 溢出处理Tab 过多时自动显示左右渐变指示器并支持横向滚动右键菜单关闭当前 / 左侧 / 右侧 / 其他 / 未修改 / 全部 Tab以及复制绝对路径、复制工作区相对路径、在系统文件管理器中定位文件仅桌面端。Tab 数据结构定义于 PreviewContext.tsxinterface PreviewTab { id: string; content: string; content_type: PreviewContentType; metadata?: PreviewMetadata; title: string; // Tab 标题 isDirty?: boolean; // 是否有未保存的修改 originalContent?: string; // 原始内容用于 dirty 对比 }2.2 智能 Tab 复用两级身份匹配README 中描述的「文件路径 → 文件名 → 标题 → 内容」四级匹配链在最新源码中已被更严谨的两级身份匹配取代见 PreviewContext.tsxL1唯一权威两侧都携带ChatFileRef时比较chatFileRefKeyL2退路两侧都没有fileRef时比较基于「类型 内容 元数据」计算出的无引用键reflessTabKey混合情况一侧有 ref、一侧没有刻意返回「不匹配」——猜测式合并可能造成静默覆盖。代码注释明确指出旧实现中五级回退链ref → file_path → file_namepath → title → 全文内容曾造成真实损害不同目录下同名文件的两个 diff 被当成同一个 Tab 而相互覆盖。因此file_path现在刻意不作为回退键。另外browser类型从不参与去重——每个浏览器 Tab 都是用户或 Agent 有意打开的独立页面。打开 Tab 时的决策流程openPreview见 PreviewContext.tsx找到匹配 Tab直接激活若用户已编辑isDirty保留编辑内容、仅合并元数据否则更新内容与元数据未找到匹配 Tab创建新 Tab 并自动激活面板自动打开。openPreview还支持options.replace模式文件树浏览场景复用当前激活 Tab 而不是堆叠新 Tab但激活 Tab 存在未保存修改时自动回退为新建 Tab避免丢失改动。2.3 批量关闭与脏检测所有批量关闭操作关闭左侧/右侧/其他/未修改/全部以及收起面板都收敛到统一的requestCloseBatch入口见 PreviewPanel.tsx先检查批次内是否有 dirty Tab有则弹出确认对话框支持「保存并关闭」或「不保存关闭」全部干净则直接关闭。收起面板只改变可见性、保留并持久化 Tab但仍须通过脏检测避免「收起」成为静默丢弃未保存内容的通道。三、文件类型支持体系3.1 查看器Viewers类型扩展名查看器组件Markdown.md,.markdown,.mdown,.mkdMarkdownViewer.tsx代码所有文本文件默认类型CodeEditor / 语法高亮图片.png, .jpg, .jpeg, .gif, .svg, .webp, .bmp, .ico, .tif, .tiff, .avifImageViewer.tsxDiff.diff,.patchDiffViewer.tsxPDF.pdfPDFViewer.tsxWord.docxOfficeDocViewer.tsxExcel.xlsxExcelViewer.tsxPPT.pptxPptViewer.tsxHTML.html,.htmHTMLViewer.tsxCSV.csv纯文本渲染表格状结构但走文本分支URL / 浏览器无扩展名URLViewer.tsx / BrowserTabLayer3.2 编辑器Editors编辑器能力组件Markdown 编辑器实时预览、分屏模式、滚动同步、语法高亮MarkdownEditor.tsx代码编辑器CodeMirror 6 集成、语法高亮、自动补全、多语言CodeEditor.tsxHTML 编辑器代码编辑 实时 iframe 渲染、分屏HTMLEditor.tsx3.3 扩展名映射与「不支持」类型扩展名到内容类型的映射集中在 fileUtils.ts 的FILE_EXTENSION_MAP。与 README 早期版本相比当前实现做了更细致的分类word: [docx]、excel: [xlsx]、ppt: [pptx]—— 只保留 officecli 实际能渲染的 OOXML 三件套csv从excel中拆出独立类型officecli 完全拒绝.csv而 CSV 本就是纯文本按文本渲染远比在一个打不开它的表格渲染器里报错合理unsupported明确收纳能识别但确实无法渲染的格式doc/xls/ppt旧版 Office 二进制、odt/ods/odpODF、docm/xlsm/pptm宏文件、heicChromium 无 HEVC 解码器。对这些格式面板展示原因说明 「在系统中打开」逃生出口而不是把它们送进注定失败的渲染器见 PreviewPanel.tsx 的renderUnsupported。PreviewContentType的完整定义位于 common/types/office/preview.tsmarkdown | diff | code | html | pdf | ppt | word | excel | image | csv | unsupported | url | browser。3.4 超限文件与缺失文件超限oversized文件超过打开时快照的大小上限内容从未被读取只显示原因与文件大小说明 「在系统中打开」逃生按钮刻意不进入可保存的编辑器——半截内容进入编辑器会毁掉未读的剩余部分缺失missingFile文件不存在或不可读时展示友好提示并提供「在新标签页打开」的兜底链接。四、架构设计目录结构与职责划分模块目录结构与源码实际布局对应Preview/ ├── context/ # React Context │ ├── PreviewContext.tsx # 核心上下文Tab 管理、内容更新、保存、流式订阅 │ ├── PreviewToolbarExtrasContext.tsx # 工具栏扩展上下文 │ ├── previewScope.ts # 预览作用域隔离按项目/工作区持久化 │ ├── previewWatchStore.ts # 目录级文件变更订阅协调 │ └── reflessTabKey.ts / tabReloaderRegistry.ts ├── components/ │ ├── PreviewPanel/ # 主面板PreviewPanel / PreviewTabs / PreviewToolbar │ │ ├── PreviewContextMenu.tsx # Tab 右键菜单 │ │ ├── PreviewConfirmModals.tsx # 关闭/刷新确认对话框 │ │ ├── previewTabPaths.ts # Tab 路径解析绝对/相对路径 │ │ ├── refreshButtonState.ts # 刷新按钮状态机琥珀色提示 │ │ └── previewToolbarUtils.ts # 保存结果分类、批量脏检测等工具 │ ├── viewers/ # 查看器Markdown / Image / Diff / PDF / Office / Excel / PPT / HTML / URL │ ├── editors/ # 编辑器MarkdownEditor / CodeEditor(CodeMirror 6) / HTMLEditor │ └── renderers/ # HTMLRenderer(iframe) / SelectionToolbar / htmlInspectScript ├── browser/ # 应用内浏览器BrowserTabLayer / BrowserViewer / agentActivity ├── hooks/ # usePreviewKeyboardShortcuts / useScrollSync / useTabOverflow / useThemeDetection / useLocalFilePreview ├── theme/ # codeEditorTheme / codeEditorConfig / languageLoader / markdownTheme ├── types.ts # 类型定义重新导出 common 类型 ├── constants.ts # 常量配置 └── fileUtils.ts # 扩展名映射与文件类型判断五、核心 Context 详解5.1 PreviewContext模块心脏PreviewProvider见 PreviewContext.tsx持有面板状态、Tab 列表、激活 Tab并暴露全部操作 APIinterface PreviewContextValue { // 面板状态 isOpen: boolean; // 预览面板是否打开 isMaximized: boolean; // 是否最大化隐藏中间聊天区纯 session 级状态 tabs: PreviewTab[]; // 所有打开的 tabs activeTabId: string | null; // 当前激活的 tab ID activeTab: PreviewTab | null; // 当前激活的 tab // 操作 openPreview: (content: string, type: PreviewContentType, metadata?: PreviewMetadata, options?: OpenPreviewOptions) void; openBrowserTab: (url?: string) void; // 打开应用内浏览器 tab省略 url 则开空白页 closePreview: () void; // 仅收起面板保留并持久化 tabs toggleMaximized: () void; clearPreviewForScope: () void; // 彻底丢弃当前作用域的 tabs closeTab: (tabId: string) void; switchTab: (tabId: string) void; updateContent: (content: string) void; updateTab: (tabId: string, patch: PreviewTabPatch) void; // 后台 tab 标题/地址更新 saveContent: (tabId?: string) Promiseboolean; reloadTabContent: (tabId: string) Promiseboolean; // Tab 查找和管理 findPreviewTab: (type: PreviewContentType, content?: string, metadata?: PreviewMetadata) PreviewTab | null; closePreviewByIdentity: (type: PreviewContentType, content?: string, metadata?: PreviewMetadata) void; closePreviewIfScopeChanged: (scopeKey: PreviewScopeKey) void; // 发送框集成 addToSendBox: (text: string) void; setSendBoxHandler: (handler: ((text: string) void) | null) void; // 浏览器 tab 活动状态 / DOM 片段 / 待刷新标记等 browserTabLimitHitAt: number | null; persistQuotaExceededAt: number | null; tabsWithUpdate: ReadonlySetstring; clearTabUpdate: (tabId: string) void; domSnippets: DomSnippet[]; addDomSnippet: (tag: string, html: string) void; removeDomSnippet: (id: string) void; clearDomSnippets: () void; }几个值得注意的实现细节openPreview的所有决策都在调用setTabs之前基于tabsRef完成updater 只负责按决策产出新数组。这是为了兼容 React 的「急切求值」与 StrictMode 双调用——否则会出现「打开第二个 tab 不切焦点」的 bugupdateContent用「新内容 ≠ originalContent」判定isDirty并有严格的字符串类型检查防止 Event 对象被误传updateTab按tabId而不是activeTabId定位保证后台浏览器 tab也能同步页面标题、favicon 与 Agent 活动状态且不抢焦点通过useOptionalPreviewContext提供可选上下文文件树等「预览只是附带能力」的组件在 Provider 之外调用时返回null而非抛错。5.2 Preview 作用域隔离与持久化预览状态按preview scope项目 id缺省回退到 workspace 路径隔离持久化见 previewScope.ts同一项目内切换会话预览保持打开切换项目则持久化旧项目的 tabs、恢复新项目的 tabs 与可见性。存储键为preview-ui:scope与 Explorer 的explorer-ui:属于同一族。持久化策略见 PreviewContext.tsx单条文本内容上限80,000 字符超限的不持久化可重新获取的类型pdf/word/excel/ppt/unsupported/image只存身份fileRef不存内容字节——大图 data URL 可能耗尽 localStorage 配额并挤掉其他项目的 tab未保存的编辑按「未保存」原样持久化内容 originalContent dirty 标记重启后仍然保持 dirty 状态Cmd/Ctrl S仍可写入最多保留12 个 scopeLRU 淘汰savedAt时间戳驱动写满配额时先淘汰最冷 scope 重试一次仍失败则通过persistQuotaExceededAt在 UI 上显式告警——曾经的静默失败让用户切换项目后 tab 悄悄消失而毫无提示恢复时丢弃旧版本遗留的truncated: true标记 tab曾被截断到 40,000 字符的片段恢复会造成「部分内容冒充全文」登出时通过clearPersistedScopes清理全部 scope见clearPersistedPreviewScopes避免下一个账号看到上一个账号打开的文件内容。5.3 PreviewToolbarExtrasContext查看器组件通过该 Context 向工具栏注入自定义按钮见 PreviewToolbarExtrasContext.tsxinterface PreviewToolbarExtras { leftButtons?: React.ReactNode; // 工具栏左侧额外按钮 rightButtons?: React.ReactNode; // 工具栏右侧额外按钮 }六、流式更新机制6.1 订阅与防抖当 Agent 写入工作区文件时Preview 通过 IPC 桥自动接收流式更新事件通道定义于 ipcBridge.ts 的fileStream.contentUpdate无需手动刷新。核心订阅逻辑见 PreviewContext.tsxipcBridge.fileStream.contentUpdate.on(({ file_path, content, operation }) { if (operation delete) { // 文件被删除清除该文件的防抖定时器并关闭对应 Tab立即处理无需防抖 closeTabByFilePath(file_path); return; } // 写入操作500ms 防抖等待 Agent 完成一段连续写入后再更新预览 debounceTimers.get(file_path) clearTimeout(...); const timer setTimeout(() { /* 更新匹配 file_path 的 tabs */ }, 500); debounceTimers.set(file_path, timer); });防抖设计Agent 每次写入文件都触发事件系统等待 500ms 内没有新的写入才一次性更新预览内容。这样避免打字动画被频繁中断提供更流畅的观看体验——这是「实时性」与「流畅性」之间的刻意权衡也是 README FAQ 中「流式更新为什么有延迟」的答案。组件卸载时清理全部定时器。6.2 保存冲突处理为了避免用户保存与流式更新互相覆盖Preview 采用双重保护见 PreviewContext.tsx// 保存文件时标记按 ChatFileRef 身份键控 savingFilesRef.current.add(saveKey); // 流式更新时检查正在保存或用户已编辑则跳过更新 if ((savingKey savingFilesRef.current.has(savingKey)) || tab.isDirty) { return tab; // 跳过更新 }保存成功后延迟 500ms 移除保存标记给变更检测留出忽略本次写入的时间。更深一层的保护是If-Match 乐观并发打开 Tab 时记录metadata.lastModified作为已知 mtime保存时通过ipcBridge.fs.writeContent携带ifMatch若文件在此期间被外部修改后端返回 409 冲突handleSaveActiveTab明确提示「保存冲突」并保留 dirty 状态让用户可重试或复制走内容而不是静默覆盖见 PreviewPanel.tsx。6.3 目录级变更标记refresh 琥珀色提示除了 Agent 写入流Preview 还订阅目录级文件变更previewWatchStore后端报告「某目录有变化」时系统只把受影响 tab 标记进tabsWithUpdate琥珀色刷新提示不自动重载——自动替换屏幕上内容正是旧轮询器的做法会覆盖正在进行的编辑。用户决定何时通过刷新按钮读取新内容刷新前若有未保存修改会先弹确认对话框「放弃修改并重新加载」。七、使用示例7.1 基础用法import { PreviewProvider, usePreviewContext } from ./preview; function App() { return ( PreviewProvider YourComponent / /PreviewProvider ); } function YourComponent() { const { openPreview } usePreviewContext(); const handleOpenFile async (filePath: string) { const content await readFile(filePath); openPreview(content, markdown, { fileName: example.md, filePath: /path/to/example.md, workspace: /workspace/root, }); }; return button onClick{handleOpenFile}打开文件/button; }7.2 打开不同类型的文件// Markdown 文件 openPreview(markdownContent, markdown, { fileName: README.md, filePath: /workspace/README.md, workspace: /workspace, }); // 代码文件可指定 language 获得语法高亮 openPreview(codeContent, code, { fileName: app.tsx, filePath: /workspace/src/app.tsx, workspace: /workspace, language: typescript, }); // 图片文件base64 内容 openPreview(base64Content, image, { fileName: screenshot.png, filePath: /workspace/screenshot.png, workspace: /workspace, }); // Diff 文件 openPreview(diffContent, diff, { fileName: changes.diff, });注意对于带fileRefChatFileRef 身份的打开场景fileRef是内容读写的终极身份走/api/fs/content优于file_path/workspace——后者仅为尚未迁移的查看器pdf 的file://、office、系统打开、下载保留。7.3 查找和关闭 Tab// 查找 Tab const tab findPreviewTab(markdown, undefined, { filePath: /workspace/README.md, }); // 关闭特定 Tab if (tab) { closeTab(tab.id); } // 根据身份关闭 Tab如 Agent 完成写入后清理 closePreviewByIdentity(markdown, undefined, { filePath: /workspace/README.md, });7.4 集成发送框function SendBox() { const { setSendBoxHandler } usePreviewContext(); const [text, setText] useState(); useEffect(() { // 注册处理器预览中的内容可一键送入发送框 setSendBoxHandler((content) { setText((prev) prev content); }); return () { setSendBoxHandler(null); }; }, [setSendBoxHandler]); return textarea value{text} onChange{(e) setText(e.target.value)} /; }八、自定义 Hooks 解析8.1 usePreviewKeyboardShortcuts注册预览面板快捷键实现见 usePreviewKeyboardShortcuts.tsCmd/Ctrl S— 保存当前 Tab仅当isDirty时触发并阻止浏览器默认保存行为Cmd/Ctrl W— 关闭当前 Tab。Cmd/Ctrl W以scopeRef面板根元素限定作用域只有源自预览面板内部的按键才关闭 Tab在聊天区按下时保持原有含义。它刻意不回避代码编辑器——编辑过程中按下就是要关掉这个 Tab未保存内容由关闭确认弹窗兜底而不是靠吞掉快捷键来保护与其它应用级快捷键策略不同。e.isComposing输入法组合中、e.repeat、altKey、shiftKey等情形均被排除。usePreviewKeyboardShortcuts({ isDirty: activeTab?.isDirty, onSave: () saveContent(), onCloseActiveTab: () handleCloseTab(activeTabId), scopeRef: panelRootRef, });8.2 useScrollSync同步编辑器与预览的滚动位置基于滚动百分比同步见 useScrollSync.ts。为避免循环触发采用「同步锁 解锁」机制同步期间置位isSyncingRef优先用requestAnimationFrame解锁不可用时降级为setTimeoutSCROLL_SYNC_DEBOUNCE100ms。目标滚动百分比通过dataset.targetScrollPercent传递由各组件自行消费。const { handleEditorScroll, handlePreviewScroll } useScrollSync({ enabled: isSplitScreenEnabled, editorContainerRef, previewContainerRef, });8.3 useTabOverflow处理 Tab 栏横向溢出自动计算左右渐变指示器见 useTabOverflow.ts。判定逻辑内容宽度超过容器宽度即存在溢出左侧渐变在「有溢出且已向右滚动」时显示右侧渐变在「有溢出且未滚动到最右」时显示阈值TAB_OVERFLOW_THRESHOLD 2像素。事件监听方面实际源码使用scroll事件 window.resizeResizeObserver监听容器尺寸变化README 中提及的 IntersectionObserver 方案在当前实现中由 scroll/ResizeObserver 组合承担且仅当状态真正变化时才setState避免无谓重渲染。const { tabsContainerRef, tabFadeState } useTabOverflow([tabs, activeTabId]);8.4 useThemeDetection检测当前主题返回light | dark供查看器/编辑器适配主题实现见 useThemeDetection.tsconst currentTheme useThemeDetection(); // light | dark九、编辑模式与分屏9.1 进入编辑模式点击工具栏「编辑」按钮或双击内容区域进入编辑模式。可编辑类型由 constants.ts 中的EDITABLE_CONTENT_TYPES [markdown, html, code, csv]决定。以下类型只读、不可编辑PDF、Word、Excel、PPT各自走独立进程/查看器渲染图片可查看不可编辑超限oversized与不支持unsupported文件刻意不进入编辑器。编辑器功能一览Markdown 编辑器实时预览、分屏模式、滚动同步、语法高亮代码编辑器CodeMirror 6完整编辑能力、语法高亮、自动补全、多语言支持语言加载器见theme/languageLoader.ts主题与高亮样式见theme/codeEditorTheme.ts、theme/markdownHighlightStyle.tsHTML 编辑器实时渲染、分屏模式、代码编辑 实时预览。9.2 分屏模式点击工具栏分屏按钮启用。分屏模式下左侧编辑器、右侧预览支持拖拽中间分隔条调整比例默认 50/50见DEFAULT_SPLIT_RATIO比例自动保存到 LocalStorage存储键preview-panel-split-ratio通过useResizableSplit实现滚动同步移动端适配分屏时全屏显示预览、隐藏编辑器编辑本就是全屏覆盖层最大化按钮也随之隐藏切换视图模式时自动关闭分屏避免「上一个文件的 source 模式串到下一个文件」。9.3 保存与退出保存工具栏「保存」按钮或Cmd/Ctrl S保存失败或 409 冲突时分别给出明确提示退出工具栏「完成」按钮脏检测有未保存修改时退出/关闭/刷新均弹确认对话框提供「保存并关闭」「不保存关闭」「取消」。9.4 HTML 检查模式与 DOM 片段HTML 预览支持「检查」模式inspectMode点击页面元素即可捕获其 DOM 片段addDomSnippet用于把选中内容注入会话。domSnippets是会话级临时状态面板收起时随之清空。十、应用内浏览器Browser Tabs除文件预览外Preview 模块还内嵌了应用内浏览器browser/子目录含 BrowserTabLayer、agentActivity、firstUseNotice 等Tab 栏「」按钮、工作区下拉、Agent 三条入口统一走openBrowserTab保证空白页地址与兜底标题完全一致浏览器 tab 常驻挂载BrowserTabLayer始终渲染切换 Tab不会重新加载页面浏览器 tab 存在数量上限MAX_BROWSER_TABS达到上限时复用最旧 tab并通过browserTabLimitHitAt在 UI 上明确提示避免「复用」被误认为 bugAgent 活动角标通过监听工具调用流而非浏览器自身事件判断 Agent 是否正在操作某 tab——Agent 经 CDP 驱动 webview 时webview 只能看到「页面变了」分不清是用户还是 Agent 操作工具调用流是唯一能区分二者的信号。该订阅是纯锦上添花一个角标 一次首用提示消息流不可用时绝不能让整个预览面板挂掉。十一、性能优化Tab 智能复用两级身份匹配避免重复打开相同文件减少内存占用流式更新防抖500ms 防抖避免 Agent 高频写入导致的频繁渲染大文件优化持久化上限 80,000 字符图片使用 Base64 data URL 延迟加载查看器在content缺失时重新读取PDF/Office 交给独立进程/URL 流渲染CONTENT_FREE_PREVIEW_TYPES代码编辑器超过LARGE_TEXT_VIEWER_THRESHOLD 30_000字符时关闭语法高亮与折叠以保证响应内容不截断Tab 溢出优化scroll resize ResizeObserver 监听仅状态变化时更新避免无谓重渲染滚动同步节流requestAnimationFrame 优先、setTimeout 降级配合同步锁避免循环触发持久化写入防抖scope 状态写入 localStorage 带 150ms 防抖LRU 淘汰防止配额耗尽严格模式兼容updater 保持纯函数、决策前置兼顾 StrictMode 双调用与性能。十二、配置项常量配置constants.ts// 滚动同步防抖时间毫秒 export const SCROLL_SYNC_DEBOUNCE 100; // Tab 溢出检测阈值像素 export const TAB_OVERFLOW_THRESHOLD 2; // 左右渐变指示器宽度像素 export const TAB_FADE_INDICATOR_WIDTH 32; // 工具栏高度像素 export const TOOLBAR_HEIGHT 40; // 分屏默认比例% export const DEFAULT_SPLIT_RATIO 50; // 分屏最小宽度%—— 注意当前源码为 20README 早期版本描述的 30 已更新 export const MIN_SPLIT_WIDTH 20; // 分屏最大宽度%—— 当前源码为 80 export const MAX_SPLIT_WIDTH 80; // 代码编辑器降级阈值字符超过则关闭语法高亮与折叠以保持响应内容不截断 export const LARGE_TEXT_VIEWER_THRESHOLD 30_000; // 具有内置打开按钮的文件类型在系统中打开 export const FILE_TYPES_WITH_BUILTIN_OPEN [word, ppt, pdf, excel] as const; // 可编辑的内容类型 export const EDITABLE_CONTENT_TYPES [markdown, html, code, csv] as const;另有上下文内常量MAX_PERSISTED_SCOPES 12持久化 scope 上限、MAX_PERSISTED_TAB_CONTENT_LENGTH 80_000持久化文本上限。持久化键前缀preview-ui:定义于 previewScope.ts。十三、常见问题FAQQ: 如何添加新的文件类型支持在PreviewPanel.tsx的renderContent()中新增类型分支参见 PreviewPanel.tsx 现有的 markdown/html/code/csv/pdf/ppt/word/excel/image/url 分支在fileUtils.ts的FILE_EXTENSION_MAP中补充扩展名映射含unsupported等边界类型的取舍更新 common/types/office/preview.ts 中的PreviewContentType联合类型若需要持久化/刷新/可编辑能力还需关注PERSISTABLE_CONTENT_TYPES、REFETCHABLE_CONTENT_TYPES、EDITABLE_CONTENT_TYPES等集合的登记。Q: 如何自定义工具栏按钮在查看器组件中使用PreviewToolbarExtrasContextconst { setExtras } usePreviewToolbarExtrasContext(); useEffect(() { setExtras({ rightButtons: CustomButton /, }); return () setExtras(null); }, []);Q: 流式更新为什么有延迟流式更新使用 500ms 防抖等待 Agent 完成一段连续写入后才刷新预览避免打字动画被频繁中断。这是实时性与流畅性的刻意权衡删除操作不防抖、立即生效。Q: 如何禁用流式更新流式更新是自动的无法禁用。如果不希望接收更新可以进入编辑模式——流式回调会检查tab.isDirty并跳过更新自己保存中的文件也会被savingFilesRef保护。Q: 为什么有些文件无法编辑PDF、Word、Excel、PPT 由独立进程/查看器渲染只读图片可查看不可编辑.doc/.xls/.ppt旧版 Office 与.odt/.ods/.odp、宏文件、HEIC 属于「可识别但无法渲染」的unsupported类型提供原因说明与「在系统中打开」逃生出口。Q: 刷新按钮什么时候变琥珀色当后端报告某个已打开文件在磁盘上发生变化目录级previewWatchStore信号命中该 tab且尚未重新读取时刷新按钮进入琥珀色状态。用户点击刷新有未保存修改先弹确认无修改则从磁盘重读内容并清除标记。PDF/Office 等无内容类型走各自的查看器刷新通道tabReloaderRegistry。十四、相关源码导航核心 Context 与流式更新context/PreviewContext.tsx主面板与视图分发components/PreviewPanel/PreviewPanel.tsx扩展名映射与类型判断fileUtils.ts常量配置constants.ts快捷键实现hooks/usePreviewKeyboardShortcuts.ts滚动同步hooks/useScrollSync.tsTab 溢出hooks/useTabOverflow.ts作用域隔离与持久化键context/previewScope.ts内容类型联合类型common/types/office/preview.ts文件流事件通道fileStream.contentUpdatecommon/adapter/ipcBridge.ts英文版模块文档Preview/README.en.md相关单元测试覆盖了本模块的关键行为可作进一步研读的入口tests/unit/previews/目录下的 fileTypeMatrix.test.ts、previewUrls.dom.test.ts、previewScopeLru.dom.test.tsx、previewScopePersistTypes.dom.test.tsx、previewTabPaths.test.ts、previewWatchSignal.dom.test.tsx 等分别验证了类型矩阵、持久化 LRU、作用域隔离与变更信号等核心逻辑。【免费下载链接】AionUiOpen-source 24/7 Cowork app for OpenClaw, Hermes, Claude Code, Codex, OpenCode and 20 more CLI Agent | Customize your assistants | Team them upStar if you like it!项目地址: https://gitcode.com/GitHub_Trending/ai/AionUi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考