HarmonyOS鸿蒙Next中应用能否在锁屏界面显示自定义通知小部件
HarmonyOS鸿蒙Next中应用能否在锁屏界面显示自定义通知小部件 音乐 App 希望在锁屏上显示播放/暂停按钮,类似 iOS 或 Android 的媒体通知。
开发者你好,当前播控中心可实现在锁屏上显示播放/暂停按钮,参考播控中心-系统特性-系统特性&能力,当前系统播控中心是有锁屏时的播控中心播控,点击可以展示锁屏状态的播控大卡片,可以在锁屏上显示播放/暂停按钮,看下是否能够满足你的需求。
如果您不想接入播控,仅做一个通知卡片去暂停/播放的话,请您再反馈下。
更多关于HarmonyOS鸿蒙Next中应用能否在锁屏界面显示自定义通知小部件的实战系列教程也可以访问 https://www.itying.com/category-93-b0.html
背景知识:
可以按照 应用接入AVSession场景介绍 流程来接入:
- 确定应用需要创建的会话类型,创建对应的会话,不同类型决定了播控中心展示的控制模板样式。
- 按需创建后台任务。
- 设置必要的元数据(Metadata),以在播控中心展示相应的信息,包括不限于:当前媒体的ID(assetId),上一首媒体的ID(previousAssetId),下一首媒体的ID(nextAssetId),标题(title),专辑作者(author),专辑名称(album),词作者(writer),媒体时长(duration)等属性。
- 设置播放相关的状态,包括不限于:当前媒体的播放状态(state)、播放位置(position)、播放倍速(speed)、缓冲时间(bufferedTime)、循环模式(loopMode)、是否收藏(isFavorite)、正在播放的媒体Id(activeItemId)、自定义媒体数据(extras)等属性。
- 按需注册不同的控制命令,包括不限于:播放/暂停、上下一首、快进快退、收藏、循环模式、进度条。
- 应用退出或者无对应业务时,注销会话。
问题解决:
示例代码: 1、创建不同类型的会话
import { avSession as AVSessionManager } from '@kit.AVSessionKit';
@Entry
@Component
struct Index {
@State message: string = 'hello world';
build() {
Column() {
Text(this.message)
.onClick(async () => {
// 开始创建并激活媒体会话。
// 创建session。
let context = this.getUIContext().getHostContext() as Context;
let type: AVSessionManager.AVSessionType = 'audio';
let session = await AVSessionManager.createAVSession(context, 'SESSION_NAME', type);
// 激活接口要在元数据、控制命令注册完成之后再执行。
await session.activate();
console.info(`session create done : sessionId : ${session.sessionId}`);
})
}
.width('100%')
.height('100%')
}
}
2、创建后台任务
当应用需要实现后台播放等功能时,需要使用BackgroundTasks Kit(后台任务管理)的能力,申请对应的长时任务,避免进入挂起(Suspend)状态。
对媒体类播放来说,需要申请AUDIO_PLAYBACK BackgroundMode的长时任务。
3、设置元数据
应用可以通过setAVMetadata把会话的一些元数据信息设置给系统,从而在播控中心界面进行展示,包括不限制:当前媒体的ID(assetId),上一首媒体的ID(previousAssetId),下一首媒体的ID(nextAssetId),标题(title),专辑作者(author),专辑名称(album),词作者(writer),媒体时长(duration)等。
import { avSession as AVSessionManager } from '@kit.AVSessionKit';
import { BusinessError } from '@kit.BasicServicesKit';
@Entry
@Component
struct Index {
@State message: string = 'hello world';
build() {
Column() {
Text(this.message)
.onClick(async () => {
try {
let context = this.getUIContext().getHostContext() as Context;
// 假设已经创建了一个session,如何创建session可以参考之前的案例。
let session = await AVSessionManager.createAVSession(context, 'SESSION_NAME', 'audio');
// 设置必要的媒体信息。
let metadata: AVSessionManager.AVMetadata = {
assetId: '0', // 由应用指定,用于标识应用媒体库里的媒体。
title: 'TITLE',
mediaImage: 'IMAGE',
artist: 'ARTIST',
};
session.setAVMetadata(metadata).then(() => {
console.info(`SetAVMetadata successfully`);
}).catch((err: BusinessError) => {
console.error(`Failed to set AVMetadata. Code: ${err.code}, message: ${err.message}`);
});
} catch (err) {
if (err) {
console.error(`AVSession create Error: Code: ${err.code}, message: ${err.message}`);
}
}
})
}
.width('100%')
.height('100%')
}
}
4、通用播放状态
import { avSession as AVSessionManager } from '@kit.AVSessionKit';
import { BusinessError } from '@kit.BasicServicesKit';
@Entry
@Component
struct Index {
@State message: string = 'hello world';
build() {
Column() {
Text(this.message)
.onClick(async () => {
let context = this.getUIContext().getHostContext() as Context;
// 假设已经创建了一个session,如何创建session可以参考之前的案例。
let session = await AVSessionManager.createAVSession(context, 'SESSION_NAME', 'audio');
// 播放器逻辑··· 引发媒体信息与播放状态的变更。
// 简单设置一个播放状态 - 暂停 未收藏。
let playbackState: AVSessionManager.AVPlaybackState = {
state: AVSessionManager.PlaybackState.PLAYBACK_STATE_PAUSE,
isFavorite: false
};
session.setAVPlaybackState(playbackState, (err: BusinessError) => {
if (err) {
console.error(`Failed to set AVPlaybackState. Code: ${err.code}, message: ${err.message}`);
} else {
console.info(`SetAVPlaybackState successfully`);
}
});
})
}
.width('100%')
.height('100%')
}
}
可以直接使用系统播控中心能力:

接入时需要使用 AvSession 接口,可参考 应用接入AVSession场景介绍-本地媒体会话-AVSession Kit(音视频播控服务)-媒体 - 华为HarmonyOS开发者
import { avSession as AVSessionManager } from '@kit.AVSessionKit';
import { BusinessError } from '@kit.BasicServicesKit';
@Entry
@Component
struct Index {
@State message: string = 'hello world';
build() {
Column() {
Text(this.message)
.onClick(async () => {
try {
let context = this.getUIContext().getHostContext() as Context;
// 假设已经创建了一个session,如何创建session可以参考之前的案例。
let session = await AVSessionManager.createAVSession(context, 'SESSION_NAME', 'audio');
// 设置必要的媒体信息。
let metadata: AVSessionManager.AVMetadata = {
assetId: '0', // 由应用指定,用于标识应用媒体库里的媒体。
title: 'TITLE',
mediaImage: 'IMAGE',
artist: 'ARTIST',
};
session.setAVMetadata(metadata).then(() => {
console.info(`SetAVMetadata successfully`);
}).catch((err: BusinessError) => {
console.error(`Failed to set AVMetadata. Code: ${err.code}, message: ${err.message}`);
});
} catch (err) {
if (err) {
console.error(`AVSession create Error: Code: ${err.code}, message: ${err.message}`);
}
}
})
}
.width('100%')
.height('100%')
}
}
如果不想接入播控中心,还可以使用锁屏卡片能力,参考 锁屏卡片开发指导-ArkTS锁屏卡片-ArkTS卡片提供方开发指导-ArkTS卡片开发(推荐)-Form Kit(卡片开发服务)-应用框架 - 华为HarmonyOS开发者

可以自行开发一个控制播放的锁屏卡片
HarmonyOS 5 支持锁屏媒体控制,但需满足:
- 使用
AVPlayer播放音频; - 调用
player.setMediaControlInfo()设置封面、标题、控制权限; - 系统自动在锁屏和通知栏生成标准媒体控件;
- 不支持自定义 UI 小部件(如进度条、歌词),仅提供播放/暂停/上一首/下一首;
可以参考音乐播控,或者接入实况窗
HarmonyOS Next支持在锁屏界面显示自定义通知小部件。开发者需使用ArkTS声明式UI开发,通过NotificationManager模块创建NotificationRequest,并设置其content属性为自定义组件。该组件需继承自CommonPanel,并遵循系统安全规范。锁屏小部件的显示受系统权限控制,用户可手动管理。
在HarmonyOS Next中,应用可以通过窗口扩展能力在锁屏界面显示自定义控件,这与iOS或Android的媒体通知控件在功能上类似。
具体实现上,你需要使用ArkUI的FormExtensionAbility来创建服务卡片(Service Widget)。虽然服务卡片通常用于桌面,但通过系统权限和特定配置,可以将其显示在锁屏界面。关键步骤包括:
- 声明权限:在
module.json5中申请ohos.permission.FORM_LOCK_SCREEN权限。 - 配置卡片:在
form_config.json中为卡片配置"supportDimensions": ["lock"],表示支持锁屏形态。 - 实现交互:在FormExtensionAbility中,通过
formProvider.updateForm更新卡片内容,并通过formBindingData传递播放状态等信息。卡片上的按钮点击事件可以通过postFormEvent与主应用通信。
需要注意的是,出于安全和功耗考虑,锁屏卡片的能力(如刷新频率、交互复杂度)可能受到比桌面卡片更严格的系统限制。你需要遵循HarmonyOS Next的设计规范,确保锁屏卡片简洁、低功耗。
目前,该功能主要面向系统预置应用或深度合作的伙伴应用开放,普通开发者在实机调试时可能需要相应的系统权限。建议在开发前仔细查阅最新的HarmonyOS Next API文档中关于FormExtensionAbility和锁屏能力的详细说明。

