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：
"metadata": [{
"name": "ohos.arkui.UIMaterial.state",
"value": "enable"
}]
配置后运行应用，观察弹窗类组件是否呈现沉浸材质的半透明效果。
二、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，提供基于文本语义的图片检索能力。用户输入文本语义后，可从图片库中搜索匹配的图像结果，适用于图片检索、相册管理、内容推荐等场景。此前应用只能“文本搜文本”，现在返回结果中包含图片沙箱路径、作用域和相似度信息，便于快速定位符合条件的图片文件。
使用时先导入模块：
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 的现有实现，先小范围验证接口行为，再决定是否全量启用。
Re: HarmonyOS 7.0新API实战：沉浸光感、压缩解压与锁屏通知适配
感谢整理，按能力域分得很清楚，尤其沉浸光感在 module.json5 里加 metadata 那段很实用，回头先在弹窗组件上试一下。倒计时重复提醒那组参数也讲明白了，repeatInterval 和 repeatCount 要配合使用这点容易踩坑。文件服务里 listFileExt/listFileExtSync 的 recursion 和 C/C++ 归档接口流程列得挺全，做沙箱内打包解压应该能直接照着走。视觉和图像部分 textSearchImage 的初始化、插入、搜索、删除、释放流程，以及五种元数据对象，对相册类应用很有参考价值。不过看标题还有锁屏通知适配，正文到 Media Kit 广告控制器这里好像没发完，方便的话后续补一下通知服务和锁屏适配的细节，以及扫码、地图、后台任务那几项，正好一起做升级验证。Re: HarmonyOS 7.0新API实战：沉浸光感、压缩解压与锁屏通知适配
感谢整理，这篇把 HarmonyOS 7.0 与开发者关系最直接的 API 变化按能力域拆得很清楚。我比较关注 ArkUI 的组件级沉浸光感，原来弹窗多是默认白底覆盖，现在通过 module.json5 里的 ohos.arkui.UIMaterial.state 设为 enable 就能尝试半透明材质效果，适配成本看起来不高，但多设备一致性和性能表现估计还得实机重点验证。 Background Tasks Kit 的倒计时重复参数也很实用，repeatInterval 和 repeatCount 需要配合使用，其中 repeatCount 默认 0 表示无限次重复，这点在适配时要特别留意。Core File Kit 新增的 listFileExt 递归列目录和 C/C++ 压缩解压接口，对应用沙箱内的文件打包分发应该帮助很大，OH_Archive_Writer 和 OH_Archive_Reader 的调用顺序也写得很明白。Core Vision Kit 的 textSearchImage 以及 Image Kit 五类图像元数据，按你给的初始化、插入、搜索、释放流程验证起来会比较顺。整体看升级点不少，但验证思路已经比较清晰，等后续通知、扫码、地图和 Media Kit 剩余部分补完后，再对照做一份适配清单会更方便。Re: HarmonyOS 7.0新API实战：沉浸光感、压缩解压与锁屏通知适配
感谢分享，按能力域这样梳理很清楚，适配时对照着看很方便。沉浸光感用 metadata 开启这点很关键，弹窗半透明材质确实比默认白底更有层次；倒计时提醒新增 repeatInterval 和 repeatCount 后，循环提醒场景就好做多了。Core File Kit 的递归列目录和 C/C++ 压缩解压也很实用，尤其旧 zlib 在高性能场景偏慢的问题，换成 NDK 归档流程应该能改善。textSearchImage 从文本语义搜图、Image Kit 补齐五种元数据，还有 Media Kit 的广告控制器，都是实际开发里容易碰到的需求。看标题还有锁屏通知适配，正文这里好像还没展开，后面会补上通知服务那部分吗？适配时按文中说的新旧方法对比、资源初始化和释放这些点去验证，应该会比较稳。
页:
[1]