简介面向 Unity 开发者的文档显示解决方案主要用于在 Android 等平台直接查看 Word、Excel、PDF、PPT 文件解决 Unity 原生不支持这些格式的渲染问题。资源包含完整的 Unity 工程、C# 脚本、动态库及演示文档并给出通过 FreeSpire、Aspose.Slides、PDFNet 等第三方库转换文件、结合 WebView 显示的实现思路适合教育、文档管理类项目的开发与学习。压缩包共 2000 个文件涵盖 cs 核心脚本、unity 场景、dll 库文件以及 docx/pdf/pptx/xlsx 示例文档另有大量 Unity 资源元数据与配置文件整体体积 172.43MB目录结构完整便于直接导入或对照学习。已有 910 人学习下载通过阅读可掌握文件加载、格式转换、WebView 嵌入、Android 适配和性能优化等关键环节减少自行排查成本快速搭建可复用的文档查看模块。 做工程项目时迟早会遇到“在Unity里显示Word、Excel、PDF、PPT文件”这种需求。我最早碰到是在做一套设备管理工具客户希望双击一个日志文件直接在软件里看到内容而不是另开Office或PDF阅读器。一开始我觉得这事不难结果越做坑越多格式兼容、线程卡顿、COM组件释放、不同Windows版本行为差异……前前后后折腾了两三周最后沉淀出一套比较可靠的实现思路。这篇就聊聊我验证过的方案、踩过的坑以及可以直接拿去改的代码结构。虽然Unity自身只认Texture2D/Sprite但文档预览的本质是“把文件内容变成一张或一组图片”。这个转换环节选对了后面UI展示就非常简单。适合被推荐给做编辑器工具、本地数据管理软件、Windows平台演示类应用的开发者特别是不想让项目过度依赖第三方重型插件的人。1. 需求拆解与方案选型1.1 为什么不能直接在UGUI里渲染Office文件很多新人上来就想找一个“纯Unity渲染docx/xlsx/pdf的库”我劝你尽早放弃。原因很简单这些格式内部结构极其复杂Word本质是一个压缩包里的XML、图片、样式、字体和流式排版指令Excel还有单元格公式、合并区域、条件格式PPT则是多张画布跟动画时间轴。Unity的UI系统只负责绘制四边形网格它没有能力解释这些文档语义。如果自己解析等于给Unity写一个Office内核工作量根本不是项目能承受的。所以实用派的思路永远是另起炉灶由系统或第三方工具把文档转成Uniform格式图片/PDF网页再交给Unity显示。这也是后面所有方案共同的出发点。1.2 主流方案横向对比我把试过的方案列个表方便你根据场景选方案适用平台优点缺点推荐指数工具截图后加载全平台实现简单逻辑直观适合静态预览需要唤起外部程序交互体验割裂低Windows.Data.Pdf WinRT转图Windows系统自带APIPDF渲染质量高无需额外SDK仅限Windows需要开启WinRT支持高PDF场景Office COM互操作转PDF/图片WindowsWord/Excel/PPT全支持保真度高依赖微软Office安装有权限和进程管理问题高Office场景浏览器内核WebView加载全平台保真度最高动态交互也能保留内存占用大移动端集成复杂中服务端转换后下发图片全平台压力转移客户端轻量需要搭建服务文件上传下载有延迟中我做Windows桌面端工具时最终选型是“Office COM先把文档转成PDFPDF走WinRT转成图片图片再贴到UGUI上”。这条链路最稳定而且两个环节都有系统级API兜底。2. 核心思路把文档变成Texture再显示2.1 为什么万事万物都能转PDF再转TexturePDF是一个高度标准化的固定版面格式跨设备显示效果完全一致。Word、Excel、PPT都可以通过Office自身的导出接口生成PDFPDF又可以被Windows.Data.Pdf逐页渲染为位图。于是整个链路变成Word/Excel/PPT —— Office COM —— PDF —— Windows.Data.Pdf —— Texture2D —— RawImage显示这条链路的好处是不需要去解析docx内部的XML不用关心字体缺失、分页规则这些细节Office自己会处理。依赖也只有两个系统装了Office、系统是Windows 10/11。对于企业内网工具类应用这两个条件基本都满足。2.2 一种特殊场景仅显示图片型PDF如果你的需求只是显示PDF那不需要Office参与。直接用WinRT的PDF API就能完成而且代码量很小。如果是Word/Excel/PPT那么绕不开Office COM。这里要注意Office COM在服务端比如Windows Server使用会有限制和许可风险但在普通客户端工具中调用自己机器上的Office实例是常见且可靠的做法。我个人的原则是客户端项目优先用本机能力避免引入庞大的运行时。只有当目标是WebGL或移动端时才考虑WebView或服务端转换。3. PDF预览实操用WinRT把PDF渲染成Texture3.1 工程开启Windows Runtime支持在Unity中先要让项目能调用WinRT。打开Player Settings选择Windows Standalone平台在Other Settings里勾选“Use Windows Runtime Support”。不勾的话Windows.Data.Pdf命名空间根本编译不过。3.2 核心代码实现下面是我整理过的PDF转Texture工具函数核心思路是异步转同步using System; using System.IO; using System.Threading.Tasks; using UnityEngine; using Windows.Data.Pdf; using Windows.Storage; using Windows.Storage.Streams; public static class PdfTextureConverter { public static Texture2D PdfPageToTexture(byte[] pdfBytes, int pageIndex, int targetWidth 1024) { // 将字节数组写入临时文件因为WinRT的PdfDocument需要从StorageFile或IRandomAccessStream加载 string tempPath Path.Combine(Application.temporaryCachePath, tempPdf.pdf); File.WriteAllBytes(tempPath, pdfBytes); // 异步加载PDF文档并用GetAwaiter()阻塞Unity主线程 var doc PdfDocument.LoadFromFileAsync(StorageFile.GetFileFromPathAsync(tempPath).AsTask().GetAwaiter().GetResult()) .AsTask().GetAwaiter().GetResult(); if (doc null || pageIndex 0 || pageIndex doc.PageCount) { Debug.LogError([PdfTextureConverter] 页码无效); return null; } // 获取页面并渲染到指定尺寸的流中 using (var page doc.GetPage((uint)pageIndex)) { var stream new InMemoryRandomAccessStream(); var options new PdfPageRenderOptions { DestinationWidth (uint)targetWidth }; page.RenderToStreamAsync(stream, options).AsTask().GetAwaiter().GetResult(); // 从流中读取字节交给Texture2D加载 stream.Seek(0); byte[] buffer new byte[stream.Size]; var reader new DataReader(stream.GetInputStreamAt(0)); reader.LoadAsync((uint)stream.Size).AsTask().GetAwaiter().GetResult(); reader.ReadBytes(buffer); // 按字节创建Texture假设PDF RenderToStream输出的是BGRA格式 Texture2D tex new Texture2D(targetWidth, targetWidth * 2, TextureFormat.BGRA32, false); tex.LoadRawTextureData(buffer); tex.Apply(); return tex; } } }这段代码里有几个关键点。必须把WinRT的IAsyncOperation转成Task才能用GetAwaiter().GetResult()同步等待。直接调用.Wait()在Unity主线程上会死锁因为Unity的同步上下文比较特殊。PDF页面本身没有固定的宽高比上面代码用targetWidth * 2是占位真实项目中要根据page.Size.Width和page.Size.Height计算目标高度否则图像会变形。RenderToStreamAsync出来的数据格式是BGRA32不是常见的RGBA32创建Texture时一定要注意TextureFormat.BGRA32否则图像会像通道被互换了一样出现红蓝偏移。3.3 多页PDF怎么办一个小PDF可能几十页全部异步转Texture后塞进列表内存会直接爆炸。我的经验是只加载当前显示的页码做LRU缓存。比如只保留前后2页的Texture翻页时销毁远离的页面。如果你用的是Unity自带UGUI的ScrollRect还可以在滚动的回调里动态加载这样外层感觉丝滑内存占用也稳。关于Page.RenderToStreamAsync的DestinationWidth我通常传屏幕宽度对应的像素值比如1920屏传1024到2048之间。太高了既浪费显存又增加加载耗时太低了字会糊。换算方式targetWidth Mathf.CeilToInt(screenWidth * 0.8f)基本够看。4. Word/Excel/PPT预览实操Office COM转PDF4.1 为什么用COM不用OpenXMLOffice OPEN XML SDK可以直接生成Word/Excel文件但它主打的是“写文档”读取和渲染也不是它的事。真要把docx按Word引擎的排版规则分页并导出为图像本质上还是Word自己做得最好。COM互操作本质是启动一个后台Office进程调它的导出接口然后把文件保存成PDF最后把PDF交给前面WinRT管道。4.2 Word导出PDF代码片段先添加COM引用在Unity工程里找到Plugins文件夹右键“Add Reference”勾选Microsoft Word 16.0 Object Library不同版本号不同。然后写一个静态方法using System.IO; using Microsoft.Office.Interop.Word; public static class WordToPdfConverter { public static bool ConvertToPdf(string wordPath, string pdfPath) { Application app null; Document doc null; try { app new Application { Visible false, DisplayAlerts 0 }; doc app.Documents.Open(wordPath, ReadOnly: true); doc.ExportAsFixedFormat(pdfPath, WdExportFormat.wdExportFormatPDF); return true; } catch (System.Exception e) { Debug.LogError([WordToPdfConverter] e.Message); return false; } finally { if (doc ! null) doc.Close(0); if (app ! null) app.Quit(); System.Runtime.InteropServices.Marshal.ReleaseComObject(doc); System.Runtime.InteropServices.Marshal.ReleaseComObject(app); } } }这里最大的问题是进程残留。如果你在app.Quit()之后没有正确释放COM对象后台的WINWORD.EXE进程会一直挂在那里。项目跑久了会积累几GB内存。我的习惯是每次转换完就去系统进程列表里捞一次WINWORD.EXE强制Kill。虽然粗暴但稳定可靠。注意不要无差别杀掉用户自己打开的Word文档进程可以在打开COM前记录PID转换结束后只杀这个PID。4.3 Excel导出PDF的页面设置坑Excel的导出比Word讲究很多。默认导出会把整个工作表拼成一页经常出现“内容被压缩成一团字体小到看不见”的情况。所以导出前要设置页面sheet.PageSetup.Orientation XlOrientation.xlLandscape; sheet.PageSetup.FitToPagesWide 1; sheet.PageSetup.FitToPagesTall false; // 让行数尽量按实际页数分页 sheet.PageSetup.Zoom false;配合Workbook.ExportAsFixedFormat效果才接近“打印预览”。如果涉及打印区域还得注意PrintArea有没有设置否则会把空行空列全导出来。4.4 PPT导出PDF每页幻灯片对应一个PDF页PPT的处理最简单分别打开演示文稿直接Presentation.ExportAsFixedFormat就可以。默认情况下每页幻灯片对应一个PDF页面。要关注的是导出图片分辨率COM导出时不会像PPT手动“另存为图片”那样可选清晰度最后得到的PDF清晰度足够正常阅读但如果你想截取某一页做缩略图还是用PDF转Texture时的DestinationWidth控制。需要说明的是Office COM只能运行在Windows上而且存在“无法创建ActiveX组件”之类的权限坑。如果目标不给装Office那就只能用LibreOffice的无头模式转换实际上社区很多项目也是这么干的只是排版细节和微软产品有细微差异特别是Excel的样式个性设置越少差异越小。5. 跨平台与轻量替代WebView与在线预览服务5.1 用WebView一劳永逸如果你的项目目标是Windows之外比如Unity WebGL、移动端那本地COM和WinRT方案都不太好使。这时我建议直接嵌入一个WebView组件。Unity官方有WebView插件付费开源社区也有Android/iOS WebView插件。原理是一样的用浏览器内核加载HTML页面在页面里通过iframe或JavaScript库显示文档。对于PC端也可以用Unity的winhttp或WebView2封装但嵌入底层浏览器内核意味着内存占用增大而且移动端和桌面端的浏览器兼容性差异会带来新的排错成本。我通常只在“必须保留文档内超链接/动态交互”时才走这条路。5.2 更轻的替代服务端转换后拉取图片企业内网项目里最常见的做法是在服务器放一个小服务接收文件调用LibreOffice或Office COM转换成PDF再用PDF渲染成图片客户端用UnityWebRequestTexture直接下载图片。这样客户端不需要装Office也不需要操作WinRT。缺点是开发量在那儿文件上传、队列、进度状态、缓存清理都要自己整。如果你的文件都是公开可访问的也有在线预览服务的现成接口可用但需要注意将文件放到公网URL上会有隐私泄露问题不一定适合企业数据。我更推荐自己搭一个内网转换服务用SDK还是命令行无所谓关键是稳定。6. 常见问题与排查技巧实录6.1 问题速查表问题现象可能原因解决办法Unity编译报错找不到Windows.Data.Pdf未勾选WinRT支持Player Settings - Windows Standalone - Use Windows Runtime Support转换后图片红蓝通道混乱TextureFormat用错使用BGRA32不要用RGBA32PDF页面内容变形目标高度计算错误根据page.Size.Width/Height等比计算Word转换PDF后卡住进程残留COM对象未释放捕捉PID并Kill加超时逻辑Excel导出后内容缩在一起页面设置未生效设置FitToPagesWide1FitToPagesTallfalse每次转换内存暴涨创建了太多Texture未销毁使用对象池和LRU缓存界面滚动时没刷新图片图片异步加载未触发UI重建调用LayoutRebuilder.ForceRebuildLayoutImmediate移动端无法调用Office COM平台限制改用WebView或服务端转换6.2 几个容易被忽略的细节第一个细节WinRT的PdfDocument.LoadFromFileAsync需要文件路径但如果路径包含中文有时会报“系统找不到指定的文件”。保险做法是先把文件复制到Application.temporaryCachePath再用ASCII命名拷贝避免编码问题。第二个细节用COM时Office在首次启动时可能有弹窗比如激活提示这会阻塞转换。我在调用前会用注册表或命令行参数把AutomationSecurity设为禁用宏。Word的宏病毒提示虽然少见但企业电脑上策略严宏安全设置可能影响COM的正常使用。项目里做一层异常捕获把“无法创建COM对象”和“权限不足”分别提示给用户方便排查。第三个细节如果你想在UGUI里用一个RawImage实时显示当前页不要反复创建新的Texture。正确做法是提前分配一个足够大的Texture每次渲染完用LoadRawTextureData覆盖如果尺寸不固定那就封装一个TexturePool按页面尺寸复用。这条优化对长文档体验提升非常明显。第四个细节UnityEngine.UI.VerticalLayoutGroup这类布局组件在动态添加子项后经常不刷新昨天还“本事”的东西今天突然空一块多半是没强制重建布局。尤其是用异步协程加载图片时加载完成后必须主动调用LayoutRebuilder.ForceRebuildLayoutImmediate(rectTransform)否则界面一直显示空白。6.3 性能优化建议转图片时按需加载默认只转第一页和当前页翻页时再处理下一页。控制目标像素PDF渲染的DestinationWidth不要超过2048否则UI缩放后其实看不出来差别但GPU显存占用翻倍。小图片用Sprite大图用RawImageImage组件是为UI九宫格设计的大尺寸动态图片反而让RawImage更合适。全部转完再批量加载不如逐页转、逐页显示用户看到的是“翻页流畅”而不是“加载半天一次性出来”。7. 写在最后的一点经验这套“文档转PDF、再转Texture”的方案我在两个项目里验证过一个给客户做数据看板一个做内部资料库。稳定运行了半年多没出过严重问题。大部分人觉得Unity显示Office文件是冷门需求实际上只要你的工具承担了“管理资料”和“查看结果”的功能这个需求几乎必然出现。我个人最深的体会是别想着在Unity里完美复刻Office的排版和交互那是自找麻烦。把文档当成“内容来源”输出成图片或网页才是符合引擎特性的做法。真要做编辑功能老老实实启动外部Office程序或者做跳转都比在Unity里塞一个重型编辑器靠谱。如果在项目里遇到了更刁钻的格式问题优先检查“Office版本”和“文件是否包含加密/只读标记”。这两个因素能解释掉九成以上异常。遇到实在搞不定的可以先手动把文件用Office另存为PDF再走PDF管道很多坑其实是Office自身格式兼容导致的跟渲染管线没关系。最后再分享一个实用小技巧转换完成后给文件加个Hash缓存只要文件内容没变下次打开直接读缓存的PDF图片不必重新走一遍COM流程。这样在用户连续打开同一种文档时预览速度能提升好几倍。本文还有配套的精品资源点击获取