Android Studio中基于.docx模板生成文档的代码问题求助

架构老林

2026-5-19

我来帮你排查在Android中使用xdocreport生成docx文档的问题，结合你给出的项目结构、模板和代码信息，咱们可以从这几个方向一步步找问题：

一、先确认依赖与项目配置

首先检查xdocreport-1.0.4.jar是否正确引入：从你的项目结构截图来看，jar包放在了libs目录，记得右键jar包选择Add as Library，让Android Studio把它加入项目依赖。
xdocreport不是独立运行的，它依赖POI系列的库（比如poi-ooxml、poi），而且版本要匹配——1.0.4版本的xdocreport对应POI 3.13左右，要是没加这些依赖，大概率会出现找不到类的异常，得把这些必要的jar包也一起引入到libs里。

二、模板文件的细节检查

你的模板是MergeField类型，一定要保证模板里的域名称和代码中设置的参数名完全一致（包括大小写），比如模板里写的是Nombre，代码里就不能写成nombre，不然会匹配不上，生成的文档里还是原始的域标记。
还要确认模板文件的读取路径：如果模板放在assets目录，读取时路径要写对；要是放在外部存储，Android 6.0以上得动态申请读取权限，不然会读不到文件。

三、核心代码逻辑排查

结合你提到的GeneradorDocumentosService.java和Main.java，重点检查这几块：

模板加载与报告初始化
加载模板的代码要确保路径正确，模板引擎选对——MergeField一般用Velocity或者Freemarker，要和模板类型匹配，比如：
```
InputStream in = getAssets().open("Test.docx");
IXDocReport report = XDocReportRegistry.getRegistry().loadReport(in, TemplateEngineKind.Velocity);
```
要是这里报错，大概率是模板路径错了，或者缺少依赖库。

参数填充环节
检查所有模板里的MergeField都有没有赋值，比如：

IContext context = report.createContext();
context.put("Nombre", "Domingo");
context.put("Apellido", "MG");
// 模板里有多少个域，就要对应put多少个键值对

漏填的话，那个域就不会被替换，还是显示原始标记。

文档生成与存储权限
Android里写文件要注意权限和路径：别直接往SD卡根目录写，建议用应用专属的外部存储目录，比如getExternalFilesDir(null)，这样Android 11及以上不用申请权限，代码示例：
```
File outFile = new File(getExternalFilesDir(null), "result.docx");
OutputStream out = new FileOutputStream(outFile);
report.process(context, out);
```
要是是Android 11以下的系统，别忘了在AndroidManifest.xml里加存储权限：
```
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
```
异常捕获与日志排查
一定要加完整的异常捕获，打印详细日志，这样能快速知道哪里错了：
```
try {
    // 你的生成文档逻辑代码
} catch (Exception e) {
    e.printStackTrace();
    Log.e("DocGenerator", "生成文档失败: " + e.getMessage());
}
```
看日志就能知道是模板读不出来、参数匹配错了，还是权限不够。

四、Android环境下的常见坑点

虚拟机兼容性问题：xdocreport依赖的POI库有些类（比如AWT相关的）在Android的ART虚拟机里跑不了，这时候可以试试用专门适配Android的POI版本（比如poi-android）替换原生POI库。
模板编码问题：确保你的Test.docx模板是UTF-8编码，不然生成的文档可能会乱码。

要是按这些步骤排查完还是有问题，把具体的错误日志或者异常信息贴出来，就能更精准地定位问题啦~

内容的提问来源于stack exchange，提问作者DomingoMG