HarmonyOS 7.0新API实战：沉浸光感、压缩解压与锁屏通知适配

鸿蒙专家

版本背景

HarmonyOS 7.0 已于 2026 年 9 月 7 日正式发布，在 HarmonyOS 6.1 基础上增强了若干特性。这一版与开发者关系最直接的变化集中在十项 API 上，涉及 ArkUI、文件基础服务、基础视觉服务、图像服务、媒体服务、地图服务、通知服务、扫码服务以及后台任务开发服务。下面按能力域梳理这些变化的具体用法、引入原因与适配验证思路，方便已经在 HarmonyOS 6.x 上完成开发的应用平滑升级。

一、ArkUI：组件级沉浸光感

ArkUI（方舟 UI 框架）新增组件级沉浸光感，把光影材质与交互动效结合，提供从“视觉层”到“感知层”的体验，让菜单、对话框这类弹窗组件在不同设备上保持一致的层次感。例如菜单展开时形变弹出，边缘流光勾勒面板轮廓。

引入该特性的原因在于：弹窗类组件原本多使用默认白色背景，弹出后会直接覆盖屏幕部分区域。开启沉浸光感后，材质滤镜、折射、高光、阴影多层叠加，底层内容可以透过材质层自然渗透，视觉表现明显优于纯色背景。

适配方式是在模块的 module.json5 中增加元数据配置，将 metadata 的 name 字段设为 ohos.arkui.UIMaterial.state，value 设为 enable：

2. "metadata": [{
3.     "name": "ohos.arkui.UIMaterial.state",
4.     "value": "enable"
5. }]

复制代码

配置后运行应用，观察弹窗类组件是否呈现沉浸材质的半透明效果。

二、Background Tasks Kit：倒计时提醒支持重复

后台代理提醒 reminderAgentManager 的倒计时实例对象 ReminderRequestTimer 新增两个参数：repeatInterval 表示重复周期，单位秒，无默认值，未赋值即无重复周期，需与 repeatCount 一起使用；repeatCount 表示重复次数，默认值 0，表示无限次重复，同样需与 repeatInterval 配合。

原实现只提供倒计时秒数，一次倒计时结束发一次提醒就不再触发。新增这两个参数后，既能设定倒计时次数，也能设定在多长周期内重复，后台代理提醒可用于更多循环提醒场景。适配时在原有倒计时请求上追加这两个参数，验证重复提醒机制是否符合预期。

三、Core File Kit：递归列目录与 C/C++ 压缩解压

文件基础服务这一版有两处更新。

第一处是 fileIo 模块新增 listFileExt 与 listFileExtSync，支持列出指定目录下所有文件名，并可通过 options 中的 recursion 参数递归列出所有文件的相对路径。原有 listFile 与 listFileSync 只能通过 Filter 类型定义固定的过滤配置项，新方法使用 FileFilter 类型，在文件名过滤上更灵活。适配时可同时调用新旧方法对比过滤效果。

第二处是新增压缩解压缩模块，面向 C/C++ 提供文件归档类能力，适用于把多个文件和目录打包成归档文件、或从归档文件提取文件到指定目录，可用于文件打包分发、减少存储占用、加速网络传输。Basic Services Kit 原有的 ArkTS @ohos.zlib（Zip 模块）依赖 zlib 全套底层能力，在高性能场景下压缩解压速度偏慢，这是引入 C/C++ 接口的主要原因。

压缩归档的基本调用顺序是：先调用 OH_Archive_Writer_OpenFile 创建归档写入器，再调用 OH_Archive_Writer_Add 向归档中添加文件或目录（支持一次添加多个），最后调用 OH_Archive_Writer_Close 完成写入并释放资源。解压侧对应 OH_Archive_Reader_OpenFile、OH_Archive_Reader_ExtractAllFile、OH_Archive_Reader_Close。在 NDK 开发中按此流程处理应用沙箱目录内的文件，可验证归档结果是否正确。

四、Core Vision Kit：用文本语义搜图片

基础视觉服务新增 textSearchImage，提供基于文本语义的图片检索能力。用户输入文本语义后，可从图片库中搜索匹配的图像结果，适用于图片检索、相册管理、内容推荐等场景。此前应用只能“文本搜文本”，现在返回结果中包含图片沙箱路径、作用域和相似度信息，便于快速定位符合条件的图片文件。

使用时先导入模块：

2. import { textSearchImage } from '@kit.CoreVisionKit';

复制代码

调用流程为：在 aboutToAppear 中调用 textSearchImage.init() 初始化分析器服务；调用 textSearchImage.insertImage 将图片特征插入数据库；调用 textSearchImage.search 获取匹配结果；调用 textSearchImage.deleteImage 从数据库删除指定图片数据；在 aboutToDisappear 中调用 textSearchImage.release() 释放资源。可将其与原有 photoAccessHelper 手工选图的实现做对照验证。

五、Image Kit：五类图像元数据对象

image 模块新增 GifMetadata、JfifMetadata、TiffMetadata、PngMetadata、AvisMetadata，分别对应 GIF、JFIF、TIFF、PNG、AVIS 格式的图像元数据，用于存储元数据并支撑后续图像修改操作。

该模块在 HarmonyOS 6.1 起支持 Heif 格式元数据，6.1.1 起支持 WebP 格式元数据，本次继续补齐上述五种格式，目的就是覆盖更多图像处理场景。适配时分别调用 image.GifMetadata、image.JfifMetadata、image.TiffMetadata、image.PngMetadata、image.AvisMetadata 的 createInstance 方法创建元数据对象，再验证能否正常读写对应格式图像。

六、Media Kit：播放器关联广告控制器

media 模块新增 createAVAdsController，用于创建与播放器实例关联的广告播放控制器 AVAdsController，并可通过以下方法管理广告资源：addAdsMediaSource 添加广告媒体源并指定其在主媒体播放进度中的插入位置；removeAdsMediaSource 移除指定广告源，若广告正在播放则等播放完成后移除；skipCurrentAdsMediaSource 跳过当前正在播放的广告；disableAllAdsMediaSource 禁用当前会话中剩余广告；release 释放控制器对象。

原来 createAVPlayer 创建的音视频播放器只能播放指定内容，无法管理片头片尾广告资源。新增控制器后，可以为音视频内容定制广告媒体源，适配时重点验证广告画面能否正常播放与跳过。

七、Map Kit：折线支持添加文字

地图服务新增折线文字能力：新建折线后可调用 MapPolyline 的 addLineText 方法为折线添加文字，通过 removeLineText 删除折线文字。此前用 MapComponentController 的 addPolyline 只能添加折线，无法标注线条含义，导致每段折线表达不明确。适配时先调用 addPolyline 获得折线实例，再调用实例的 addLineText 添加线条文本，确认地图上是否正确显示。

八、Notification Kit：读取通知开关状态

notificationManager 模块的 NotificationSetting 类型新增四个字段：lockScreenEnabled 表示是否开启锁屏通知，bannerEnabled 表示是否开启横幅通知，badgeNumberEnabled 表示是否开启通知角标数字展示，notificationEnabled 表示应用通知使能状态。

此前锁屏通知、横幅通知由用户到系统设置菜单中操作，应用无法感知用户关掉了哪些能力。现在调用 getNotificationSetting 即可获取应用通知设置，包括锁屏通知、横幅通知、桌面角标、振动、铃声等开关状态，推送策略可以据此更有针对性。

九、Scan Kit：查询设备扫码能力支持情况

scanCore 模块新增 isDefaultScanSupported 与 isCustomScanSupported，分别用于查询当前设备是否支持默认界面扫码、是否支持自定义界面扫码。

Scan Kit 原先默认所有设备都支持这两种扫码方式，但随着鸿蒙系统覆盖设备范围扩大，可能存在少数设备不支持默认界面扫码或不支持自定义界面扫码的情况。提前查询设备支持情况后，应用可以在扫码入口处做差异化处理。适配时在调用扫码前先执行这两个查询方法，确认返回值与实际设备能力一致。

小结

整体来看，HarmonyOS 7.0 这十项 API 升级有两条主线：一条是体验与性能，比如 ArkUI 沉浸光感、C/C++ 压缩解压、Media Kit 广告插播；另一条是能力可控性，比如文件递归过滤、文本搜图、折线文字、通知开关读取、扫码能力查询、倒计时重复提醒。已经运行在 HarmonyOS 6.x 上的应用，可以按上述顺序逐项对照 module.json5、fileIo、image、media、map、notificationManager、scanCore 与 reminderAgentManager 的现有实现，先小范围验证接口行为，再决定是否全量启用。