简介这是一份面向Unity开发者的文档显示功能实现资源适用于需要在Android平台集成Word、Excel、PDF、PPT等文件预览能力的教育、办公及文档管理类应用。压缩包共2000个文件容量172.43MB包含C#脚本、DLL库、XML配置、Meta与Asset资源文件以及少量docx、xlsx、pptx、pdf示例文档并带有若干说明文档与文本文件方便对照结构进行二次开发和调试。已有913人学习下载适合有一定C#基础、正在处理移动端文档展示需求的Unity中级开发者。资源围绕平台兼容性、第三方库调用、AndroidWebView集成和性能优化等要点整理了实现思路与代码结构能帮助读者快速理解在Unity中解析并呈现常见办公文档的技术路线减少自行摸索和踩坑成本。1. Unity 显示 Word、Excel、PPT、PDF 等文件别急着找插件先回答三个问题我在做工业一体机和展厅项目时经常接到一句话“把文档列表做进 Unity点开就能显示 word 和 pdf。”听起来像是加个 unity 扩展就完事但第一个原型通常会翻车——文档是打开了弹窗却把 Unity 界面挡在身后或者直接绿屏、黑屏。这个需求本质不是“显示文件”而是“在 Unity 的渲染界面里嵌入其他格式文档的预览通道”。能解决它的路子有四条转图片、转 PDF 再渲染、嵌套 WebView、后端转换前端展示每条的适用边界和坑完全不同。适合谁看这篇文章做展厅大屏、培训考核、数据可视化配套工具、生产管理系统的 Unity 开发者尤其是 Windows 平台为主、又不想把整个项目改成 Electron 的那类团队。动手前先回答三个问题要不要让用户编辑文档文档要离线还是要走内网目标平台是 Windows 还是 Android/iOS这三个答案直接决定选型方向。2. 选型四条技术路线先按“要不要编辑”砍掉一半注意本章不是罗列插件而是理顺“谁在真正渲染文档”。选型错误会在项目后期付出数倍返工代价。2.1 转图片方案用 Office COM 把 Word/Excel/PPT 导成 PNG先解释一下为什么优先考虑转图片。Unity 是游戏引擎它的 UI 系统UGUI/UI Toolkit只认 Sprite/Texture不认 docx 或 pptx。你把一个 Word 文件直接拖给 RawImage它不会自己变成像素。所以最早的落地思路是“在进入 Unity 之前先把文档变成图片”锁定格式消除变量。具体做法Windows 机器上安装 Office用 Word/Excel/PowerPoint 的 COM 接口把文档导出为 PDF 或 PNG再把这个中间产物丢给 Unity 加载。很多团队的第一反应是去找 unity 扩展但文档渲染最终不在 Unity 的图形管线上扩展只是壳底层绕不开“谁来做解析”这个问题。优点非常明显所见即所得导出结果就是 Office 排版引擎的真实输出字体、分页、表格都不需要你重新实现缺点是强依赖本机 Office且 COM 进程管理很烦这点我会在第 5 章展开。它适合什么样的项目单机版工具、展厅大屏、文档总数在几百份以内、没有频繁更新需求的场景。如果文档源文件随时在变每次更新都要重新跑一遍转换维护成本会很快超过收益。这个方案还有一个变体是“只转第一页”或“只转指定页”常用于做列表缩略图。比如在一体机左侧放一个文档列表每项需要一张缩略图预览那就没必要把整份 200 页的 PPT 全转掉只转封面页就够。用 COM 的 ExportAsFixedFormat 转 PDF 后再调 PDF 渲染接口取第一页图片。列表和详情的预处理链路可以分开列表用低分辨率缩略图详情用完整 PDF。2.2 统一转 PDF 再渲染借 PDFium/MuPDF 把 PDF 页变成 Texture2D转图片方案有个软肋如果一份 Excel 有几十个工作表或者一份 Word 有 100 页全转成图片序列目录、内存和加载速度都很难接受。更常见的选择是“先转 PDF进 Unity 后再动态渲染 PDF 页”。PDF 在这里不是展示格式而是中间交换格式。原因有三第一PDF 是固定版式无论在哪台机器上渲染页面拆解和坐标计算都比直接解析 docx 可靠第二PDFium、MuPDF 都有独立的 native 渲染库Unity 通过 DllImport/Plugins 调用不需要 Office 常驻第三后端转换工具可选的很多Windows 上可以继续用 Office COMLinux 上可以用 LibreOffice headless反正最终产物都是 PDF客户端不需要关心来源。这条路线适合中到大批量文档、交互要求高的项目也适合想做 Android 端的团队——移动端没有 Office COM但 PDF 渲染库可以编出移动端版本。PDFium 是 Chromium 项目里的 PDF 渲染引擎只负责“把 PDF 画到一块内存 bitmap”不负责 Word/Excel/PPT 的解析所以必须配合前一步的“转 PDF”。MuPDF 也是同级别选择它额外带 xps/epub 支持但对 Unity 的接入方式没有本质区别。我不会在“选 PDFium 还是 MuPDF”上花太多时间因为项目里多半是哪个能编出稳定 DLL 用哪个如果只做 WindowsPDFium 的预编译包更好拿。渲染性能上单页 A4 在 2 倍缩放约 1400x2000下PDFium 的耗时通常在 30ms-100ms 之间完全够翻页交互。这里唯一要提醒的是PDFium 本身不做“pdf 解析”之外的文档结构理解你要想从 PDF 里提取正文做全文搜索那是另一套 API预览阶段别碰留到第 6 章再说。2.3 内嵌 WebView 方案WebView2 在 Windows 平台直接打开 Office 与 PDF第三种思路是“不做渲染做浏览器宿主”。Windows 上装 WebView2 Runtime 后Unity 可以通过官方插件把一块浏览器窗口嵌进 UI 层级。浏览器内核本身就能显示 PDF以及部分 Office 文件取决于本机是否有 Office 关联或是否走 Office Online 预览。这个方案的直接价值是不需要维护 COM 转换链路不需要引入 PDFium代码量最小只要把文件路径或网络 URL 丢给 WebView2 的 Navigate 方法它自己搞定缩放、翻页、打印web 页面本来就为打印做了全套准备。代价也很明显渲染结果是一块独立于 Unity 渲染管线的原生窗口很多团队遇到的“黑屏、被遮挡、无法叠加 UI”都在这一层此外Canvas 上的 Transform/遮罩对系统窗口不一定生效你想在文档上画一个半透明遮罩做“强制阅读模式”用 WebView2 会很别扭。所以 WebView2 适配的场景是项目本身就对 UI 层级要求不苛刻例如内部工具、后台管理页面或者文档预览里有大量网页交互需求比如 PDF 内嵌了超链接、动态表单那 WebView2 是天然合适的。还要注意运行时依赖目标机器必须装了 WebView2 RuntimeUnity 包里要带 Loader DLL具体坑在第 5 章写。如果是内网部署且不允许外发文件Office Online 预览那条线要谨慎用——它会把文档传到在线服务去渲染这个隐私决策要在项目启动前跟客户确认而不是等上线前再解释。2.4 服务器/局域网共享预览把解析压力挪到后端Unity 只当显示器最后一类思路适合“多台一体机共用一个文档库”的架构。前端 Unity 只负责请求和展示后端服务器负责把 Word/Excel/PPT 转成 PDF 或图片。这样做的好处是文档更新不用每台机器挨个跑转换后端升级转换引擎也不影响客户端坏处是需要额外维护一台带转换服务的机器。后端技术上Windows 服务器可以装 Office 用 COM就是第 3 章那套逻辑搬到服务端Linux 服务器则用 LibreOffice headless一条命令就能完成转换soffice --headless --convert-to pdf --outdir /data/preview /data/uploads/guide.docxLibreOffice 的转换质量与 Office COM 相比在复杂排版上略有差距比如某些字体回退、Word 文本框浮动位置但对付“预览”这个场景是足够的。如果你已经有内网文件服务这个方案的增量成本其实不大。它和“转图片方案”的本质区别是转换动作从客户端前置到了服务端客户端的资源占用趋近于零。适合展厅里同时跑 Unity 展示和其他程序的机器也适合后端已经有文档管理系统的企业项目。四条路线对比直接用一个表收束路线是否依赖 Office客户端资源占用交互能力部署成本推荐场景转图片是转换机低弱翻页要另做低单机、文档数量少转 PDF PDFium是转换机可切换中强翻页缩放标注中中大批量、跨平台WebView2否依赖 Runtime中高强浏览器内核低内部工具、网页交互多后端转换否客户端极低取决于客户端高多终端共享文档库选型标准我一般这样定先问“要不要编辑”。要编辑就别在 Unity 里硬做直接用 Application.OpenURL 唤起外部程序更省事不要编辑再按“离线/在线”和“单机/多机”往下二分。离线单机选转图片或 PDFium在线多机选后端转换如果文档里全是 PDF 且无 Office 文件直接走 PDFium省掉 Office COM 这一层。3. 用 Office COM 把 Word/Excel/PPT 批量转 PDF脚本与参数说明很多 Unity 开发者看到“Office COM”第一反应是装 Microsoft.Office.Interop 的 NuGet 包然后在 Unity 工程里直接引用。这能跑但会让 Unity 工程的编译链路变重而且 Unity 的编辑器编译和运行时工程是两个环境程序集版本不一致会在打包时突然报错。我更常用的做法是单独建一个 .NET Framework 的控制台或类库项目专门做“文档转换”Unity 通过子进程调用它。这样 Unity 工程里不需要引用任何 Office 相关程序集把 COM 造成的编译期污染隔离在 Unity 之外。对应到第 2.4 节说的“后端转换”也同理——那个控制台程序可以直接部署到服务器。3.1 先做转换工具Word/Excel/PPT 分别怎么调 COM 接口先用 Word 开刀。下面的代码是控制台程序里最核心的函数用反射调 COM不依赖 Interop 程序集。这里用反射的意图是“少装一个包、少一类版本冲突”代价是代码难看一点但这类工具写好一次就长期用值得// WordToPdf.cs —— .NET Framework 4.7.2 控制台程序 using System; using System.IO; using System.Reflection; using System.Runtime.InteropServices; class WordConverter { public static void Convert(string src, string pdf, int optimize 1) { object word null, docs null, doc null; try { Type type Type.GetTypeFromProgID(Word.Application); if (type null) throw new Exception(未安装 Microsoft Word或 ProgID 注册表损坏); word Activator.CreateInstance(type); // 隐藏窗口、关闭弹窗和宏警告是转换不卡死的前提 word.GetType().InvokeMember(Visible, BindingFlags.SetProperty, null, word, new object[] { false }); word.GetType().InvokeMember(DisplayAlerts, BindingFlags.SetProperty, null, word, new object[] { 0 }); docs word.GetType().InvokeMember(Documents, BindingFlags.GetProperty, null, word, null); doc docs.GetType().InvokeMember(Open, BindingFlags.InvokeMethod, null, docs, new object[] { src, true }); // 第二个参数 true ReadOnly // ExportAsFixedFormat 参数1: 输出路径; 参数2: 17 wdExportFormatPDF; // 参数4: 0 按打印优化, 1 按屏幕优化字体嵌得更全屏幕预览更清晰 doc.GetType().InvokeMember(ExportAsFixedFormat, BindingFlags.InvokeMethod, null, doc, new object[] { pdf, 17, false, optimize }); Console.WriteLine(OK: pdf); } finally { if (doc ! null) { doc.GetType().InvokeMember(Close, BindingFlags.InvokeMethod, null, doc, new object[] { false }); Marshal.ReleaseComObject(doc); } if (word ! null) { word.GetType().InvokeMember(Quit, BindingFlags.InvokeMethod, null, word, null); Marshal.ReleaseComObject(word); } } } }逻辑说明这段代码的关键有 4 处。第一Type.GetTypeFromProgID 是拿注册表里的 COM 标识需要机器真实装了 WordWPS 如果兼容注册了 ProgID 也能用但验证程度不如 Word。第二Visiblefalse 和 DisplayAlerts0 两个设置缺一不可否则 Word 可能在转换中弹出“是否保留格式”之类的模态对话框子进程直接挂在那里等一个永远不来的点击。第三Open 只传路径和 ReadOnly 两个参数后面的可选参数不传用的是 Word 默认值具体业务文档如果有密码需要在第 4 个参数传密码字符串。第四finally 里 Close 和 Quit 是必须的如果函数中间抛异常word 对象没 Quit就会在任务管理器里留下一个 WINWORD.EXE 进程下次再调转换就会撞上“文件被占用”这就是最常见的进程残留坑。接着是 Excel。Excel 的坑跟 Word 不太一样最大的区别是“导出作用域挂在 Workbook 而不是 Sheet 上”// ExcelToPdf.cs 核心片段 static void ConvertExcel(string src, string pdf) { object excel null, books null, book null; try { Type type Type.GetTypeFromProgID(Excel.Application); excel Activator.CreateInstance(type); excel.GetType().InvokeMember(Visible, BindingFlags.SetProperty, null, excel, new object[] { false }); excel.GetType().InvokeMember(DisplayAlerts, BindingFlags.SetProperty, null, excel, new object[] { false }); books excel.GetType().InvokeMember(Workbooks, BindingFlags.GetProperty, null, excel, null); // Open 参数: FileName, UpdateLinksfalse, ReadOnlytrue book books.GetType().InvokeMember(Open, BindingFlags.InvokeMethod, null, books, new object[] { src, false, true }); // 关键导出范围选择整个工作簿而不是默认的第一个工作表 object sheets book.GetType().InvokeMember(Worksheets, BindingFlags.GetProperty, null, book, null); sheets.GetType().InvokeMember(Select, BindingFlags.InvokeMethod, null, sheets, null); // Workbook.ExportAsFixedFormat 参数1:0PDF, 参数2: 输出路径, 参数3: Quality(0标准,1最小) book.GetType().InvokeMember(ExportAsFixedFormat, BindingFlags.InvokeMethod, null, book, new object[] { 0, pdf, 0 }); Console.WriteLine(OK: pdf); } finally { if (book ! null) { book.GetType().InvokeMember(Close, BindingFlags.InvokeMethod, null, book, new object[] { false }); Marshal.ReleaseComObject(book); } if (excel ! null) { excel.GetType().InvokeMember(Quit, BindingFlags.InvokeMethod, null, excel, null); Marshal.ReleaseComObject(excel); } } }逻辑说明这段代码里最容易漏的是 Worksheets.Select。如果不 SelectExcel 的 ExportAsFixedFormat 默认导出的是“当前活动工作表”一个包含 12 个月报表的工作簿最后只导出 1 页这是最常见的 Excel 转 PDF 翻车第 5 章会再提。参数方面ExportAsFixedFormat 的第一个参数 0 是 xlTypePDF如果传 1 就是导出成 XPS 文件第三个参数品质默认 0 标准导出来用于屏幕预览已经足够。如果 Excel 文件里有“打印区域”设置导出时也会遵守它这会导致某些内容被裁剪解决办法是在导出前把每个工作表的 PageSetup 重置一遍后面会讲。然后是 PowerPoint。PPT 的 COM 有个脾气它不允许完全隐藏窗口Open 时 WithWindow 参数必须为 true否则直接抛异常// PptToPdf.cs 核心片段 static void ConvertPpt(string src, string pdf) { object ppt null, pres null, presentation null; try { Type type Type.GetTypeFromProgID(PowerPoint.Application); ppt Activator.CreateInstance(type); // PPT 不允许无窗口打开只能把窗口移到屏幕外或最小化 ppt.GetType().InvokeMember(Visible, BindingFlags.SetProperty, null, ppt, new object[] { 1 }); // 1 msoTrue pres ppt.GetType().InvokeMember(Presentations, BindingFlags.GetProperty, null, ppt, null); // 参数含义依次是: FileName, ReadOnly, Untitled, WithWindow presentation pres.GetType().InvokeMember(Open, BindingFlags.InvokeMethod, null, pres, new object[] { src, true, false, false }); if (presentation null) throw new Exception(PPT 打开失败可能是文件格式兼容问题); // PowerPoint 的 ExportAsFixedFormat: 参数2: 2 ppFixedFormatTypePDF presentation.GetType().InvokeMember(ExportAsFixedFormat, BindingFlags.InvokeMethod, null, presentation, new object[] { pdf, 2 }); Console.WriteLine(OK: pdf); } finally { if (presentation ! null) { presentation.GetType().InvokeMember(Close, BindingFlags.InvokeMethod, null, presentation, null); Marshal.ReleaseComObject(presentation); } if (ppt ! null) { ppt.GetType().InvokeMember(Quit, BindingFlags.InvokeMethod, null, ppt, null); Marshal.ReleaseComObject(ppt); } } }逻辑说明PPT 的 Open 参数比 Word 多两个第 4 个 WithWindow 传 false 看起来很合理不想弹窗但 PowerPoint 会直接报“远程过程调用失败”。这是因为 PPT 的 COM 对象模型强制要求窗口存在即使你 Visible 设成 1它也会真开一个窗口所以转换服务器上最好有桌面会话Windows 服务模式下跑 PPT 转换会失败这是一个环境限制。如果项目被迫在 Windows Server 上跑可以考虑把转换做成计划任务而不是服务。另外PPT 转 PDF 默认不会带演讲者备注这符合预览需求但如果你要导“备注版讲义”得通过 PrintOptions 设置不走 ExportAsFixedFormat那个我建议另开工具脚本不要跟预览链路混在一起。3.2 Unity 侧改造成异步加载协程与子线程怎么配合转换工具是独立进程Unity 这边要做的事就简单了用 Process.Start 启动它等退出码然后加载产物。这里有个原则不要在 Unity 主线程同步等待否则文档一多界面就冻住。常见做法是协程 Task 组合// DocPreviewManager.cs —— Unity 场景里的预览调度器 using System; using System.Collections; using System.Diagnostics; using System.IO; using System.Threading.Tasks; using UnityEngine; using UnityEngine.UI; public class DocPreviewManager : MonoBehaviour { public RawImage previewTarget; public Text statusText; private Queuestring _pending new Queuestring(); public void RequestPreview(string filePath) { if (!File.Exists(filePath)) { statusText.text 文件不存在; return; } _pending.Enqueue(filePath); if (_pending.Count 1) StartCoroutine(PumpQueue()); } private IEnumerator PumpQueue() { while (_pending.Count 0) { string src _pending.Dequeue(); string ext Path.GetExtension(src).ToLower(); string pdfPath Path.Combine(Application.temporaryCachePath, Path.GetFileNameWithoutExtension(src) .pdf); // 转换过程放到 Task 里不阻塞主线程WaitUntil 每帧检查完成 Taskbool task Task.Run(() { if (ext .pdf) { File.Copy(src, pdfPath, true); return true; } return RunConverter(src, pdfPath, ext); }); yield return new WaitUntil(() task.IsCompleted); if (task.Result File.Exists(pdfPath)) { statusText.text 渲染中...; yield return StartCoroutine(RenderPdfToUi(pdfPath, previewTarget)); } else { statusText.text 转换失败请检查源文件; } } } private bool RunConverter(string src, string pdf, string ext) { string exePath Path.Combine(Application.streamingAssetsPath, Tools, OfficeToPdf.exe); ProcessStartInfo psi new ProcessStartInfo(exePath, $\{src}\ \{pdf}\ \{ext}\) { CreateNoWindow true, UseShellExecute false, RedirectStandardOutput true, RedirectStandardError true }; using (Process proc Process.Start(psi)) { proc.WaitForExit(120000); // 120 秒超时防止 Office 弹出模态框卡死进程 return proc.ExitCode 0; } } }逻辑说明这里把“转换”从 Unity 进程里彻底摘了出去好处是就算 Office COM 崩了挂掉的只是子进程Unity 不会跟着崩溃。ProcessStartInfo 的 UseShellExecutefalse 是必须的否则没法重定向输出也无法拿到退出码。超时时间建议按文档类型区分Word 一般 30 秒够PPT 带复杂动画的可以放大到 120 秒如果机器配置低把 WaitForExit 的超时继续调大改成 300 秒也正常。缓存目录用 Application.temporaryCachePath系统会自动清理别往 StreamingAssets 写那在打包后是只读的。RenderPdfToUi 是第 4 章的内容这里先留一个协程接口到渲染章节再接上。3.3 批量场景的参数预设清晰度、页边距、隐私设置转换工具里最容易被忽视的是参数预设。很多人第一次跑通后就不再管参数结果换一批真实文档就出问题。我把常用参数整理成一张表照着初始化就不会差参数WordExcelPPT导出类型枚举17PDF0PDF2PDF屏幕优化optimize1Quality0默认是否嵌入字体导出设置中“嵌入所有字体”无默认嵌入页面方向按文档设置统一设为横向再导出按幻灯片大小可见窗口falsefalse必须 true另开窗口弹窗抑制DisplayAlerts0DisplayAlertsfalse无专门开关超时参考30s60s120s一个值得说清楚的参数是 Word 导出时的 optimize 值。ExportAsFixedFormat 的第 4 个参数其实是个大枚举它同时决定“按打印优化”还是“按屏幕优化”。按打印优化时PDF 里嵌入的字体子集会按打印机驱动的要求裁剪屏幕上看可能发虚按屏幕优化时字体会更完整地嵌入但文件体积略大。预览类项目我一般选 1屏幕优化打印类项目选 0。如果你发现 PDF 在 Unity 里渲染出来字迹边缘发虚第一件事不是调 PDFium 的缩放而是回头把转换工具的 optimize 改成 1 再导一次。Excel 页面设置还有一个坑很多业务表并不是按 A4 排版的默认导出会按“打印区域”切页列被拆到两三页里。统一做法是在导出前遍历所有 Sheet把 PageSetup.Orientation 设为 2横向PageSetup.Zoom 设为 falsePageSetup.FitToPagesWide 设为 1FitToPagesTall 设为 false这样一张超宽的表会被缩放到单页宽预览体验最好。PPT 则没有这个问题它按幻灯片尺寸导宽高比跟你做的幻灯片一致唯一要注意的是嵌入的音频视频不会进 PDF预览无碍。隐私设置提醒一句如果文档带修订痕迹、隐藏行、批注默认导出可能把“批注”带进 PDF。在 Word 导出前推荐把 doc.Revisions 的 AcceptAll 或者把“显示标记”设置为 false具体看业务要求。Excel 的隐藏工作表默认不导出这可能反而是你要的行为如果要把隐藏页也导出就得先遍历 Worksheets 把 Visible 改为 true这个需求不常见但遇到过“审计要求所有记录在 PDF 里可见”的项目提前知道总比现场改好。4. 在 Unity 里渲染 PDF用 PDFium 把页面变成 Texture2D 的最小实现PDF 显示环节是整个方案里最贴近 Unity 的一步也是“为什么不能用自己写解析器”的答案所在。PDF 的解析复杂度在于它要还原出矢量图形、字体轮廓、图层、色彩空间Unity 原生没有这套状态机。直接用 PDFium 渲染 bitmap是工作量最小的路径。第 2 章选型里我提到了 PDFium/MuPDF下面按 PDFium 讲因为它在 Windows 下最容易拿到预编译 DLL且 API 稳定你如果换成 MuPDF只需要替换 DllImport 的函数映射架构不用变。4.1 引入 PDFiumWindows 下加载 native DLL 的步骤第一步是把 native 库放进 Unity 工程。以 Windows x64 为例在 Assets 下建 Plugins/x86_64 目录把 pdfium.dll 放进去Unity 打包时会自动把它放进最终包。这里有两个基本注意点一是 DLL 的位数必须和 Unity 目标平台一致Editor 是 64 位就用 x86_64如果还要出 32 位版单独放一份 x86二是 pdfium.dll 内部依赖 zlib、libjpeg 这些静态链入的版本不要自己从系统目录拷贝DLL 文件应该完整来自官方打包产物否则启动时会报找不到入口点。这步看起来像是普通的 unity 插件安装流程但 DLL 的位数和依赖检查比普通 C# 插件严格得多别等打包到客户机器上再验证。然后是 C# 侧的初始化与清理。PDFium 要求进程开一个全局库实例Unity 的播放模式每进一次场景都会重新加载程序集所以初始化要跟场景生命周期对好// PdfiumInitializer.cs using System; using System.Runtime.InteropServices; using UnityEngine; public sealed class PdfiumInitializer : MonoBehaviour { [DllImport(pdfium)] private static extern void FPDF_InitLibrary(); [DllImport(pdfium)] private static extern void FPDF_DestroyLibrary(); [RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.BeforeSceneLoad)] private static void Init() { FPDF_InitLibrary(); Application.quitting () FPDF_DestroyLibrary(); } }逻辑说明RuntimeInitializeOnLoadMethod 保证 Unity 场景加载前就先调用 FPDF_InitLibrary避免第一次渲染时才初始化引发卡顿。Application.quitting 注册释放函数是为了在编辑器里反复进入播放模式时不把 native 资源泄漏给下一次播放。如果项目里有场景热重载Domain Reload建议在 OnDisable 里也做一次保护性判断不过最省心的方式还是把这个初始化脚本放在一个不销毁的场景里配合 DontDestroyOnLoad 使用。参数说明DllImport 的第一参数“pdfium”是 DLL 名Unity 在 Windows 下会自动去 Plugins/x86_64 找同名文件如果 DLL 版本名字带后缀比如 pdfium_x64.dll那第一参数也要改成一致的名字。4.2 渲染单页到 Texture2D关键 API 与内存释放渲染一页 PDF 到 Unity 的 Texture2D核心调用链是LoadDocument - LoadPage - 创建 bitmap - RenderPageBitmap - 拷贝像素 - 释放句柄。下面是我在项目里抽出来的最小实现包含所有必须的释放步骤// PdfPageRenderer.cs using System; using System.Runtime.InteropServices; using UnityEngine; public static class PdfPageRenderer { [DllImport(pdfium)] static extern IntPtr FPDF_LoadDocument(string path, string password); [DllImport(pdfium)] static extern void FPDF_CloseDocument(IntPtr doc); [DllImport(pdfium)] static extern int FPDF_GetPageCount(IntPtr doc); [DllImport(pdfium)] static extern IntPtr FPDF_LoadPage(IntPtr doc, int index); [DllImport(pdfium)] static extern void FPDF_ClosePage(IntPtr page); [DllImport(pdfium)] static extern double FPDF_GetPageWidth(IntPtr page); [DllImport(pdfium)] static extern double FPDF_GetPageHeight(IntPtr page); [DllImport(pdfium)] static extern IntPtr FPDFBitmap_CreateEx(int width, int height, int format, IntPtr buffer, int stride); [DllImport(pdfium)] static extern void FPDFBitmap_FillRect(IntPtr bitmap, int left, int top, int width, int height, uint color); [DllImport(pdfium)] static extern void FPDFBitmap_Destroy(IntPtr bitmap); [DllImport(pdfium)] static extern IntPtr FPDFBitmap_GetBuffer(IntPtr bitmap); [DllImport(pdfium)] static extern void FPDF_RenderPageBitmap(IntPtr bitmap, IntPtr page, int startX, int startY, int width, int height, int rotate, int flags); public static Texture2D RenderPage(string pdfPath, int pageIndex, float scale 2f) { IntPtr doc FPDF_LoadDocument(pdfPath, null); if (doc IntPtr.Zero) return null; try { IntPtr page FPDF_LoadPage(doc, pageIndex); if (page IntPtr.Zero) return null; int w (int)(FPDF_GetPageWidth(page) * scale); int h (int)(FPDF_GetPageHeight(page) * scale); // format4 对应 FPDFBitmap_BGRA32位与 Unity 的 BGRA32 纹理直接对应 IntPtr bitmap FPDFBitmap_CreateEx(w, h, 4, IntPtr.Zero, w * 4); FPDFBitmap_FillRect(bitmap, 0, 0, w, h, 0xFFFFFFFF); // flags0 表示正常渲染不带文字抗锯齿的额外选项兼容性最好 FPDF_RenderPageBitmap(bitmap, page, 0, 0, w, h, 0, 0); byte[] buffer new byte[w * h * 4]; Marshal.Copy(FPDFBitmap_GetBuffer(bitmap), buffer, 0, buffer.Length); Texture2D tex new Texture2D(w, h, TextureFormat.BGRA32, false); tex.LoadRawTextureData(buffer); tex.Apply(); FPDFBitmap_Destroy(bitmap); FPDF_ClosePage(page); return tex; } finally { FPDF_CloseDocument(doc); } } }逻辑说明这段代码的释放顺序是刻意安排的先释放 bitmap再关 page最后关 doc。如果把 FPDF_CloseDocument 放在 page 还活着的时候调用轻则渲染结果丢失重则 native 层直接崩溃。buffer 的拷贝用 Marshal.Copy是因为 FPDFBitmap_GetBuffer 返回的是非托管内存指针Unity 的 Texture2D.LoadRawTextureData 要求 byte[] 托管数组中间必须多一次拷贝对单页 A4 来说2 倍缩放下 buffer 是 8MB 左右这个拷贝耗时在几毫秒能接受。参数说明scale 是渲染缩放比。PDF 页面的宽度单位是“点”Point1 点约等于 1/72 英寸在屏幕上通常乘以 96/72 得到物理像素。如果直接把 scale 固定为 1A4 宽度只有约 595 像素在 1080p 屏幕上会明显模糊我一般设 1.5-2.0 让文字边缘干净但要注意 scale 越大纹理内存按平方增长A4 在 scale3 时约 2550 x 3300 像素单张纹理就是 30MB这是 unity 游戏优化里常被忽略的一块列表缩放图和详情页缩放一定要分开。flags0 是常规渲染如果要显示 PDF 注解/批注需要把 FPDF_ANNOT 常量加进去但这里做最小实现先不加。4.3 翻页、缩放、旋转交互参数的三个常调点渲染单页的代码跑通后交互层还有三个高频调整点翻页缓存、自适应缩放、旋转参数。翻页缓存不要每次翻页都重新 LoadDocument而应该把 doc 句柄保存在预览会话里翻页时只关上一页、再 Load 下一页可以预取前一页和下一页让翻页接近零等待。如果文档很大可以只缓存当前页前后各一页再加一个 LRU 队列把超过 5 页的旧页纹理释放掉。自适应缩放推荐按显示区域宽度反推 scale而不是用固定值。以 RawImage 的 rectTransform 为准先算出显示区域里可容纳的宽度像素再除以 FPDF_GetPageWidth得到 scale。这样同一套代码接不同的 UI 布局都不会糊。如果要同时支持超宽表格类 PDF记得保留“按宽度适配”和“显示整页”两个模式让用户手动切换。旋转参数FPDF_RenderPageBitmap 的 rotate 参数取值 0-3对应 0 度、90 度、180 度、270 度。竖向 PDF 在横屏一体机上展示时旋转参数设置为 1 或 3同时要交换宽高值否则画面会被拉伸。这里的常见错误是只转图片不换宽高导致显示比例不对代码里应在 rotate1 时把 w/h 对调后再创建 bitmap。最后补一句关于“pdf 解析”的边界预览阶段只需要渲染不需要提取文本。PDFium 虽然提供 FPDFText_LoadPage 系列接口做文本解析但坐标、段落、分页的映射关系比渲染复杂得多做全文搜索或复制粘贴是独立功能建议放到后端或专门工具里Unity 只消费结果别把预览代码和解析代码混在一个类里否则后添加的解析逻辑很容易把渲染性能拖垮。5. 避坑指南文档预览在 Unity 里的 5 个典型翻车现场文档预览这功能大部分时间不是写不出来而是死在边界情况上。下面 5 个坑是我实际跟项目时频繁遇到的每一条都按“现象 → 原因 → 解决”写你对照自己的现象找解决路径比逐个读报错更快。5.1 现象COM 转换偶尔报“拒绝访问”Office 弹窗卡死转换背景是转换服务跑在 Windows 服务器或一体机上连续转换十几份后突然某次调用报“拒绝访问”或“RPC 服务器不可用”任务管理器里有一堆 WINWORD.EXE / EXCEL.EXE 残留。原因上一轮转换异常退出COM 对象没有正确 Quit或者 Word 在首次启动时弹出了“隐私设置”“登录 Office”之类的向导弹窗Visiblefalse 挡不住这种模态窗子进程被挂起。解决转换程序在启动时先做一次实例清理用 taskkill 清掉同名进程前提是确认这台机器没有别人正开着 Office再把 Office 组件的“自动化安全”注册表项设好允许脚本访问。更现实的宽松做法是给每个子进程加超时超时直接 Kill不等待。转换程序本身用独立进程跑的好处就在这里杀错也不影响 Unity 主程序。进程名清理可以用一句命令taskkill /F /IM WINWORD.EXE但注意别在用户自己的开发机上跑这个会把正在编辑的文档一起关掉这条只推荐在专用转换机/服务器上启用。5.2 现象转出来的 PDF 白边大、字发虚背景Word/PPT 用 COM 转 PDF 后在 PDFium 里渲染发现左右两圈大黑边文字边缘发毛尤其 100% 缩放时明显。原因白边大的原因是文档本身的纸张方向和内容方向不一致比如页面是 A4 竖版但内容其实很窄导出时默认带上了完整的纸张边距字发虚的原因多半是 optimize 参数用了按打印优化的 0打印机驱动按 300 DPI 去制作字型而 PDFium 渲染时按 96 DPI 缩放字形边缘被重采样。解决转换时把 optimize 参数切到按屏幕优化1并且统一把目标页面纸张设为 A4 或与内容一致的宽高。Excel 还要注意把 PageSetup.FitToPagesWide1避免被拆页。改完参数重新转换白边和发虚会同时改善。如果还有边距可以在 Unity 侧做“白边裁剪”把纹理边缘的纯白像素列裁掉再显示但这是治标能留到最后用。5.3 现象PDFium 渲染中文/日文缺字或乱码背景转换出的 PDF 在 Windows 的 Edge 里打开正常但在 Unity 的 PDFium 渲染里中文变成方块或日文假名消失。原因PDF 没有把字体完整嵌入只嵌了子集而 PDFium 渲染时找不到对应的字体映射或者转换机器上的字体和运行机器上的字体不一致PDF 里虽然嵌了字体名但字形数据缺失。解决在转换端把“嵌入所有字体”打开Word 导出设置里勾选或者用 COM 设置 EmbedTrueTypeFontstrue让 PDF 自包含字形。如果文档已经生成没法重转可以在渲染端给 PDFium 设置系统字体目录让它去匹配中文字体。但最稳的还是源头嵌入这条建议写进转换工具的默认配置。另一个附带问题扫描版 PDF 本来就是图片PDFium 渲染没问题但如果要做文本搜索或复制会发现提取出来是乱码因为那是 OCR 前的纯图片这个属于 pdf 解析范畴和渲染缺字是两码事别混在一起排查。5.4 现象WebView2 在 Unity 里黑屏/白屏或打包后功能消失背景选型时走了 WebView2 路线在编辑器里预览正常打包到客户机器上导航栏按钮有了窗口区域却一直白屏或者加载后黑屏什么内容都不显示。原因三选一。第一目标机器没装 WebView2 Runtime第二webview2loader.dll 被 Unity 打包时漏掉了第三Unity 的线程模型和 WebView2 的 UI 线程要求冲突初始化时机不对最常见是把 CoreWebView2Environment 创建放在了非主线程。解决把 webview2loader.dll 放到 Assets/Plugins/ 目录让 Unity 按插件处理在运行时检查 Runtime 是否安装可以调用 CoreWebView2Environment.GetAvailableBrowserVersionString()抛异常就往浏览器下载页引导初始化 Environment 必须在主线程等 UI 事件Unity 的协程里用“started completed”两个标记来做不要直接同步等待。5.5 现象打包到 Android/iOS 后用不了“功能隐形消失”背景开发期一直用 Windows Editor 跑交付前打 Android 包才发现 Word/Excel/PPT 全部打不开代码里没有报错但界面没有内容。原因COM 这条路是 Windows 专属Android/iOS 不存在 ProgIDWebView2 也没有移动版。如果代码里没有按平台条件分支调用方拿到 nullUI 上就表现为空白。解决移动端不要走 COM 转换和 WebView2而是把文档在服务端转成 PDF客户端只做 PDFium 渲染如果不想上服务器Android 用系统 Intent 调起 WPS/Office 打开原文件iOS 用 Quick Look 预览框架让系统去处理格式Unity 退到后台。最省心的移动端方案其实是“后端转换 PDFium”——第 4 章的实现稍加改动就能编到 AndroidPDFium 有对应的 native 库不需要改渲染逻辑。6. 进阶技巧PDF 覆层标注、远程转换接口与“系统打开”保险丝如果只是“能看”上面 4 章已经够用。下面三个技巧是把这套预览能力做成产品的最后一层适用于“还要在文档上标记位置、圈出重点”的协同类需求。6.1 在 PDF 页上叠 UI把屏幕坐标映射回 PDF 坐标批注的本质是一组“矩形 文本 页码”的数据。在 Unity 里做标注不要把批注直接画进 PDF而是维护一个与页面同尺寸的 Canvas 层把 PDF 纹理作为背景批注用一个 RectTransform 精确定位。坐标换算只有一个关键点UGUI 的 RectTransform 原点是中心Y 轴向上而 PDF 渲染的 bitmap 原点是左上角Y 轴向下所以显示和取点需要各翻一次// 屏幕上的点转 PDF 页内坐标 Vector2 ScreenToPdf(Vector2 localPos, RectTransform viewRect, Texture2D pdfTexture) { float u (localPos.x viewRect.rect.width * 0.5f) / viewRect.rect.width; float v (localPos.y viewRect.rect.height * 0.5f) / viewRect.rect.height; return new Vector2(u * pdfTexture.width, (1f - v) * pdfTexture.height); }逻辑说明先把 UGUI 的中心原点转成左下角原点的比例再通过 1-v 把左下角原点翻成左上角原点最后乘纹理像素尺寸得到 PDF 坐标。存储时把页码坐标矩形宽高颜色文本序列化成 JSON下次预览按页码加载对应批注就成了一个轻量标注层。这个方案比直接在 PDFium 里画 annotation 简单且不会污染源 PDF 文件。6.2 远程转换服务的接口约定如果走后端转换路线接口不要设计成“上传后等同步结果”转换耗时会拖垮请求。建议拆成两个动作提交转换任务、轮询结果。动作接口参数返回上传并提交转换POST /api/convertmultipart/form-data: file, targetpdf任务 ID查询转换结果GET /api/convert/{id}无pending / success / failedsuccess 附带下载路径下载产物GET /api/files/{name}无PDF 文件流服务端用 LibreOffice headless 转 PDF 那套命令配合一个简单工作队列每份文档转换完成就写文件系统Unity 端协程轮询 1 秒一次拿到 URL 后用 UnityWebRequest 下载到缓存目录再交给 PdfPageRenderer。这个交互模型比同步接口稳健尤其当某份 PPT 转换超过 60 秒时不会让客户端一直挂在下载上。6.3 最后的保险丝保留一个“用系统打开”的按钮所有的预览方案都有概率碰上“格式兼容”问题尤其是客户发来的加密文档、宏文档、老版本 .doc。我的习惯是在详情页右下角留一个低调的按钮——用系统关联程序打开原文件Application.OpenURL(file:// path)。这个动作看起来很原始但它能在预览翻车时兜住场景对内部员工工具来说甚至可以直接当作高性能预览方式。我做这套功能时养成习惯先把“要不要编辑、能不能联网、跑在谁的机器上”三个答案写在需求单第一行再决定走哪条路。COM 的进程残留、PDFium 的内存释放、WebView2 的 Runtime 缺失这三个是最耗时间也最容易复发的坑值得在项目第一天就做好预案。希望帮到你。本文还有配套的精品资源点击获取
