文件预览
可移植回放DOM预览PDF,DOCX,PPTX,XLSX,RTF和图像(包括SVG). 软件包拥有渲染,控制,结构选择,工人和翻译. 主机拥有文件访问,权限,导航,外部打开和记录. HTML,Markdown和源代码预览保留在桌面应用程序中.
在React 19和React DOM 19同时安装一个已出版的版本:
pnpm add @cherrystudio/file-preview react@^19 react-dom@^19
该包可以独立于樱桃工作室的工作空间进行安装. 包起来 其渲染引擎和UI组件; 消费者不需要工作空间包或 依赖补丁.
import type { PreviewSource } from '@cherrystudio/file-preview/core'
import { Preview } from '@cherrystudio/file-preview/react'
import '@cherrystudio/file-preview/styles.css'
function FilePanel({ source }: { source: PreviewSource }) {
return <Preview source={source} locale="zh-cn" />
}
给父母一个定义的高度 。 每个源打开一个独立的 PreviewDocument。 。 。 .
预览在失败、替换、刷新或卸载后关闭, 包括延迟
在取消后打开。 文件的大小和修改保持不变;
它的读者必须拒绝版本的修改,短读后读取. 关闭必须
成为独行侠。 距离抵消和长度是文档大小范围内的安全整数.
DOCX, PPTX, XLSX, RTF 和图像请求整个文档为一体 [0, size) 范围,所以
a 主机可以用单读来服务; PDF 请求部分范围.
读者在运输支持取消时,应当遵守中止信号. 这个
软件包在取消后丢弃一个已读结果;它不能停止有主机 I/O
已启动或中断同步引擎解析 。 返回的字节视图仍然存在
主机拥有:包不变异或拆分. XLSX 复制请求
在将自己的缓冲器转移给解析工人之前, 位数 .
refreshKey 是一个可选的数字。 修改后关闭当前文档并打开
重新开庭,包括失败后. header 接受主机自主导航
和固定上行的文件标识内容;格式工具栏共享该行.
没有页眉,格式控件会在文档上方渲染. 给 source 财务报告和审定财务报表
resources 稳定的参考文献这样布局, 地方和主题更新保留会话.
刷新相同的源代码和格式保留挂载格式及其有效性 打开新文档时读取状态。 格式保存缩放、页面、滚动、, 工作表和图像酌情转换,并夹住位置以缩短内容. 不同的源代码或格式开始新的预览. 上一份文件仍然 关闭刷新; 过时的读取和解析结果不能覆盖保留 内容或公布替换会话的选择或终端错误. 关闭和重新打开预览不会持续读取 历史 主机在请求刷新时必须清除任何持有的选择 .
onSelection 报告 { sourceId, revision, anchor, excerpt },或 null 当 a
选择被清除。 控制器使用工作表 A1 范围、正文段落正文、 PDF 页面
和 PPTX 幻灯片。 主机拥有横跨刷新和文件开关的选择.
revision 与软件包不透明,只区分文档版本。 主机
映射选择返回到自己的文件身份; 软件包从不解析它 .
节选使用 NFC 正常化, 崩溃共享的 JavaScript/ Python 白空位集
至单空格,并修剪两端。 它们仅限于2000个UTF-16代码单元,
不拆分替代对; 空的正则摘录产生 null。 。 。 .
内部已稳定回调引用 Preview因此内置回调
仅仅因为主机提供,就重新打开文件或重复选择通知.
DOCX文本支持本地选择并用 Ctrl+C (在macOS上的 Cmd+C) 复制, 包括跨段落。 复制使用浏览器选择,而不是普通化 或长度限制的引用节选。 当段落选择启用时,结束 文本拖动保留了已存在的段落取出;平滑键仍然取出或清除.
公认的 source.mediaType 值优先于文件名扩展名;
缺少或未识别的媒体类型返回扩展名. supportsPreview
财务报告和审定财务报表 canSelectPreview 接受与他们的第二个参数相同的可选媒体类型.
onDiagnostic 是引擎警告和错误的日志通道。 一个终端
失败发出一个诊断和呼叫 onError (一) 该届会议; onError
通知主机状态, 不应再次登录同一错误 。 预期 too_large
失败就是警告。 非终端问题, 如 PPTX 幻灯片或 PDF 失败
概要导航,发出诊断,而文件的其余部分仍然可用.
onError 收到一个 PreviewError 拥有稳定 code 和可选基础
cause。错误信息是诊断细节,而不是本地化的 UI 副本.
| 代码 | 含义 |
|---|---|
invalid_range | 无效的文档大小、 偏移或读取长度 |
short_read | 阅读器返回的字节比要求的少或多 |
source_changed | 主机在读取时检测到修订更改 |
closed | 在主机文件关闭后尝试读取 |
too_large | 预览源或 PDF 范围超过其安全限制 |
load_error | 打开、解析或渲染因其他原因失败 |
onRequestOpen 代表外部仅在用户激活后打开主机
打开按钮。 它的理由是 unsupported 用于未识别格式或 too_large
对于大小限制回落; 渲染或刷新一个不支持的源永远不会打开
另一个应用程序自动。 25米B以上的DOCX/PPTX,20米B以上的XLSX,
10米B以上的RTF和64米B以上的图像显示了它们的极限. PDF有一个16个米B
组装范围盖,无全文件尺寸限制. 这些状态在
主机提供回调.
resources.baseUrl 可选择覆盖捆绑的工人/font/CMap目录;
包括一条接踵而至的斜线。 相对的URL根据主机页面解决.
readPdfResource 优先于 PDF 字体和 CMaps 的资源 URL,
包括字体替换。 Electron为文件-scheme页面提供.
PDF工人属于个人预览,永不改变pdf.js全局选项.
清理等待 pdf.js 装入任务的破坏 之前结束它的工人,
允许释放文档字体。 没有强制停工:a
已经无动于衷的工人可以将破坏承诺搁置.
翻译使用独立的i18next实例,为14种语言提供资源;其他地语回落为英语.
FilePreviewLayout.Shell 拥有共享标题和工具栏位置.
FilePreviewLayout, (中文(简体) ), FilePreviewToolbar 并使用其门户提供者/主机
仅使用桌面格式; FilePreviewToolbarButton 用于图标命令.
登记册是静态的;格式不能在运行时注册.
对于捆绑的网页应用程序,请复制软件包 dist/assets/ 一个目录
公共目录( 例如, Vite ) public/preview-assets/预览
在其部署的 URL 中:
const resources = { baseUrl: '/preview-assets/' }
<Preview source={source} resources={resources} locale="zh-cn" />
留着工人, cmaps/ 财务报告和审定财务报表 standard_fonts/ 一起来 工人条目 URL 必须是
申请的同一来源; 仅凭CORS的许可不能允许交叉来源
new Worker() 输入。 跨原产地资产宿主需要同源工人进入或
由东道方提供 createWorker。字体和CMap请求分别需要服务器的
从另一个来源装入时的跨源权限.
未提供基准 URL 时, 捆绑者处理本地工人 URL; 主机
仍然必须部署 PDF 资源目录或提供 readPdfResource。 。 。 .
WebView 和内置主机
捆绑没有 URL 的页面, 如装入移动 WebView 的内置 HTML , 无法
解决捆绑工人或PDF资源。 双向供应 resources数字 :
import pdfWorker from '@cherrystudio/file-preview/assets/pdf.worker.js?raw'
import xlsxWorker from '@cherrystudio/file-preview/assets/xlsx.worker.js?raw'
const workerSources = { pdf: pdfWorker, xlsx: xlsxWorker }
const workerUrls: Partial<Record<'pdf' | 'xlsx', string>> = {}
const resources = {
createWorker: (kind: 'pdf' | 'xlsx') => {
workerUrls[kind] ??= URL.createObjectURL(new Blob([workerSources[kind]], { type: 'text/javascript' }))
return new Worker(workerUrls[kind], { type: 'module' })
},
readPdfResource: (kind: 'cmap' | 'standard_font', name: string) => bridge.readPdfResource(kind, name)
}
主机资源寿命中每个工人类型缓存一个对象 URL 。 在所有预览后
使用这些资源已卸载, 主机处理此资源集, 释放
使用 for (const url of Object.values(workerUrls)) URL.revokeObjectURL(url)。 。 。 .
终止个体劳动者不取消其对象URL.
createWorker 优先于 baseUrl 给两个工人 每个工人档案
自相残缺。 给内置的 HTML 一个基础 URL, 如反应- 内置- 网络视图
source={{ html, baseUrl: 'https://file-preview.local/' }}: 不透明 about:blank
来源,浏览器拒绝从blob URL创建的模块工人. readPdfResource 服务名称从 assets/cmaps/ (无) .bcmap(中文(简体) )
财务报告和审定财务报表 assets/standard_fonts/。 。 。 .
PDF和DOCX用两指相接来缩放,图像在他们的取景口中被相接.
PPTX和XLSX通过工具栏放大. 电子表格触摸会选择水龙头上的单元格,并且
不选择而刷取滚动 。 在主机页面上禁用页面缩放
(单位:千美元)<meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no">(中文(简体) )
因此,这些表面外的一接 无法缩放整个预览.
Opt- in 主机布局和字体兼容性
全体 options 选择进入。 关闭它们保留桌面渲染: PDF 侧边栏,
DOCX 百分百地拥有其现有的字体处理,半透明电子表格头,以及
现有视图端口设置。 软件包不检测主机平台.
<Preview
source={source}
resources={resources}
options={{
bottomInset: 'content',
pdf: { outlineLayout: useOverlayOutline ? 'overlay' : 'panel' },
docx: { initialZoom: 'fit-width', normalizeSymbolBullets: true },
xlsx: { opaqueHeaders: true }
}}
/>
主机选择 useOverlayOutline 实际可用宽度,包括
景观取向。 重叠模式覆盖预览而不缩小其页面;
逃跑 关闭按钮 背景 选择内部目的地
这个 明确选择任何 PDF 版式, 也保持页面宽缩放同步
容器调整大小; 手动缩放保存.
DOCX 数据库 fit-width 将最宽的页与窗格相匹配,允许比例低于50%,以及
从未超过200%。 它跟随容器调整大小,直到用户使用
工具栏或夹; 重置复选。 不需要定向信息
国防部. normalizeSymbolBullets 在打开文档时被读取: 它映射已知的
单字符符号/ Wingdings 弹出标记为 Unicode并去除其遗留
字体覆盖。 其他字体,未知符号和编号列表被保留.
bottomInset: 'content' 在 PDF 、 DOCX 和 PPTX 文档滚动中添加后缀空间
容器,装入未缩放的主机CSS像素. PDF 概要布局都收到后缀
卷轴空间也。 XLSX 是固定控制例外:它的工作表标签、状态和缩放
控制保留整个页脚下方的内置,所以主机覆盖无法覆盖它们.
网格不添加第二个设置 。 其他格式保留其已存在的内置行为.
opaqueHeaders 复数 :
--background,包括被冻结的角落,所以细胞不能通过α颜色显示.
保留 source 财务报告和审定财务报表 resources 在布局、地方和主题更新期间,参考文献稳定.
变化 options 不重开源代码。 字体相容性生效于
下个文档打开或清晰刷新;它不会重放打开的文档.
样式
className 财务报告和审定财务报表 style 应用到预览的单一主题根。 内部框架继承
它的标志。 添加 dark 用于黑暗主题,并设置这些自定义属性以重取主题.
Root 覆盖胜过被打包的值, PDF 观察到这个相同的根用于主题变化 .
| 财产 | 用于 |
|---|---|
--background, (中文(简体) ), --foreground | 表面和文字 |
--primary | 选择、焦点和主动控制 |
--muted, (中文(简体) ), --muted-foreground | 次要表面、图标和标签 |
--border, (中文(简体) ), --border-subtle, (中文(简体) ), --ring | 分裂者、轮廓和焦点环 |
--file-preview-toolbar-button-size | 工具栏按钮大小, 默认值 1.75rem |
--file-preview-bottom-inset | 底部空间; 内容模式添加文档滚动空间或保护固定的 XLSX 页脚 |
RTF 文档
RTF 预览渲染格式化的文本、 Unicode 和遗留的代码页面、链接和嵌入 图片使用rtf.js. 文档在两个主题中使用白布保留作者 前景并突出颜色。 HTTP、HTTPS和邮件链接仅在用户动作时开放; 其他链接仍为纯文本。 未装入外部图像导入 .
渲染是一个流出文档预览,而不是一页忠实的Word布局. RTF 没有
提供结构选择参考。 解析在懒惰中同步进行
格式模块,以10 MiB源限制为限。 捆绑的 rtf.js 补丁拒绝
切换文档,消耗二进制图像有效载荷,并恢复默认字体
关于字符重排。 字节字节、十六进制出错和出错符号共享
1个代码页解码器;Unicode控件仍为解码文本. 原始双字节线索
字节在解释RTF语法前被消耗. 不完整或未映射字节
序列失败而非插入预览 undefined 输入文档内容.
后退案例涵盖Windows-1252,GBK,Big5和Shift-JIS,包括混合字节
表达式、字体变化、组边界和Unicode倒置跳过.
大楼
pnpm --dir packages/file-preview pack --pack-destination /path/to/artifacts
pack 先经营生产基地,所以柏油丸从不带 stale dist。 。 。 .
库建使用 Vite 处理本地工人 URL 和 Tailwind CSS, 加上
rolldown-plugin-dts 声明捆绑。 每个第三方图书馆,但 zod
被捆绑,包括 UI 组件和被补丁的 docx- preview 和 pptx- renderer,所以它们是 dev
依赖关系;仅安装消费者 zod 和反应同伴。 CSS 不包括尾风预飞
选择范围 .file-preview-root。 。 。 .
浏览器回归测试
从工作空间根起,安装一次Playwright的铬,然后运行包测试:
pnpm exec playwright install chromium
pnpm exec playwright test --config packages/file-preview/playwright.config.ts
测试配置构建软件包并启动自己的 Vite 服务器, 然后停止 运行后的服务器。 没有运行电子实例或渲染器开发服务器 需要时间。 PDF案例行使已建公共软件包和实际工人/排出 用于混合/修改的页几何、阅读偏移、刷新、缩放、活动和较短的文档. PowerPoint 大小写使用真正的渲染器来保留幻灯片相对读取的偏移 当同一甲板改变滑动比例时,包括活动还原.
出版
版本和 npm 发布使用寄存器 更改工作流程。 。 。 .
初始变换器促进 0.1.0-alpha.0 改为 0.1.0 在自动版本 PR 中.
合并该版本的 PR 发布软件包 latest 标签。 后续
可公布的更改必须包括用于 @cherrystudio/file-preview。 。 。 .
发布和快照工作流程都通过此软件包构建 pnpm packages:build。 。 。 .
手册简况工作流程 snapshot 用于集成测试的标签 :
pnpm add @cherrystudio/file-preview@snapshot
这个 prepack 钩子在包装或发布前重建包. 艺术品
包含 JavaScript 和声明入口、 范围化样式表、 工人脚本,
PDF CMaps 和标准字体, README 和许可证. 检查包装的文物
第一次发布前的独立消费者,包括工人和PDF资源加载.