Cherry Studio 文件预览体系深度解析FilePreview 宿主架构、插件注册表与多格式渲染实现【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studioFilePreview是 Cherry Studio 渲染进程中本地文件的标准只读预览宿主调用方只负责提供文件路径与决定预览出现的位置宿主负责校验路径目标、选择预览策略而真正执行文件 I/O、格式渲染、工具栏控制与格式专属状态管理的是匹配到的格式插件。本文基于 FilePreview README 及src/renderer/components/FilePreview/下的源码实现系统讲解路径契约、嵌入与标签页两种宿主组合方式、插件注册机制、内置格式支持、状态路由模型与 I/O 安全边界并给出新增格式插件的完整步骤适合需要接入文件预览能力或扩展新格式的开发者阅读。组件定位与内置格式支持FilePreview是一个纯只读预览宿主canonical read-only preview host。它不关心业务页面如何进入预览、也不持有页面级导航状态调用方传入一个本地绝对路径宿主负责路径校验、目标分类、插件选择与渲染各格式插件则完全拥有自己的文件读取、渲染、工具栏与状态。当前内置插件支持的格式如下类别支持格式渲染方式要点HTML.html、.htm默认走无脚本沙箱与严格 CSPtypeartifact时使用可执行脚本的交互式 artifact 沙箱图片.jpg、.jpeg、.png、.gif、.bmp、.webp、.avif、.ico、.svgSVG 通过img渲染绝不执行内嵌脚本PDF.pdf基于 pdf.js 的 Range 传输按需分块读取Word.docxOffice Zip 预检后解析PowerPoint.pptxOffice Zip 预检后解析电子表格.xlsx含图表、公式、网格渲染的完整解析管线Markdown.md、.markdown、.mdx支持预览/源码切换与工作区相对链接解析文本/源码文本扩展名白名单内容嗅探识别为文本的任意文件也会回退到文本插件值得注意的边界行为白名单之外的文件只要内容嗅探content sniffing判定为文本仍然会使用文本插件渲染。这一点在宿主源码 FilePreview.tsx 中有直接体现当没有注册插件或插件属于文本类html、markdown、text时宿主依据预检元数据的metadata.type text决定是否回退到textFilePreviewPlugin反之若扩展名命中了非文本插件但元数据显示不是文本插件会被置空避免用错误策略渲染二进制文件。路径契约Path ContractFilePreview对输入路径有严格约束这是安全与可移植性的第一道防线只接受本地绝对路径AbsoluteFilePath同时支持 POSIX 与 Windows 路径含 UNC 路径禁止相对路径、file://URL、HTTP URL、Base64 数据或内存数据宿主在解析插件前只做词法规范化lexically normalize不会解析符号链接、不会调用realpath宿主会并行启动扩展插件模块加载与getMetadata预检但最终由元数据决定候选插件是否能渲染目录directory与不可访问路径永远不会进入文件插件组件当路径来自 IPC 或其他非类型化字符串来源时必须用normalizeFilePreviewPath做运行时校验不要用类型断言绕过校验。normalizeFilePreviewPath的实现位于 src/renderer/utils/filePreview.tsimport { normalizeFilePreviewPath } from renderer/utils/filePreview const filePath normalizeFilePreviewPath(physicalPath)从源码看该函数对以\\或//开头的路径走专门的normalizeUncFilePreviewPath分支处理 UNC 路径的段折叠与..回退其余路径调用canonicalizeFilePath词法规范化后经createFilePathHandle生成标准文件句柄最终返回AbsoluteFilePathSchema.parse(...)的结果——校验失败会直接抛错宿主捕获后呈现invalid_path状态。配套工具还包括跨平台取文件名getFilePreviewFileName按/与\同时切分与取扩展名getFilePreviewExtension无点号、统一小写供注册表匹配。两种宿主组合方式嵌入预览与标签页预览是宿主的组合选择host composition choices不是FilePreview的展示变体。如果用户需要在两种模式间切换切换状态应保存在调用页面中嵌入模式设置当前filePath标签页模式调用openFilePreviewTab(filePath)。不要把模式状态下沉到FilePreview内部。嵌入预览Embedded Preview从模块根导入FilePreview放入一个具有确定可用高度的父容器中组件会填满父容器滚动由插件内容区负责。import { Button } from cherrystudio/ui import { FilePreview } from renderer/components/FilePreview import type { AbsoluteFilePath } from shared/types/file import { useTranslation } from react-i18next interface FileDetailsProps { fileName: string filePath: AbsoluteFilePath onBack: () void refreshKey?: number } export function FileDetails({ fileName, filePath, onBack, refreshKey }: FileDetailsProps) { const { t } useTranslation() return ( section classNameflex min-h-0 flex-1 FilePreview filePath{filePath} refreshKey{refreshKey} header{ Button onClick{onBack}{t(common.back)}/Button span classNametruncate{fileName}/span / } / /section ) }嵌入宿主拥有返回、关闭、文件选择等页面级交互这些控件以header内容传入与插件工具栏共享固定顶行。FilePreview会将调用方内容保持在左侧并把活动插件的工具栏通过 Portal 挂到右侧详见 FilePreviewToolbar.tsx 中FilePreviewToolbarPortalProvider/FilePreviewToolbarPortalHost的实现header存在时工具栏渲染在顶行右侧的 portal 目标内最多占 70% 宽度并可横向滚动。不要把格式控制类控件塞进header也不要向FilePreview添加embedded、showBackButton等页面专属回调。当嵌入宿主拥有应用内文件导航时用FilePreviewNavigationProvider包裹预览并提供工作区根与绝对路径 opener见 FilePreviewNavigationProvider.tsx。这样 Markdown 插件可以把无 scheme 链接解析为相对工作区根的绝对目标并交还宿主打开。需要注意该 Provider 不强制工作区包含性——绝对链接及用..词法逃逸出根目录的相对链接都可能解析到根之外访问策略由宿主自己负责。未提供此能力时预览保留 Streamdown 默认的安全链接处理。标签页预览Tab Preview在TabsProvider之下使用useOpenFilePreviewTab钩子实现见 hooks/useOpenFilePreviewTab.ts。钩子会规范化路径、生成 URL 编码的/app/file-preview?path...目标并以跨平台 basename 作为标签标题。import { Button } from cherrystudio/ui import { useOpenFilePreviewTab } from renderer/components/FilePreview import type { AbsoluteFilePath } from shared/types/file import { useTranslation } from react-i18next export function OpenPreviewButton({ filePath }: { filePath: AbsoluteFilePath }) { const { t } useTranslation() const openFilePreviewTab useOpenFilePreviewTab() return Button onClick{() openFilePreviewTab(filePath)}{t(common.open_in_new_tab)}/Button }钩子的关键语义与 filePreview.ts 的createFilePreviewTabTarget呼应钩子不设置forceNew等价的规范化路径产生相同 URL因此复用已有标签页重新打开已有标签页会将其内部 refresh key递增使已挂载的插件重新读取文件当显示名与物理路径 basename 不同时可传第二个可选参数作为显示名返回值是标签 ID供调用方需要时使用。FILE_PREVIEW_REFRESH_KEY元数据字段在 filePreview.ts 定义getFilePreviewRefreshKey负责安全地读取仅接受安全整数且非负否则回退 0。路由搜索参数解析由parseFilePreviewRouteSearch完成——它会对path参数再次调用normalizeFilePreviewPath解析失败则返回{ path: undefined }交由宿主呈现无效路径状态。插件结构Plugin Structure每种格式是一个位于plugins/format/下的独立插件推荐目录结构plugins/example/ ├── ExampleFilePreview.tsx ├── ExampleFilePreviewToolbar.tsx # 仅当插件有控件时创建 ├── __tests__/ │ └── ExampleFilePreview.test.tsx └── exampleFilePreviewPlugin.ts插件描述符描述符只声明身份、扩展名与懒加载入口不包含任何渲染逻辑import type { FilePreviewPlugin } from ../../types export const exampleFilePreviewPlugin { id: example, extensions: [example, example2], load: () import(./ExampleFilePreview) } satisfies FilePreviewPluginFilePreviewPlugin的类型定义位于 types.ts要求load返回一个带defaultReact 组件的模块。描述符规则如下id必须在注册表内稳定且唯一extensions必须全小写且不带前导点写pdf不要写.pdf或PDF一个扩展名只能属于一个插件重复扩展名在注册表创建时直接抛错load必须解析为带 default 组件导出的模块大型渲染库应留在懒加载模块内而不是描述符里注册表是静态配置没有运行时注册、优先级或调用方覆盖 API。注册表的创建逻辑在 filePreviewRegistry.ts 中createFilePreviewRegistry遍历所有插件描述符逐扩展名写入Mapstring, FilePreviewPlugin期间调用normalizeExt校验扩展名格式不合法抛Invalid file preview extension发现重复扩展名抛Duplicate file preview extension。resolveExtensionPlugin则用getFilePreviewExtension取小写扩展名后查表未命中返回null。插件组件插件组件接收规范化路径、提取出的文件名、预检过的文件元数据以及必需的 refresh keyinterface FilePreviewPluginProps { filePath: AbsoluteFilePath fileName: string metadata: FilePreviewFileMetadata refreshKey: number type?: artifact | file }预览组件必须使用default 导出自行读取文件并组合模块内部布局import { FilePreviewLayout } from ../../FilePreviewLayout import type { FilePreviewPluginProps } from ../../types import { ExampleFilePreviewToolbar } from ./ExampleFilePreviewToolbar export default function ExampleFilePreview({ filePath, fileName, metadata, refreshKey }: FilePreviewPluginProps) { // Load in an effect that depends on filePath and refreshKey. The plugin owns // file loading, view state, and toolbar actions here. return ( FilePreviewLayout.Frame ExampleFilePreviewToolbar disabled{false} / FilePreviewLayout.Content div{fileName} ({metadata.size} bytes)/div /FilePreviewLayout.Content /FilePreviewLayout.Frame ) }插件实现完成后在filePreviewRegistry.ts中显式导入并加入extensionPlugins数组export const filePreviewRegistry createFilePreviewRegistry({ extensionPlugins: [imageFilePreviewPlugin, exampleFilePreviewPlugin] })真实描述符示例可参考 HTML 插件 htmlFilePreviewPlugin.tsid: html、extensions: [html, htm]、load: () import(./HtmlFilePreview)。当前注册表共挂载 8 个插件html、image、markdown、pdf、powerpoint、spreadsheet、text、word见 filePreviewRegistry.ts。宿主的预加载机制从 FilePreview.tsx 可以看到一个值得借鉴的细节宿主通过preloadFilePreviewPlugin用Promise.resolve().then(() descriptor.load())提前触发插件模块加载与元数据预检并行同时捕获 rejection 避免未处理 Promise 警告但React.lazy只会在元数据判定该候选可渲染时观察到原始 rejectionvoid modulePromise.catch(() {})注释说明了这一设计。插件渲染时再经lazy(() plugin.modulePromise)包装配合Suspense加载态与ErrorBoundary渲染错误回退见 FilePreview.tsx。组合规则Composition Rules公开的FilePreviewprops 保持最小化filePath、可选header、可选refreshKey、可选type。新增格式或能力时应遵守以下边界格式差异用独立插件表达不要给FilePreview增加isPdf、isImage之类的布尔开关插件拥有自己的加载状态、视图状态与动作其工具栏只接收渲染所需的状态与回调每个插件的工具栏放在独立的FormatFilePreviewToolbar.tsx组件中插件没有控件时应完全省略工具栏而不是渲染空行用FilePreviewToolbar组合工具栏内容图标命令用FilePreviewToolbarButton模式选择用SegmentedControl等合适的 UI 原语渲染器与文件加载生命周期保持在插件目录内不要包一层既有页面或旧预览面板——应把调用方迁移到FilePreview而不是让新插件反向耦合旧实现互斥的插件视图用显式联合类型表达如preview | source而不是多个相互作用的布尔值插件能力留在插件内不要向调用方暴露工具栏插槽也不要让调用页面管理格式专属状态typefile是任意路径的默认值必须保持不受信任 HTML 的无脚本渲染typeartifact仅用于显式的开发产物development artifact表面它故意运行生成的 HTML 并拥有源码/编辑体验。没有 artifact 专属策略的插件会忽略它格式控件仍保持可见header只作为宿主拥有的导航与身份内容。当它缺失时插件工具栏在 Tab 预览与独立预览中保持居中于自己的行内。这套组合方式让同一个插件无需格式分支即可同时工作在嵌入与标签页两种宿主中。typeartifact 与安全边界typeartifact用于显式的开发产物表面宿主拥有编辑权Markdown 与 HTML 保持渲染预览模式并省略预览/源码切换而 HTML 使用交互式 artifact 沙箱允许生成的应用执行脚本。该模式不会隐藏格式专属控件如 PDF 缩放、图片变换。其余所有调用方默认typefile本地 HTML 被视为不受信任内容用无脚本沙箱与严格 CSP 渲染并保留插件拥有的预览/源码切换。不要仅为了启用脚本就把任意本地文件标记为 artifact。文件 I/O、状态与错误模型打开前的目标分类打开入口应先对点击路径分类再选择 UI目录直接在文件浏览器中打开不进入预览选择具体文件交给FilePreview缺失或不可访问的文件选择也交给FilePreview由它呈现不可用unavailable状态。路由决策表FilePreview使用的路由模型如下目标预览决策结果目录不进入文件插件文件浏览器表面直接传入时呈防御性文件夹状态已注册二进制插件的现有文件注册插件内联预览Artifact HTML带 artifact 策略的 HTML 插件交互式内联预览宿主拥有源码/编辑已注册文本插件的现有文本文件内容嗅探后使用注册插件内联预览无注册扩展名的现有文本文件文本回退插件源码预览无注册插件的现有二进制文件不支持unsupported说明 安全的默认应用打开动作缺失或不可访问路径不可用unavailable说明无打开动作无效或非绝对路径无效invalid说明无打开动作宿主实现中状态种类FilePreviewStateKind定义为directory | invalid_path | load_error | unavailable | unsupportedFilePreview.tsx文案统一走file_preview.*i18n 键。需要特别说明的是只有unsupported状态可以回退到外部默认应用打开源码注释明确了原因——此时路径已通过校验、指向真实文件只是无法内联渲染且safeOpen会执行不安全扩展名策略invalid_path状态下绝不提供打开动作。I/O 规范与传输层防护文本读取用window.api.fs.readTextwindow.api.fs.read仅用于插件依据预检文件大小限定边界的整文件二进制读取大型或按需读取的二进制格式必须用类型化的ipcApi.request(file.read, ...)区间读取range read而不是加载整个文件组合多个区间读取的传输层在分配缓冲区前必须封顶组装后的区间大小并拒绝以下响应读取之间version变化或version.size与预检的metadata.size不一致必须使用预检过的metadataprop 做大小守卫插件不得再发第二次元数据请求加载 effect 必须包含filePath与refreshKey新的 refresh key 意味着即使路径不变也必须重新读取文件组件卸载、filePath变化或refreshKey变化时必须取消/断开/销毁文件读取、worker、监听器与第三方实例。PDF 传输层是最佳范例PdfFileRangeTransport.ts它以 1 MiBPDF_RANGE_CHUNK_SIZE_BYTES为单位通过file.read区间读取把每个组装后的 pdf.js range 封顶在 16 MiBPDF_MAX_ASSEMBLED_RANGE_BYTES。超限抛PdfRangeTooLargeError。这不是 PDF 文件大小上限更大的文件依然可以预览只要每个请求的区间在封顶之内。若某个 PDF 需要超过封顶的连续区间就必须提供显式的“外部打开”回退要移除该上限需要改为不在渲染器内组装的流式传输。传输层还校验每个 chunk 的version一致性、短读Short PDF read与非法区间参数。错误所有权FilePreview拥有目录、无效路径、不可用路径、不支持格式、插件加载失败、同步渲染错误等状态渲染错误由ErrorBoundary的PluginErrorFallback承接见 FilePreview.tsx插件拥有自己的加载中、空、过大与读取错误状态并且必须捕获 effect 与事件处理器中的异步失败让错误保持在预览区域内读取失败通过loggerService记录并在错误状态中暴露足够诊断信息使失败可定位、可处理。UI 与文案规范新 UI 使用cherrystudio/ui与 Tailwind CSS遵循仓库 DESIGN.md 设计规范工具栏使用 Lucide 图标图标按钮必须具有可访问名称与 tooltip插件专属文案放file_preview.*i18n 键下共享控件复用已有common.*或preview.*键并同步更新en-us与zh-cn工具栏保持稳定高度只有FilePreviewLayout.Content拥有内容滚动。验证Verification新插件至少需要覆盖以下测试场景仓库内已有对应 Vitest 用例可参考如 plugins/**/tests下的各格式测试与tests/filePreviewRegistry.test.ts扩展名能正确解析到对应插件且不与既有扩展名冲突重复扩展名应使注册表创建抛错懒加载组件收到规范化的filePath、正确的fileName、预检的metadata与当前refreshKey加载中、成功、空与读取错误状态保持在预览区域内工具栏动作、禁用状态与清理行为符合预期。按仓库约定先运行聚焦插件与注册表的 Vitest 套件再执行仓库要求的格式化与静态检查。相关测试基础设施还可参考 frontend-testing 指南。小结一套插件两种宿主FilePreview的设计核心是职责切分宿主只做路径校验、元数据预检、插件路由与状态兜底格式能力全部内聚在独立插件中。嵌入预览与标签页预览作为宿主的组合选择共享同一套插件避免了对每种格式编写两套预览面板。新增格式时只需遵循“描述符 default 组件 独立工具栏 注册表登记 测试覆盖”的固定模式即可复用已有的安全路径契约、懒加载机制、portal 工具栏与错误模型让 Cherry Studio 的文件预览体系保持可扩展性与安全性兼备。【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Cherry Studio 文件预览体系深度解析：FilePreview 宿主架构、插件注册表与多格式渲染实现
Cherry Studio 文件预览体系深度解析FilePreview 宿主架构、插件注册表与多格式渲染实现【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studioFilePreview是 Cherry Studio 渲染进程中本地文件的标准只读预览宿主调用方只负责提供文件路径与决定预览出现的位置宿主负责校验路径目标、选择预览策略而真正执行文件 I/O、格式渲染、工具栏控制与格式专属状态管理的是匹配到的格式插件。本文基于 FilePreview README 及src/renderer/components/FilePreview/下的源码实现系统讲解路径契约、嵌入与标签页两种宿主组合方式、插件注册机制、内置格式支持、状态路由模型与 I/O 安全边界并给出新增格式插件的完整步骤适合需要接入文件预览能力或扩展新格式的开发者阅读。组件定位与内置格式支持FilePreview是一个纯只读预览宿主canonical read-only preview host。它不关心业务页面如何进入预览、也不持有页面级导航状态调用方传入一个本地绝对路径宿主负责路径校验、目标分类、插件选择与渲染各格式插件则完全拥有自己的文件读取、渲染、工具栏与状态。当前内置插件支持的格式如下类别支持格式渲染方式要点HTML.html、.htm默认走无脚本沙箱与严格 CSPtypeartifact时使用可执行脚本的交互式 artifact 沙箱图片.jpg、.jpeg、.png、.gif、.bmp、.webp、.avif、.ico、.svgSVG 通过img渲染绝不执行内嵌脚本PDF.pdf基于 pdf.js 的 Range 传输按需分块读取Word.docxOffice Zip 预检后解析PowerPoint.pptxOffice Zip 预检后解析电子表格.xlsx含图表、公式、网格渲染的完整解析管线Markdown.md、.markdown、.mdx支持预览/源码切换与工作区相对链接解析文本/源码文本扩展名白名单内容嗅探识别为文本的任意文件也会回退到文本插件值得注意的边界行为白名单之外的文件只要内容嗅探content sniffing判定为文本仍然会使用文本插件渲染。这一点在宿主源码 FilePreview.tsx 中有直接体现当没有注册插件或插件属于文本类html、markdown、text时宿主依据预检元数据的metadata.type text决定是否回退到textFilePreviewPlugin反之若扩展名命中了非文本插件但元数据显示不是文本插件会被置空避免用错误策略渲染二进制文件。路径契约Path ContractFilePreview对输入路径有严格约束这是安全与可移植性的第一道防线只接受本地绝对路径AbsoluteFilePath同时支持 POSIX 与 Windows 路径含 UNC 路径禁止相对路径、file://URL、HTTP URL、Base64 数据或内存数据宿主在解析插件前只做词法规范化lexically normalize不会解析符号链接、不会调用realpath宿主会并行启动扩展插件模块加载与getMetadata预检但最终由元数据决定候选插件是否能渲染目录directory与不可访问路径永远不会进入文件插件组件当路径来自 IPC 或其他非类型化字符串来源时必须用normalizeFilePreviewPath做运行时校验不要用类型断言绕过校验。normalizeFilePreviewPath的实现位于 src/renderer/utils/filePreview.tsimport { normalizeFilePreviewPath } from renderer/utils/filePreview const filePath normalizeFilePreviewPath(physicalPath)从源码看该函数对以\\或//开头的路径走专门的normalizeUncFilePreviewPath分支处理 UNC 路径的段折叠与..回退其余路径调用canonicalizeFilePath词法规范化后经createFilePathHandle生成标准文件句柄最终返回AbsoluteFilePathSchema.parse(...)的结果——校验失败会直接抛错宿主捕获后呈现invalid_path状态。配套工具还包括跨平台取文件名getFilePreviewFileName按/与\同时切分与取扩展名getFilePreviewExtension无点号、统一小写供注册表匹配。两种宿主组合方式嵌入预览与标签页预览是宿主的组合选择host composition choices不是FilePreview的展示变体。如果用户需要在两种模式间切换切换状态应保存在调用页面中嵌入模式设置当前filePath标签页模式调用openFilePreviewTab(filePath)。不要把模式状态下沉到FilePreview内部。嵌入预览Embedded Preview从模块根导入FilePreview放入一个具有确定可用高度的父容器中组件会填满父容器滚动由插件内容区负责。import { Button } from cherrystudio/ui import { FilePreview } from renderer/components/FilePreview import type { AbsoluteFilePath } from shared/types/file import { useTranslation } from react-i18next interface FileDetailsProps { fileName: string filePath: AbsoluteFilePath onBack: () void refreshKey?: number } export function FileDetails({ fileName, filePath, onBack, refreshKey }: FileDetailsProps) { const { t } useTranslation() return ( section classNameflex min-h-0 flex-1 FilePreview filePath{filePath} refreshKey{refreshKey} header{ Button onClick{onBack}{t(common.back)}/Button span classNametruncate{fileName}/span / } / /section ) }嵌入宿主拥有返回、关闭、文件选择等页面级交互这些控件以header内容传入与插件工具栏共享固定顶行。FilePreview会将调用方内容保持在左侧并把活动插件的工具栏通过 Portal 挂到右侧详见 FilePreviewToolbar.tsx 中FilePreviewToolbarPortalProvider/FilePreviewToolbarPortalHost的实现header存在时工具栏渲染在顶行右侧的 portal 目标内最多占 70% 宽度并可横向滚动。不要把格式控制类控件塞进header也不要向FilePreview添加embedded、showBackButton等页面专属回调。当嵌入宿主拥有应用内文件导航时用FilePreviewNavigationProvider包裹预览并提供工作区根与绝对路径 opener见 FilePreviewNavigationProvider.tsx。这样 Markdown 插件可以把无 scheme 链接解析为相对工作区根的绝对目标并交还宿主打开。需要注意该 Provider 不强制工作区包含性——绝对链接及用..词法逃逸出根目录的相对链接都可能解析到根之外访问策略由宿主自己负责。未提供此能力时预览保留 Streamdown 默认的安全链接处理。标签页预览Tab Preview在TabsProvider之下使用useOpenFilePreviewTab钩子实现见 hooks/useOpenFilePreviewTab.ts。钩子会规范化路径、生成 URL 编码的/app/file-preview?path...目标并以跨平台 basename 作为标签标题。import { Button } from cherrystudio/ui import { useOpenFilePreviewTab } from renderer/components/FilePreview import type { AbsoluteFilePath } from shared/types/file import { useTranslation } from react-i18next export function OpenPreviewButton({ filePath }: { filePath: AbsoluteFilePath }) { const { t } useTranslation() const openFilePreviewTab useOpenFilePreviewTab() return Button onClick{() openFilePreviewTab(filePath)}{t(common.open_in_new_tab)}/Button }钩子的关键语义与 filePreview.ts 的createFilePreviewTabTarget呼应钩子不设置forceNew等价的规范化路径产生相同 URL因此复用已有标签页重新打开已有标签页会将其内部 refresh key递增使已挂载的插件重新读取文件当显示名与物理路径 basename 不同时可传第二个可选参数作为显示名返回值是标签 ID供调用方需要时使用。FILE_PREVIEW_REFRESH_KEY元数据字段在 filePreview.ts 定义getFilePreviewRefreshKey负责安全地读取仅接受安全整数且非负否则回退 0。路由搜索参数解析由parseFilePreviewRouteSearch完成——它会对path参数再次调用normalizeFilePreviewPath解析失败则返回{ path: undefined }交由宿主呈现无效路径状态。插件结构Plugin Structure每种格式是一个位于plugins/format/下的独立插件推荐目录结构plugins/example/ ├── ExampleFilePreview.tsx ├── ExampleFilePreviewToolbar.tsx # 仅当插件有控件时创建 ├── __tests__/ │ └── ExampleFilePreview.test.tsx └── exampleFilePreviewPlugin.ts插件描述符描述符只声明身份、扩展名与懒加载入口不包含任何渲染逻辑import type { FilePreviewPlugin } from ../../types export const exampleFilePreviewPlugin { id: example, extensions: [example, example2], load: () import(./ExampleFilePreview) } satisfies FilePreviewPluginFilePreviewPlugin的类型定义位于 types.ts要求load返回一个带defaultReact 组件的模块。描述符规则如下id必须在注册表内稳定且唯一extensions必须全小写且不带前导点写pdf不要写.pdf或PDF一个扩展名只能属于一个插件重复扩展名在注册表创建时直接抛错load必须解析为带 default 组件导出的模块大型渲染库应留在懒加载模块内而不是描述符里注册表是静态配置没有运行时注册、优先级或调用方覆盖 API。注册表的创建逻辑在 filePreviewRegistry.ts 中createFilePreviewRegistry遍历所有插件描述符逐扩展名写入Mapstring, FilePreviewPlugin期间调用normalizeExt校验扩展名格式不合法抛Invalid file preview extension发现重复扩展名抛Duplicate file preview extension。resolveExtensionPlugin则用getFilePreviewExtension取小写扩展名后查表未命中返回null。插件组件插件组件接收规范化路径、提取出的文件名、预检过的文件元数据以及必需的 refresh keyinterface FilePreviewPluginProps { filePath: AbsoluteFilePath fileName: string metadata: FilePreviewFileMetadata refreshKey: number type?: artifact | file }预览组件必须使用default 导出自行读取文件并组合模块内部布局import { FilePreviewLayout } from ../../FilePreviewLayout import type { FilePreviewPluginProps } from ../../types import { ExampleFilePreviewToolbar } from ./ExampleFilePreviewToolbar export default function ExampleFilePreview({ filePath, fileName, metadata, refreshKey }: FilePreviewPluginProps) { // Load in an effect that depends on filePath and refreshKey. The plugin owns // file loading, view state, and toolbar actions here. return ( FilePreviewLayout.Frame ExampleFilePreviewToolbar disabled{false} / FilePreviewLayout.Content div{fileName} ({metadata.size} bytes)/div /FilePreviewLayout.Content /FilePreviewLayout.Frame ) }插件实现完成后在filePreviewRegistry.ts中显式导入并加入extensionPlugins数组export const filePreviewRegistry createFilePreviewRegistry({ extensionPlugins: [imageFilePreviewPlugin, exampleFilePreviewPlugin] })真实描述符示例可参考 HTML 插件 htmlFilePreviewPlugin.tsid: html、extensions: [html, htm]、load: () import(./HtmlFilePreview)。当前注册表共挂载 8 个插件html、image、markdown、pdf、powerpoint、spreadsheet、text、word见 filePreviewRegistry.ts。宿主的预加载机制从 FilePreview.tsx 可以看到一个值得借鉴的细节宿主通过preloadFilePreviewPlugin用Promise.resolve().then(() descriptor.load())提前触发插件模块加载与元数据预检并行同时捕获 rejection 避免未处理 Promise 警告但React.lazy只会在元数据判定该候选可渲染时观察到原始 rejectionvoid modulePromise.catch(() {})注释说明了这一设计。插件渲染时再经lazy(() plugin.modulePromise)包装配合Suspense加载态与ErrorBoundary渲染错误回退见 FilePreview.tsx。组合规则Composition Rules公开的FilePreviewprops 保持最小化filePath、可选header、可选refreshKey、可选type。新增格式或能力时应遵守以下边界格式差异用独立插件表达不要给FilePreview增加isPdf、isImage之类的布尔开关插件拥有自己的加载状态、视图状态与动作其工具栏只接收渲染所需的状态与回调每个插件的工具栏放在独立的FormatFilePreviewToolbar.tsx组件中插件没有控件时应完全省略工具栏而不是渲染空行用FilePreviewToolbar组合工具栏内容图标命令用FilePreviewToolbarButton模式选择用SegmentedControl等合适的 UI 原语渲染器与文件加载生命周期保持在插件目录内不要包一层既有页面或旧预览面板——应把调用方迁移到FilePreview而不是让新插件反向耦合旧实现互斥的插件视图用显式联合类型表达如preview | source而不是多个相互作用的布尔值插件能力留在插件内不要向调用方暴露工具栏插槽也不要让调用页面管理格式专属状态typefile是任意路径的默认值必须保持不受信任 HTML 的无脚本渲染typeartifact仅用于显式的开发产物development artifact表面它故意运行生成的 HTML 并拥有源码/编辑体验。没有 artifact 专属策略的插件会忽略它格式控件仍保持可见header只作为宿主拥有的导航与身份内容。当它缺失时插件工具栏在 Tab 预览与独立预览中保持居中于自己的行内。这套组合方式让同一个插件无需格式分支即可同时工作在嵌入与标签页两种宿主中。typeartifact 与安全边界typeartifact用于显式的开发产物表面宿主拥有编辑权Markdown 与 HTML 保持渲染预览模式并省略预览/源码切换而 HTML 使用交互式 artifact 沙箱允许生成的应用执行脚本。该模式不会隐藏格式专属控件如 PDF 缩放、图片变换。其余所有调用方默认typefile本地 HTML 被视为不受信任内容用无脚本沙箱与严格 CSP 渲染并保留插件拥有的预览/源码切换。不要仅为了启用脚本就把任意本地文件标记为 artifact。文件 I/O、状态与错误模型打开前的目标分类打开入口应先对点击路径分类再选择 UI目录直接在文件浏览器中打开不进入预览选择具体文件交给FilePreview缺失或不可访问的文件选择也交给FilePreview由它呈现不可用unavailable状态。路由决策表FilePreview使用的路由模型如下目标预览决策结果目录不进入文件插件文件浏览器表面直接传入时呈防御性文件夹状态已注册二进制插件的现有文件注册插件内联预览Artifact HTML带 artifact 策略的 HTML 插件交互式内联预览宿主拥有源码/编辑已注册文本插件的现有文本文件内容嗅探后使用注册插件内联预览无注册扩展名的现有文本文件文本回退插件源码预览无注册插件的现有二进制文件不支持unsupported说明 安全的默认应用打开动作缺失或不可访问路径不可用unavailable说明无打开动作无效或非绝对路径无效invalid说明无打开动作宿主实现中状态种类FilePreviewStateKind定义为directory | invalid_path | load_error | unavailable | unsupportedFilePreview.tsx文案统一走file_preview.*i18n 键。需要特别说明的是只有unsupported状态可以回退到外部默认应用打开源码注释明确了原因——此时路径已通过校验、指向真实文件只是无法内联渲染且safeOpen会执行不安全扩展名策略invalid_path状态下绝不提供打开动作。I/O 规范与传输层防护文本读取用window.api.fs.readTextwindow.api.fs.read仅用于插件依据预检文件大小限定边界的整文件二进制读取大型或按需读取的二进制格式必须用类型化的ipcApi.request(file.read, ...)区间读取range read而不是加载整个文件组合多个区间读取的传输层在分配缓冲区前必须封顶组装后的区间大小并拒绝以下响应读取之间version变化或version.size与预检的metadata.size不一致必须使用预检过的metadataprop 做大小守卫插件不得再发第二次元数据请求加载 effect 必须包含filePath与refreshKey新的 refresh key 意味着即使路径不变也必须重新读取文件组件卸载、filePath变化或refreshKey变化时必须取消/断开/销毁文件读取、worker、监听器与第三方实例。PDF 传输层是最佳范例PdfFileRangeTransport.ts它以 1 MiBPDF_RANGE_CHUNK_SIZE_BYTES为单位通过file.read区间读取把每个组装后的 pdf.js range 封顶在 16 MiBPDF_MAX_ASSEMBLED_RANGE_BYTES。超限抛PdfRangeTooLargeError。这不是 PDF 文件大小上限更大的文件依然可以预览只要每个请求的区间在封顶之内。若某个 PDF 需要超过封顶的连续区间就必须提供显式的“外部打开”回退要移除该上限需要改为不在渲染器内组装的流式传输。传输层还校验每个 chunk 的version一致性、短读Short PDF read与非法区间参数。错误所有权FilePreview拥有目录、无效路径、不可用路径、不支持格式、插件加载失败、同步渲染错误等状态渲染错误由ErrorBoundary的PluginErrorFallback承接见 FilePreview.tsx插件拥有自己的加载中、空、过大与读取错误状态并且必须捕获 effect 与事件处理器中的异步失败让错误保持在预览区域内读取失败通过loggerService记录并在错误状态中暴露足够诊断信息使失败可定位、可处理。UI 与文案规范新 UI 使用cherrystudio/ui与 Tailwind CSS遵循仓库 DESIGN.md 设计规范工具栏使用 Lucide 图标图标按钮必须具有可访问名称与 tooltip插件专属文案放file_preview.*i18n 键下共享控件复用已有common.*或preview.*键并同步更新en-us与zh-cn工具栏保持稳定高度只有FilePreviewLayout.Content拥有内容滚动。验证Verification新插件至少需要覆盖以下测试场景仓库内已有对应 Vitest 用例可参考如 plugins/**/tests下的各格式测试与tests/filePreviewRegistry.test.ts扩展名能正确解析到对应插件且不与既有扩展名冲突重复扩展名应使注册表创建抛错懒加载组件收到规范化的filePath、正确的fileName、预检的metadata与当前refreshKey加载中、成功、空与读取错误状态保持在预览区域内工具栏动作、禁用状态与清理行为符合预期。按仓库约定先运行聚焦插件与注册表的 Vitest 套件再执行仓库要求的格式化与静态检查。相关测试基础设施还可参考 frontend-testing 指南。小结一套插件两种宿主FilePreview的设计核心是职责切分宿主只做路径校验、元数据预检、插件路由与状态兜底格式能力全部内聚在独立插件中。嵌入预览与标签页预览作为宿主的组合选择共享同一套插件避免了对每种格式编写两套预览面板。新增格式时只需遵循“描述符 default 组件 独立工具栏 注册表登记 测试覆盖”的固定模式即可复用已有的安全路径契约、懒加载机制、portal 工具栏与错误模型让 Cherry Studio 的文件预览体系保持可扩展性与安全性兼备。【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考