鸿蒙7.0 Preview Kit 文件预扫描C API接入与避坑

鸿蒙专家

背景：文件预览的瓶颈从渲染转向IO与解码

在大型企业级文档管理或协同办公场景中，用户经常要预览数百 MB 的超大 PDF、高清工程图纸或海量数据表格。传统处理链路是：点击列表项 -> 路由跳转 -> 加载动画 -> IO 线程读文件 -> 内存分配与解码 -> 渲染上屏。这条链路会让用户点击后面对 1 到 3 秒白屏或加载圈。业务优化深入后，单纯压缩主线程渲染耗时已经见顶，真正瓶颈在底层磁盘 IO 寻址与重度解码没有前置。

HarmonyOS 7.0（API 26）中，系统通过 Preview Kit 引入基于 C API 的文件加速前置扫描机制 openfileboost_preview。它提供 File Open Boost（文件打开加速）和与应用状态深度绑定的 QueryAppState 查询回馈机制。团队在版本迭代中将这套 C 层加速机制接入内部文档中台模块，在列表页静默预读与缓存解码后，头部重度文档的二次打开耗时从平均 1200ms 锐减到 150ms 左右。

为什么用 C API：内存模型与 IO 调度

如果完全在 ArkTS 虚拟机堆内存中做文件预读和缓存，容易引发频繁 GC 停顿；向底层文件系统发起 mmap 或 read 系统调用时，也会产生多余的跨层拷贝。Preview Kit 的核心头文件 open_file_boost.h 和 file_cache_boost.h 提供了一套贴近内核层的回调模型，这也是 API 26 选择用 C API 承接文件预览加速的原因。

这套机制主要围绕两个回调展开：

1. HMS_OpenFileBoost_QueryAppState：系统探测器。当系统后台监控到可能出现文件预览意图时，会调用此接口向应用查询是否允许预加载。应用需要结合前后台状态、内存水位以及电量模式，返回可用性评估。

2. HMS_OpenFileBoost_OnFilePreload：动作执行器。当 QueryAppState 准许执行后，此回调会被系统底层线程池拉起，携带一组推荐预加载的 URI 或文件路径列表。应用在这里承接路径，调用 file_cache_boost 相关 API，将解码后的文件头或关键数据置入系统缓存。

双栈工程结构：C 层预读，ArkTS 管状态

示例工程按职责做了双栈划分：C 层负责高并发预读回调与零拷贝缓存，ArkTS 层负责列表状态机分发。典型目录包括 entry/src/main/cpp 下的 CMakeLists.txt、file_boost_manager.h、file_boost_manager.cpp、file_boost_napi.cpp；ArkTS 侧则包括 DocumentList.ets、BoostNativeAgent.ets、EntryAbility.ets 和 module.json5。

在 C/C++ 侧使用 Preview Kit，需要在 CMakeLists.txt 中链接 Preview Kit、NAPI 和日志相关系统动态库：

2. target_link_libraries(fileboost_jni PUBLIC libace_napi.z.so libpreview_kit.z.so libhilog_ndk.z.so)

复制代码

核心 C API 回调：状态查询与预加载落地

在 file_boost_manager.cpp 中，需要维护供 QueryAppState 评估的全局状态，例如 g_isAppInForeground 和 g_isMemoryCritical。OnQueryAppState 的决策会直接影响系统 IO 调度带宽分配：内存极度紧张时返回 OPEN_FILE_BOOST_STATE_REJECT，防止 OOM；应用退到后台且业务不需要后台预热时返回 OPEN_FILE_BOOST_STATE_PAUSE；前台且资源允许时返回 OPEN_FILE_BOOST_STATE_ACCEPT。

OnFilePreloadTriggered 会拿到 fileList、count 和 OpenFileBoost_PreloadType。当类型为 OPEN_FILE_BOOST_TYPE_CACHE 时，可构造 CacheBoost_Options，并将 cachePolicy 设置为 CACHE_BOOST_POLICY_MEMORY_PRIORITY，然后调用 HMS_FileCacheBoost_SubmitTask 发起异步缓存任务。这里不要在系统派发的调度线程里同步执行重度解码，否则容易阻塞底层线程池。

完成初始化时，构造 OpenFileBoost_CallbackConfig，把 queryAppStateCallback 指向 OnQueryAppState，把 onFilePreloadCallback 指向 OnFilePreloadTriggered，再调用 HMS_OpenFileBoost_RegisterCallback 向系统内核层注册预读监听机制。另需提供 UpdateAppState，用于从 ArkTS 同步前台状态和内存危机状态。

NAPI 桥接与 ArkTS 生命周期接入

为了让业务侧在合适时机初始化引擎并同步状态，file_boost_napi.cpp 中可封装两个 NAPI 方法：initBoostEngine 调用 FileBoostManager::InitOpenFileBoost；syncAppState 读取两个 bool 参数，分别表示是否前台、是否内存危机，再调用 UpdateAppState。最后通过 napi_define_properties 暴露方法，并用模块名 fileboost_jni 注册。

ArkTS 侧在 EntryAbility.ets 中导入 libfileboost_jni.so。onCreate 冷启动阶段尽早调用 fileBoostNative.initBoostEngine()；onForeground 调用 fileBoostNative.syncAppState(true, false)；onBackground 调用 fileBoostNative.syncAppState(false, false)，暂停非必要的重度 IO 预热。实际工程中，内存危机状态应结合 onMemoryLevel 监听同步到底层。

避坑一：预加载队列的并发风暴

HMS_OpenFileBoost_OnFilePreload 回调由系统后台线程并发触发。列表很长且用户快速抛滑时，系统可能在极短时间内传入数百个文件 URI。如果直接在回调内同步执行重量级解码，底层 C++ 线程池会被迅速打满，甚至引发线程死锁或卡死。

解法是收到 URI 数组后不要以阻塞形式解析文件，必须调用 HMS_FileCacheBoost_SubmitTask 的异步模式，或自己实现 Token Bucket 令牌桶限流，严格控制同一时刻并发映射的句柄数量。

避坑二：文件描述符耗尽风险

前置预扫描意味着文件会在真正展示前就被打开。如果在 OnFilePreload 阶段通过常规 POSIX API open 获取大量文件句柄做自研解析，却在业务主动放弃预览时没有显式 close，容易触达单进程 1024 或 4096 的 FD 上限，出现 Too many open files。

防范原则是强依赖 preview_kit 提供的系统级缓存托管接口，避免自造轮子强占 FD。对于必不可少的自建预读任务，要构建完善的销毁监听，在收到 OPEN_FILE_BOOST_STATE_PAUSE 或业务销毁信令时，立即批量释放未命中视图的句柄资源。

避坑三：内存预警时的断腕机制

接入加速 API 时，不能为了极速在 HMS_OpenFileBoost_QueryAppState 中无脑返回 OPEN_FILE_BOOST_STATE_ACCEPT。低配机型上，这相当于在紧张的内存池里继续强注数据，容易引发系统级 OOM 并导致进程被内核终结。必须严格监听 ApplicationContext 提供的 onMemoryLevel 接口，一旦达到 MEMORY_LEVEL_CRITICAL，立刻在 C 层阻断新的预读请求，并上报清理现有缓存的信令。

总结

HarmonyOS 7.0 引入的 Preview Kit C API open_file_boost，本质上是把应用层传统的拉取式按需加载，转变为由内核智能预测驱动的推送式流式处理。QueryAppState 让系统尊重业务主观状态；OnFilePreload 结合 file_cache_boost，让系统接管沉重的跨层通信与存储寻址负担。把解码与读取任务向 C 层和系统预测池下沉，是企业级应用打破性能天花板的一条可行路径，也为后续更复杂的重载场景提供了底层样板。

热心网友6

这个分享挺实在的，双栈划分很清楚，C 层做预读和零拷贝缓存、ArkTS 管列表状态机，确实比全堆在 ArkTS 里反复预读更容易避开 GC 和跨层拷贝。QueryAppState 按前台、内存水位和电量模式返回 ACCEPT、PAUSE、REJECT 这点很关键，感觉能直接影响系统给多少 IO 带宽。避坑一的并发风暴也说到点子上了，快速抛滑时几百个 URI 一起来，如果回调里同步解码基本会把底层线程池打满。后面如果继续写，比较想看 SubmitTask 异步模式具体怎么限制并发、怎么做任务取消或优先级丢弃，以及 CACHE_BOOST_POLICY_MEMORY_PRIORITY 在高内存压力下要不要配合 onMemoryLevel 及时降级。感谢经验分享，期待后续。

热心网友2

感谢分享，内容很干货。把文件预览瓶颈从渲染转到 IO 和解码前置这点很认同，单纯压主线程渲染确实容易到天花板。C 层双回调的分工也讲得清楚：QueryAppState 做准入判断，OnFilePreload 承接系统线程池派发的预读任务，ArkTS 侧只负责生命周期和状态同步，这种双栈结构比全塞进 ArkTS 堆里稳很多。避坑一很关键，系统并发回调时如果同步做重度解码，底层线程池很快会被打满，用 HMS_FileCacheBoost_SubmitTask 异步提交是正路，同时结合前台、内存水位返回 ACCEPT、PAUSE、REJECT 来削峰。想请教下，UpdateAppState 里内存危机状态从 onMemoryLevel 同步过来时，你们是怎么划分等级的？另外期待避坑一后续关于并发队列控制的补充。

热心网友6

感谢楼主分享，内容很干。把预览慢的根因定位到磁盘 IO 和重解码前置，而不是只盯主线程渲染，这点很有启发。双栈划分也合理，C 层扛高并发预读和零拷贝缓存，ArkTS 只做状态分发，能避开 ArkTS 堆里频繁 GC 的麻烦。 关于 QueryAppState 的 ACCEPT、PAUSE、REJECT 三种返回，我觉得关键是别只按前后台判断，还要把内存水位和电量模式一起纳入，否则容易在后台把 IO 带宽抢太多。避坑一里说的并发风暴确实很实在，系统线程池回调里一旦同步做重解码，很容易把线程池打满甚至卡死。用 HMS_FileCacheBoost_SubmitTask 异步提交，并设置 CACHE_BOOST_POLICY_MEMORY_PRIORITY，这个思路比较稳妥。 想请教一下，OnFilePreload 拿到几百个 URI 时，你们会做去重或优先级排序吗，还是完全依赖系统给的 fileList 顺序？另外 UpdateAppState 从 ArkTS 同步时，内存危机状态用 onMemoryLevel 的哪一级作为切换阈值比较合适？