📦 read_pdf_text 用于读取 PDF 页数、全文和分页文本。我在鸿蒙平板讲义页面里遇到了选中文档却无法复制的问题,修复授权 URI 的读取方式后,又接入系统 PDFKit,让导入的讲义可以按页浏览、保存片段。
完整代码已开源在 oh-flutter/read_pdf_text,本次修改的接入方式见第五节。有问题可以到仓库提 Issue,也可以来 鸿蒙系统Flutter开源库社区 交流 Flutter 鸿蒙适配问题。
前言
我在鸿蒙平板模拟器上做了一个讲义阅读页,左边选文件,右边按页显示文字,需要保留的片段放在页面下方。工程里有一份四页双语 PDF,我想先用它试试:从公共“文档”目录选中讲义,能不能直接在这个页面里读到内容。
接入 read_pdf_text 社区适配版后,文件选择器能打开,取消也正常,可选中文件后却报了“文件不存在”。我顺着原生代码查到 URI 复制这一段,改用只读文件描述符转存,再接入系统 PDFKit,让页面顺利读出了四页文本。后面检查缓存时,我发现初版自己加的“清理旧副本”会让之前返回的路径失效,于是撤掉这项策略并补上清理失败上报,重新在平板模拟器上跑通了连续导入与片段摘录。
一、使用场景与原版问题
1.1 平板页面需要完成什么
我把导入控制、分页阅读和片段保存放在同一页。平板横屏时,左边留给文件来源和诊断信息,右边显示讲义;窗口宽度达到 760 逻辑像素时左右分栏,窄窗口则纵向排列。这些布局由 Example 处理,插件只负责取得文件和读取文本。设备类型虽然也配置了手机、平板与 2in1,实际运行对照用的是平板模拟器。
测试时,我从平板公共“文档”目录选择 tablet_lecture_notes.pdf,查看页数和分页文字,再把选中页的片段加入下方栏位。这份讲义是工程里的测试样本,每页都有一个不同的校验标记。检查结果时,我同时看页面数量、标记所在页和文本内容,免得卡片显示出来了,读取结果却错页或漏页。
“加入摘录”保存的是该页前两条非空文本行,标题和校验标记也可能被选进去。这是按行截取文本,不做摘要,所以我把原来的“课程重点摘录栏”改成了“页面片段栏”,并在空状态里写明取行规则。换文档成功或读取失败时,页面会清空旧片段;用户只是取消选择,则继续保留当前文档。
这条流程里,系统选择器负责让用户授予具体文件的访问权限。插件拿到授权 URI 后,把文件转存到解析器能读取的位置,再把文本或错误传回 Flutter。至于怎样排版、搜索、保存笔记,以及什么时候清空片段,仍由应用处理。扫描件如果需要识别文字,还要另外接入 OCR,不能只靠这个文本提取接口。
我把页面操作和调用关系画在图 1:选择讲义后,插件处理授权 URI,并调用系统 PDFKit 读取文字,应用再把分页结果和片段显示在平板上。

图1 讲义导入流程
1.2 检查上游与鸿蒙社区实现
我先检查了 pub.dev 发布页和 thevikke/read_pdf_text 上游仓库。主包发布版本是 0.3.1,采用 MIT 许可,平台标签为 Android、iOS。它提供全文、分页和页数三个读取接口:Android 使用 PdfBox,iOS 使用系统 PDFKit。鸿蒙也有名为 PDFKit 的系统能力,但需要单独实现原生调用,不能直接沿用 iOS 后端。

图2 上游源码仓库
接着,我检查了 oh-Flutter 和 CPF-Flutter。oh-flutter/read_pdf_text 已有鸿蒙实现,可以沿用原包和后端注册方式继续修改。CPF-Flutter 侧,我检索了 read_pdf_text、fluttertpc_read_pdf_text、flutter_read_pdf_text 三个名称,没有找到同名可用仓库;这次查库记录的范围就是这几个候选。

图3 社区适配仓库
图 3 是鸿蒙系统 Flutter 开源库社区维护的适配仓。首页 README 主要沿用上游的 Android、iOS 说明,我继续读了 README.OpenHarmony_CN.md、CHANGELOG.OpenHarmony.md 和原生源码,才确认鸿蒙端已经提供了文档选择器和可替换的解析后端。选库时,这几处说明需要对照着看。
| 来源 | 固定版本或分支 | 与本文有关的能力 |
|---|---|---|
| pub.dev 主包 | 0.3.1 | Android、iOS 的三项 PDF 读取接口 |
| oh-flutter 社区仓 | master 基线 | 增加选择器和后端注册表;默认通道提示后端缺失 |
| 社区发布标签 | 0.3.1-ohos-1.0.0-beta.2 | 与所测 master 不是同一个提交 |
| 修复复现分支 | fix/ohos-picker-uri-pdf-read | 补齐 URI 描述符转存、系统 PDFKit 后端与平板双栏 Example |
表1 版本职责区分
核对版本时还有一个细节:社区 master 和 beta.2 标签指向不同提交。我用 master 的固定快照构建原版对照包,完整提交映射保存在工程说明里。社区变更合入主分支前,第五章给出了包含缓存保留与清理异常处理的公开分支和固定提交,方便直接依赖与复现。
1.3 哪一项可以判定为 Bug
社区说明对 pickPdfFile() 的约定很明确:打开系统文档选择器,把选择结果复制进应用缓存,再返回可供读取的沙箱路径。我据此检查了下面这条正常使用路径:
- 启动原版插件构建的平板 Example,点击“从系统文件管理器导入 PDF”。
- 在“我的平板 → 个人 → 文档”中选中测试讲义,点击“打开”。
- 期待拿到非空沙箱路径,且对应文件与所选 PDF 内容一致。
选中文件并点击“打开”后,我得到的是 PICK_ERROR,消息里有 No such file or directory (13900002),缓存目录也没有成功生成 PDF。用同一环境取消选择时,插件能正常返回空值。问题因此落在选中文件后的复制过程:选择器已经完成了交互,插件却没能按约定返回可读路径。这里复现的是固定基线、所用系统和这份测试讲义的结果。
接下来遇到的 BACKEND_MISSING 要另作处理。原库把 PDFium 拆成可选子包,文档也说明了未注册后端时会返回这个错误。这是它原来的设计。我希望讲义页面只依赖主包就能读文字,于是增加系统 PDFKit 作为默认后端。这部分属于功能扩展,选择时还要考虑最低系统版本、文本解析差异,以及应用是否已经注册了其他后端。
二、功能对照与修订验证
2.1 环境、样本与证据分组
我给原版和修复版使用了同一份四页双语讲义,文件大小为 58,543 B。修复版读取后,全文长度为 1030,四个页标记全部命中。这里的长度来自 Dart 字符串,单位是代码单元;页标记用于核对这份样本的内容和页序,其他 PDF 的排版仍需单独检查。
- 框架为 Flutter 3.41.9+ohos-1.0.2,Dart 3.11.5;插件基于上游 0.3.1 与社区 master,修改后的代码按分支记录,没有新的版本 tag。
- 构建使用的工具是 DevEco Studio 26.0.0.865、HarmonyOS SDK API 26。
- 功能对照设备为 MatePad Pro 13 模拟器,横屏物理分辨率 2880 × 1920。模拟器镜像显示 HarmonyOS 7.0.0.107,设备系统参数为 OpenHarmony-7.0.0.105,两者分别记录。
- 原版包为 com.example.pgc24base,修复版包为 com.example.pgc24fix。下文的带外框画面、连续导入验证和收尾后日志均在同一台平板模拟器上采集。
2.2 选择文件后的实际变化
两个包都从平板桌面启动,选择同一份讲义并打开。原版在选择器返回后报错,修复版则显示了四页内容并支持加入页面片段。下面两段 GIF 均小于三十秒,录下了选文件、点击“打开”和返回页面的过程。

图4 原版导入实录

图5 修复后导入实录
选择器里能看到“应用仅可访问您选定的文件或文件夹”的提示。测试工程没有额外声明存储读写权限,读取依据来自用户这次选择。拿到授权后,插件才能打开对应文件;这个授权不包含公共目录里其他文件的访问权,应用自己拼出一个 URI 也不能代替用户选择。

图6 单文件选择
我在修复版页面里把第 1、2 页加入下方“页面片段栏”,结果如图 7。左侧信息卡显示返回路径带有独立的 UUID 文件名,四个页标记全部命中,缓存目录里 transient 残留为 0 个、picked 副本为 1 个。随后我再次打开选择器导入同一份讲义,页面切换到了新的 UUID 路径,旧片段自动清空为 0 条,缓存目录里两份 58,543 B 的 picked 副本同时保留;单独打开选择器直接取消时,插件返回空值,当前讲义不会被清空。

图7 双栏分页结果
2.3 日志能证明什么

图8 收尾日志对照
🔍 我按动作名逐条查看 HiLog:页数、全文、分页在每次验证里各调用一次,计时终点位于页面释放、文档释放和临时文件删除完成之后。
| 调用接口 | 首次导入副本 | 二次导入副本 | 授权 URI 直读 | 记录含义 |
|---|---|---|---|---|
getPDFlength | 154 ms | 4 ms | 5 ms | 一次页数查询与释放 |
getPDFtext | 20 ms | 22 ms | 16 ms | 一次全文提取与释放 |
getPDFtextPaginated | 16 ms | 16 ms | 13 ms | 一次分页提取与释放 |
表2 单次调用记录
首次导入的页数查询记录为 154 ms,其中包含文档加载和释放;日志没有单独量出系统 PDFKit 的初始化开销。授权 URI 直读一列还包含转存与删除临时文件的时间。由于各列只记录单次调用,没有控制文件系统缓存冷热或重复采样,这张表只用来核对收尾后的功能执行记录,不能拿来比较不同输入方式的速度。
三项 URI 直读调用结束后,缓存目录里 transient 临时文件数量保持为 0,先前两次选择器导入生成的两份 picked 副本仍原样保留。我还向提取接口传入了损坏文件头的样本,日志和页面都收到了预期的格式错误。至于系统 PDFKit 省去可选 PDFium 子包后安装包具体减少多少体积,我没有做同配置 HAP 对比,这里只记录依赖组成上的变化。
2.4 缓存与异常路径如何验证
检查缓存时,我发现了自己在初版补丁里引入的一个问题:每次新导入前,插件会删除所有旧 picked 文件。用连续两次导入核对这项策略,第二次调用会让第一次返回的路径失效;即使第二个 URI 打不开,第一份文件也已经被删了。如果页面还在读取上一份讲义,就会被这次导入打断。
我把删除旧副本的操作去掉,每次复制都使用独立的 UUID 文件名。成功导入的 picked 文件留给调用方,失败时只回滚当前文件;直接传 URI 解析时生成的 transient 副本,则在该次调用结束后清理。这样保留了旧路径,也会让缓存占用随导入次数增长,需要应用决定哪些副本已经不用了。文件位于缓存目录,长期保存仍要复制到应用自己的持久目录。
为了检查这些失败路径,我补了 14 项原生逻辑测试。测试读取实际 ArkTS 插件源码,转译后执行,再用替身对象模拟文件系统、选择器和 PDFKit 的返回值或异常。修改后 14 项全部通过;拿修改前的代码跑同一组测试,12 项失败、2 项通过,旧副本被删和清理错误被忽略的问题都能被检出。
| 验证层次 | 覆盖内容 | 结论范围 |
|---|---|---|
| 原生逻辑 14 项 | 重复导入;打开、复制、状态查询、关闭失败;空文件;加载失败;释放顺序及错误优先级 | 检查实现分支,系统对象为替身 |
| 插件测试 5 项 | Dart 通道、参数和自定义后端契约 | 不证明系统选择器已运行 |
| Example 测试 4 项 | 页面读取与失败状态、缓存读取失败显示未知、换文档清空片段 | 检查 Flutter 页面状态 |
| 平板模拟器与构建 | 两级 analyze、无签名 HAP 构建;选择器取消、连续导入、URI 直读与损坏文件头验证 | 覆盖功能闭环,不含底层句柄长时内存采样 |
表3 修订验证范围
替身测试主要检查清理顺序和错误返回:哪一步抛异常,外层还会不会继续收尾,最终交给 Dart 的又是哪一个错误。系统对象在单测里被模拟了,所以我又把修订包安装到平板模拟器核对了连续两次导入、URI 直读和取消选择的文件结果;至于 PDFKit 底层原生句柄的长期内存驻留,这次只验证了接口释放调用,没有单独做长时内存剖析。
三、原理与核心代码分析
3.1 先把 URI 交给支持它的接口
定位复制问题时,我把本机 SDK 中两个接口的参数说明放在一起看。copyFileSync 接受路径或文件描述符,openSync 则明确支持 URI。原版把选择器返回的 URI 直接交给复制接口,恰好在这里报了文件不存在。于是我先用支持 URI 的接口打开源文件,再把得到的描述符交给复制接口。

图9 接口与配置
具体修改分成四步:
- 把选择器返回的 URI 交给只读打开接口,使用得到的文件描述符复制内容。
- 校验复制结果非空,再把沙箱路径返回给 Dart;关闭失败时也不返回成功路径。
- 只回滚当前调用创建的文件,保留之前已经交给调用方的副本。
- 解析授权 URI 时使用独立临时文件,读取结束后再做文档释放和文件删除。
复制逻辑放在 ReadPdfTextPlugin.ets 中,完整函数如下。它调用的 openUriReadOnly 负责只读打开:本应用的 file:/// 路径保留百分号解码后的重试,外部 docs URI 按系统授权处理。清理操作统一交给 runCleanup,后面会说明它怎样保留原始错误。
private copyUriIntoCache(uri: string, prefix: string): string {
const cacheRoot = this.abilityContext?.cacheDir ?? this.appContext?.cacheDir;
if (cacheRoot == null || cacheRoot.length === 0) {
throw new PdfExtractError('GENERIC ERROR', 'Application cache directory is unavailable.');
}
const directory = `${cacheRoot}/${PICKED_DIR}`;
if (!fileIo.accessSync(directory)) {
fileIo.mkdirSync(directory);
}
// 每次导入独立命名,不覆盖其他调用或插件实例仍在使用的路径。
const target = `${directory}/${prefix}_${util.generateRandomUUID()}.pdf`;
let completed = false;
try {
const srcFile = this.openUriReadOnly(uri);
let copyFailed = false;
try {
fileIo.copyFileSync(srcFile.fd, target);
if (fileIo.statSync(target).size <= 0) {
throw new PdfExtractError('GENERIC ERROR', 'Copied PDF file is empty (0 bytes).');
}
} catch (error) {
copyFailed = true;
throw error as Error;
} finally {
this.runCleanup('source.close', () => fileIo.closeSync(srcFile), copyFailed);
}
completed = true;
return target;
} finally {
// 回滚只删除本次创建的文件,保留先前成功返回的导入副本。
if (!completed) {
this.runCleanup('copy.rollback', () => {
if (fileIo.accessSync(target)) fileIo.unlinkSync(target);
}, true);
}
}
}
这里有两个状态需要分清。复制或文件校验失败时,copyFailed 用来保留那个错误,关闭句柄即使再报错,也不能将它覆盖。completed 则要等复制、校验和关闭都结束才设为真;只要有一步没走完,外层就回滚当前目标文件。回滚本身失败也会留下清理阶段和错误码,不会继续处理其他副本。UUID 只用于减少并发或多个插件实例之间的重名,与 URI 授权无关。
3.2 PDFKit 后端与资源释放顺序
PDFKit 需要能访问的本地文件。调用方传入沙箱路径时,插件直接使用它;传入授权 URI 时,插件先复制出 transient 文件。resolveReadableSource 除了返回路径,还记录来源种类,以及这个副本是不是本次调用创建的。收尾时就看这个标记:临时副本由插件删除,调用方传来的源文件留在原处。
我让页数、全文和分页三个接口共用同一个异步文档读取函数,先通过 loadPdfService() 按需动态加载 @kit.PDFKit(这样在低于 API 23 或缺少该能力的运行时能温和抛出 BACKEND_MISSING,同时保留编译期类型安全),再把各自的提取动作作为回调传入。页数查询返回数量,全文提取拼接每页字符串,分页提取则保留列表。这样修改加载或清理行为时,只需检查这一处。下面是类里的完整函数;所需的 ResolvedPdfSource、loadPdfService、错误映射、清理函数和 Dart 门面都保存在配套工程中。
private async withPdfDocument<T>(
pathOrUri: string,
action: string,
extractor: (doc: PdfServiceNamespace.PdfDocument, pageCount: number) => T,
): Promise<T> {
const startMs = Date.now();
let source: ResolvedPdfSource | null = null;
let operationFailed = false;
let pageCount = 0;
try {
const pdfService: ESObject = await this.loadPdfService();
source = this.resolveReadableSource(pathOrUri);
const doc: PdfServiceNamespace.PdfDocument = new pdfService.PdfDocument();
let documentFailed = false;
try {
const parseResult = doc.loadDocument(source.localPath, '');
if (parseResult !== pdfService.ParseResult.PARSE_SUCCESS) {
throw this.mapParseResultError(pdfService, parseResult);
}
pageCount = Math.max(0, doc.getPageCount());
return extractor(doc, pageCount);
} catch (error) {
documentFailed = true;
throw error as Error;
} finally {
// 加载失败也尝试收尾;清理错误不能覆盖原来的解析错误。
this.runCleanup('document.release', () => doc.releaseDocument(), documentFailed);
}
} catch (error) {
operationFailed = true;
throw error as Error;
} finally {
if (source != null && source.isTransientCopy) {
const temporaryPath = source.localPath;
// 临时副本删除失败仅记日志,不再覆盖已经成功提取并释放句柄的结果。
this.runCleanup('transient.unlink', () => fileIo.unlinkSync(temporaryPath), true);
}
// 计时到文档释放和临时文件删除结束;主流程或原生释放失败时不会记录成功。
if (!operationFailed && source != null) {
hilog.info(LOG_DOMAIN, LOG_TAG,
'%{public}s ok: sourceKind=%{public}s pages=%{public}d transient=%{public}s elapsedMs=%{public}d',
action, source.sourceKind, pageCount, String(source.isTransientCopy), Date.now() - startMs);
}
}
}
每页的读取还有一层 finally,用来调用 page.release()。如果连页面对象都没拿到,插件会回传错误,不再用空字符串代替;正常取得页面却没有文字,才属于空文本结果。释放顺序是先页面、再文档、最后临时文件。即便 loadDocument 返回失败,已经创建的文档实例也要尝试释放,收尾不能只放在成功分支里。
几层 finally 各管一段资源。页面释放抛异常后,外层仍会尝试释放文档、删除临时文件;读取本身已经失败时,则保留原来的读取错误,把后续清理错误另记到日志。这样排查时能看到最先出问题的位置,也能知道收尾有没有继续失败。
3.3 让清理失败真正可见
初版在释放代码外包了一层 catch (_) {}。异常一旦被忽略,页面还会收到成功结果,我也就无从知道收尾出了问题。于是把这些位置改成调用同一个辅助函数:
private runCleanup(stage: string, operation: () => void, preservePrimaryError: boolean): void {
try {
operation();
} catch (error) {
const failure = error as BusinessError;
const code = String(failure.code ?? 'UNKNOWN');
// 系统错误可能包含原始路径;日志仅记录清理阶段与错误码。
hilog.error(LOG_DOMAIN, LOG_TAG, 'cleanup failed: stage=%{public}s code=%{public}s', stage, code);
if (!preservePrimaryError) {
throw new PdfExtractError('CLEANUP_ERROR', `PDF cleanup failed at ${stage} (${code}).`);
}
}
}
如果前面的读取已经成功,页面或文档原生句柄释放却失败了,辅助函数就回传 CLEANUP_ERROR;而读取与句柄释放都完成后删除 transient 临时副本这一步,我选择在日志中补上清理阶段和系统错误码而不丢弃已经读出的文档文本。如果前面已经有解析或复制错误,则保留原始错误,同样只在日志里记下清理阶段和错误码。系统异常可能带着原始文件路径,我没有把它整段写进清理日志。这里也没有自动重试;调用方能凭明确的句柄清理错误或日志记录来决定后续处理。
页面里的缓存统计也有类似问题。我把两个计数的更新放到目录遍历成功之后;读取目录失败时,显示“未知”和“读取失败”,不用默认的零填上去。界面分别列出 picked 和 transient 数量,前者是留给调用方的导入副本,后者才是单次解析用完应清理的临时文件。查看结果时,要先分清数的是哪一种。
3.4 保留公开接口与自定义后端
Dart 层保留原包导入、四个静态方法和 read_pdf_text 通道名。三项提取方法先检查 PdfTextBackendRegistry:应用注册了自定义后端,就交给它;没有注册,才通过 MethodChannel 调用系统 PDFKit。选择器始终走平台通道,切换解析后端不会改变它。
我保留这个优先级,是考虑到已有应用可能正在使用 PDFium,依赖它对某些字体或文档的处理。换成系统默认后端后,阅读顺序、换行和异常文档的结果都有可能不同。我目前用四个标记核对了固定样本,没有比较两种引擎对其他文档的输出。已有文档库的应用,最好先用自己的代表性样本读一遍,再决定是否切换。
四、踩坑与边界条件
4.1 构建通过与系统可用是两道检查
写异常处理时,还要留意 ArkTS 对抛出类型的限制。普通 TypeScript 里直接重抛 catch 参数的写法,在当前编译器下可能触发 arkts-limited-throw。插件主动构造的错误使用 Error 子类,重抛也按工程既有写法显式转为 Error。原生逻辑测试只执行转译后的代码,因此我在测试通过后又运行了无签名 HAP 构建,检查实际 ArkTS 编译结果。
我检查 SDK 声明时看到,文本提取用到的 PdfPage.getTextContent() 自 API 23 起提供。不过,这份工程的构建和运行对照都使用 API 26,API 23 到 API 25 还没有做兼容测试。它直接依赖 HarmonyOS SDK 的 PDFKit;其他 OpenHarmony 发行版是否提供相应能力,也需要按目标环境核对。
4.2 授权 URI 与缓存路径都不是永久入口
应用保存 URI 时,要把文件标识和访问授权分开考虑。字符串还在,不代表重启或授权变化后仍能打开原文件。需要保留讲义时,可以趁授权有效保存提取出的文本,或把文件复制到自己的持久目录,后续读取再检查文件是否存在、是否可读。如果业务需要长期跟踪外部原文件,则要另外核对持久访问能力,这条链路我还没有实现和验证。
缓存副本也需要应用安排使用期限。一次导入结束后,页面可能还会再次读取 picked 文件,所以插件把它留给调用方;用 URI 解析时生成的 transient 文件只服务于这一次调用,结束后就清理。应用要限制磁盘占用,可以等某份 picked 副本不再使用时删除它。由于它仍在缓存目录里,也要处理系统回收后文件不存在的情况。
4.3 文本提取的范围
我按 SDK 的解析结果保留了文件不可读、格式错误、密码错误和证书相关错误等标识,方便页面给出对应提示。模拟器实测中,我传入损坏头部的样本,实际收到了 PARSE_ERROR_FORMAT: 2;密码和证书场景目前只核对了错误映射,还没有用对应样本跑过。
现有公开接口没有密码参数,插件加载时传入空密码,遇到受保护的文档就把错误交给页面。空文本则要另外看:页面可能只有图片,也可能与字体编码或内容有关。PDFKit 不负责 OCR,提取顺序也未必等同于视觉排版顺序。处理双栏讲义时,我会重点核对读出来的段落有没有串列,而不是只看返回字符串是否为空。
getPDFtextPaginated 会一次读取全部页面。页面虽然可以用 ListView.builder 减少同时构建的组件,但插件已经提取出的文本仍会保留在结果里。当前原生读取是同步调用,我没有专门测过大文档的响应时间和线程影响。这里跑通的是四页讲义;如果要用来读几百页教材,还需要用那个量级的文件检查等待时间和内存占用。
五、结论与可直接复用的建议
回到讲义页面,修复后的插件让系统选择器选中的 PDF 能够通过文件描述符复制进应用缓存,再由系统 PDFKit 提取为分页文本,同时保留已返回的导入副本并显式上报收尾异常。如果你的应用同样需要在鸿蒙上导入本地 PDF 并按页读取文字,在社区变更合入主分支前,可以先固定下面这个公开提交继续使用 read_pdf_text 的接口:
dependencies:
read_pdf_text:
git:
url: https://atomgit.com/abaoge/read_pdf_text.git
ref: ef7760424c26a1557f2519656e8e4f7d0fd1823d
接入时建议留意三点边界:一是社区当前 master 快照与 pub.dev 0.3.1 还不包含这套 URI 转存和系统 PDFKit 默认后端,依赖时不要只凭版本号互换;二是 pickPdfFile() 成功返回的路径位于缓存子目录 picked_pdf 下,插件不会在下一次导入时自动删除旧副本,不再使用的临时副本建议由应用主动清理,长期保存的内容应复制到持久目录;三是若主读取已完成但页面或文档原生句柄释放失败,插件会返回 CLEANUP_ERROR(临时副本删除失败仅记日志不覆盖已读文本),已注册自定义 PdfTextBackendRegistry 后端的应用则继续优先走自定义后端。
在宿主工程里配置所用的 tablet 设备类型,横竖屏显示则由方向配置和页面布局共同处理。测试工程没有为这条选择器流程额外声明存储读写权限,实际环境是 API 26。调用时,我会把选文件和读文本一起放进异常处理,避免只处理解析失败,却漏掉选择阶段的错误:
import 'package:flutter/services.dart';
import 'package:read_pdf_text/read_pdf_text.dart';
Future<List<String>?> pickAndReadLecturePages() async {
try {
final String? path = await ReadPdfText.pickPdfFile();
if (path == null) {
// 取消不改变当前文档,也不显示失败提示。
return null;
}
return await ReadPdfText.getPDFtextPaginated(path);
} on PlatformException catch (error) {
final String message = error.message ?? '';
if (message.contains('PARSE_ERROR_PASSWORD')) {
throw StateError('该 PDF 受密码保护,请先解除口令。');
}
if (message.contains('PARSE_ERROR_FORMAT')) {
throw StateError('PDF 格式无效或文件已损坏。');
}
rethrow; // 保留选择、权限和其他系统错误,交给页面统一提示。
}
}
页面调用这个函数前,先禁用导入按钮,完成或失败后再恢复。返回空值表示用户取消,可以保留当前文档;真正读取失败时应显示错误,并清掉上一份讲义的片段。宿主如果已经取得有效授权 URI,也可以直接交给分页接口,但要自行管理授权来源和有效期。需要长期阅读的内容,保存为文本或应用自己的持久副本更合适。
公开 Example可以查看同款平板双栏页面,Example 运行说明提供对应构建步骤。鸿蒙环境请看这份说明,上游通用 README 主要介绍 Android 和 iOS。我这次没有运行 Android、iOS、其他设备形态或远程云盘文件的测试。
小结
从文件管理器选中讲义后,平板页面终于能按页显示文字、保存片段。继续查缓存时,我也重新考虑了返回路径的含义:既然已经交给调用方,就得留给它使用,不能在下一次导入时顺手删掉。以后再处理这类返回文件路径的接口,我会把副本的使用期限和读取结果一起检查。
5



被折叠的 条评论
为什么被折叠?



