支持格式

Runtime Truth

当前版本内置 74 个扩展名映射，覆盖 14 条预览链路。 这一页不是“计划支持什么”，而是以当前代码里已经注册好的渲染器为准，告诉你项目现在到底能处理哪些格式、分别走哪条渲染链路，以及在真实业务里应该怎么选。

74 个扩展名映射

覆盖 Office、PDF、OFD、CAD、Excalidraw、draw.io、EPUB、Markdown、图片、音频、代码/文本和视频等常见附件类型。

按需异步加载

OFD、CAD、绘图、PDF、Office、Markdown、代码高亮等渲染器都会拆成独立异步块，命中格式时才加载。

两条输入路径

既可以用 url 直接预览，也可以在业务侧拿到文件后二次包装成 File 再传入。

以体验边界为准

不同格式会走不同解析链路，兼容优先的格式与高保真格式在样式还原上并不完全一样。

当前支持矩阵

分类	扩展名	渲染链路	当前表现	更适合的场景
Word	docx	docx-preview	白色纸张显示在灰色页面底中，支持宽度自适应和长文档视觉分页	新生成的 Word 文档、正式公文、模板文档
Word	doc	msdoc-viewer	使用 Word 风格页面容器，页面居中显示在灰色工作台中	存量老文档、历史附件回溯
Excel	xlsx	styled-exceljs + e-virt-table	支持虚拟滚动、列宽/行高、合并单元格和常见样式	大表格预览、报表、需要保留结构和样式的业务
Excel 兼容格式	xlsm、xlsb、xls、csv、ods、fods、numbers	styled-exceljs + e-virt-table	统一读取数据、尺寸和可用样式，按浏览器能力渐进还原	老表格、跨平台导出的表格、轻量数据查看
PowerPoint	pptx	自定义 PPTX 渲染器	以页面展示为主，增强组合图形、旋转/翻转、主题背景、图片裁剪和 EMF 矢量图预览	汇报材料、说明文档、培训课件
PDF	pdf	pdfjs-dist	浏览器端 PDF 渲染，支持缩放工具栏、页码状态和可显隐导航窗格	合同、票据、版式稳定文件
OFD	ofd	DLTech21/ofd.js 源码	使用浏览器端 OFD 解析和页面渲染，避开 npm dist 授权 wasm 分支	电子发票、公文、国产版式归档材料
CAD	dxf	@cadview/core	Canvas 方式浏览 DXF 图纸，支持缩放、平移、图层显示控制	工程图纸、二维 CAD 附件
CAD 兼容入口	dwg	CAD 兼容提示	DWG 属于专有二进制格式，当前不内置 GPL 解析器，会提示转换为 DXF 后预览	需要兼容上传入口但不希望引入 GPL 运行时代码的业务
Excalidraw	excalidraw	@excalidraw/excalidraw	使用官方 restore 兼容真实公开文件，再通过 exportToSvg 输出只读 SVG 预览	白板草图、产品沟通图、流程草稿
draw.io	drawio、dio	diagrams.net GraphViewer	使用官方 viewer 渲染 mxGraphModel / mxfile，不自行解析 draw.io 方言	流程图、架构图、业务泳道图
电子书	epub	epubjs	解析 EPUB 包、目录和章节资源，使用滚动阅读避免超宽分页白板	电子书、培训手册、长篇阅读材料
Markdown	md、markdown	Markdown 渲染器	保留 Markdown 阅读样式	README、知识文档、开发说明
图片	gif、jpg、jpeg、bmp、tiff、tif、png、svg、webp	图片渲染器	原生图片浏览	图片附件、设计稿、截图、Logo
代码/文本	txt、json、js、mjs、cjs、umd、css、java、py、html、htm、jsx、ts、tsx、xml、log、vue、yaml、yml、ini、sh、bash、sql、go、rs、php、c、cpp、cc、h、hpp、cs、diff	highlight.js	按源码方式展示并轻量高亮，不执行脚本	配置文件、日志、代码片段、UMD 产物源码、接口响应
音频	mp3、mpeg、wav、ogg、oga、opus、m4a、aac、flac、weba	浏览器原生 <audio>	使用原生音频控件播放，具体编码支持取决于浏览器	录音、播客、语音附件、音效素材
视频	mp4	浏览器原生视频播放器	原生播放、带控制条	演示视频、录屏材料

按类型看体验和边界

Word 文档

• docx 使用 docx-preview，适合正文、表格、图片和常规版式较多的现代 Word 文档。当前预览层会恢复白色纸张和灰色页面底，并根据可用宽度自动缩放。
• doc 使用 msdoc-viewer，并额外套用 Word 风格页面容器。它不只是“把内容吐出来”，而是尽量保留文档阅读时的页面感。
• 如果源文档缺少显式分页，.docx 预览会在浏览器端补一层视觉分页，避免长文档变成一整条没有纸张边界的内容流。
• 如果你的业务能控制导出格式，优先推荐 docx；如果你面对的是存量老文档，当前 .doc 已经可以作为正式能力对外说明。

`.doc` 文件现在会显示在灰色工作台中的白色纸张上，页面居中，阅读路径更接近真实 Word 阅读体验。

表格类文件

• 表格类文件统一走 styled-exceljs 解析和 e-virt-table 虚拟渲染，适合需要保留表格结构、合并单元格和视觉层级的场景。
• xlsm、xlsb、xls、csv、ods、fods、numbers 会读取格式中能表达的数据、尺寸和样式；部分格式本身不包含完整样式时，会按可用信息渐进还原。
• 如果你正在设计业务导出格式，优先选 xlsx；如果你只是需要把历史附件打开看内容，兼容链路已经足够实用。

演示文稿、PDF 与 OFD

• pptx 适合浏览幻灯片内容、做方案回看和日常演示，不需要 Office 本体参与。
• PPTX 渲染器现在会按 DrawingML 的组合图形坐标系处理 chOff/chExt，组合内元素在缩放、旋转、翻转时会更接近 PowerPoint 中的位置关系。
• 主题背景支持从 fillStyleLst / bgFillStyleLst 解析纯色、渐变、图片和平铺图案；PPTX 内嵌的 EMF 图片会尽量转换为 SVG 数据图，避免只显示空白占位。
• 图片填充会处理 srcRect 裁剪信息，复杂模板里的裁切图、背景图和组合形状更适合作为真实业务样本回归。
• pdf 走 pdfjs-dist，通常是版式最稳定的一类文件，适合合同、流程单、正式成品材料。当前 PDF 视图提供顶部缩放工具栏、页码状态和可显隐页面导航窗格。
• ofd 走 DLTech21/ofd.js 仓库源码，用于国产版式文档在线预览。npm dist 当前会在 wasm 解析层返回授权错误，组件改用同仓库的纯 JS 解析/渲染链路，OFD 依赖仍保持按需异步加载。
• 如果你更在意“展示结果必须完全稳定”，优先考虑 pdf / ofd 这类版式成品；如果你需要保留可编辑文件的阅读入口，优先用 pptx。

CAD 图纸

• dxf 走 @cadview/core，提供 Canvas 图纸预览、缩放、平移和图层显隐能力。
• dwg 当前注册为兼容入口，但不会直接解析。DWG 格式通常需要专用转换或 GPL 授权运行时，组件会给出清晰提示，推荐业务侧转换为 dxf 后再预览。
• 如果你要在生产系统里稳定预览 CAD 文件，建议把 DXF 作为前端预览标准格式，并在上传或归档环节统一转换。

绘图文件

• excalidraw 使用官方 @excalidraw/excalidraw 包的 restore 与 exportToSvg 能力，按需加载后输出只读 SVG 预览，不手写 Excalidraw 图元解析器。
• drawio 和 dio 使用官方 diagrams.net GraphViewer，由官方 viewer 处理 mxGraphModel / mxfile、主题和图元兼容，组件只负责创建容器和传入 XML。
• draw.io viewer 脚本来自 diagrams.net 官方静态地址，只有命中 .drawio / .dio 时才加载；需要内网私有化时，可以把该官方脚本镜像到自己的静态资源域名再替换加载地址。

电子书

• epub 使用 epubjs，由成熟开源库处理 EPUB zip 包、OPF、目录和章节资源。
• EPUB 预览提供目录窗格、上一章/下一章式导航和阅读进度。正文区域使用滚动文档模式，避免部分浏览器在超宽分页 iframe 下出现白板。为了安全，阅读器不会允许书内脚本执行。
• Kindle 专有格式、DRM 电子书或业务加密包不在当前内置范围内，建议在接入侧转换为 EPUB 或 PDF 后预览。

Markdown、代码与文本

• md 和 markdown 会按 Markdown 阅读样式展示，适合项目说明、知识文档和内部手册。
• 代码和文本文件会使用 highlight.js 做轻量高亮，按扩展名匹配语言，不命中时会自动退回纯文本；umd 会按 JavaScript 源码高亮。
• 这里有一个很重要的边界：html 文件会被当作源码看，而不是在预览器里当网页执行。这是更安全、也更可控的默认策略。

图片、音频与视频

• 图片类支持 gif、jpg、jpeg、bmp、tiff、tif、png、svg、webp。
• svg 会作为图片来展示，很适合拿来放矢量图标、流程图和品牌素材。
• 音频类支持 mp3、mpeg、wav、ogg、oga、opus、m4a、aac、flac、weba，使用浏览器原生播放器；不同浏览器对编码格式的支持会有差异。
• 视频当前支持 mp4，使用浏览器原生播放器，适合最常见的演示和录屏场景。

真实业务里怎么选

• 你能控制导出格式：优先使用 docx、xlsx、pptx、pdf、ofd、dxf 这类现代或稳定交换格式。
• 你要兼容历史附件：.doc 与 xls/xlsm/xlsb/csv/ods 这一组已经有正式链路，但要接受它们与现代格式在样式上的差异。
• 你要看日志、配置或代码：直接用代码/文本链路即可，重点是快速打开、检索内容和保持安全。
• 你在做品牌、示意图或视觉素材展示：png、svg、webp 这类图片格式会比转成文档更省心。
• 你要预览 CAD：优先沉淀 dxf，把 dwg 作为上传兼容和转换前提示。
• 你要预览绘图文件：Excalidraw 和 draw.io 都保留源格式入口，前者走官方恢复与导出 SVG，后者走官方 diagrams.net viewer。
• 你要预览电子书或音频：EPUB 优先保留源文件，音频优先选择浏览器兼容最稳定的 MP3 / OGG。

不支持的格式会怎样

如果文件扩展名没有命中已注册渲染器，组件会显示“不支持当前格式在线预览”的提示，引导用户下载后查看或转换格式。

最稳妥的做法，不是只看这张表，而是把你业务里最关键的那几类真实文件各准备一份样本，走一遍本地 Demo 和接入页联调。这样你拿去对外说明时，底气会更足。