从API版本26.0.0开始,系统支持自定义播控中心控制按钮的显示布局。本文档介绍播控中心控制按钮的默认显示规则,以及应用如何自定义控制按钮的显示。
播控中心常见的控制按钮类型有:播放/暂停、上一首、下一首、快进、快退等。不同的播控页面会显示不同的控制按钮布局,目前主要有以下两种布局方式:


播控中心根据应用设置的AVSessionType会话类型(本文提到的会话类型均指应用设置的AVSessionType)决定三元组/五元组控制按钮的显示:
通话类型的应用:如voice_call、video_call类型,只涉及在播控中心的三元组界面显示,且固定显示为:2号位显示置灰的上一首、1号位显示置灰的播放、3号位显示置灰的下一首。
音视频类型的应用:涉及播控中心的三元组和五元组界面显示,主要分为audio和video两种类型显示规则,具体的显示规则下文详细介绍。
播控中心默认三元组/五元组显示规则如下:
五元组:
audio类型:循环模式、上一首、播放/暂停、下一首、收藏。
当应用支持倍速时,五元组的4号位和5号位显示如下:
video类型:快退、上一首、播放/暂停、下一首、快进。
三元组:
应用可以通过setMediaCenterControlType接口自定义设置三元组/五元组控制按钮的显示,可设置的控制类型详见AVMediaCenterControlType。系统根据应用设置的AVMediaCenterControlType列表,结合系统显示优先级进行最终的三元组/五元组控制按钮显示,详细规则如下:
| 编号 | audio类型显示优先级(从左往右优先级依次降低) | video类型显示优先级(从左往右优先级依次降低) |
|---|---|---|
| 1号位 | 播放/暂停 | 播放/暂停 |
| 2号位 | 上一首 > 快退 > 循环模式 > 收藏 | 快退 > 上一首 > 循环模式 > 收藏 |
| 3号位 | 下一首 > 快进 > 收藏 > 倍速 | 快进 > 下一首 > 收藏 > 倍速 |
| 编号 | 显示优先级(不区分audio和video类型,从左往右优先级依次降低) |
|---|---|
| 1号位 | 播放/暂停 |
| 2号位 | 上一首 > 快退 > 循环模式 > 收藏 |
| 3号位 | 下一首 > 快进 > 收藏 > 倍速 |
| 4号位 | 快退 > 循环模式 > 收藏 |
| 5号位 | 快进 > 收藏 > 倍速 |
以下示例代码展示了应用如何在播控中心五元组上从左到右依次显示循环模式、上一首、播放/暂停、下一首、倍速。
import { avSession as AVSessionManager } from '@kit.AVSessionKit';
// ...
@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 type: AVSessionManager.AVSessionType = 'audio';
let session = await AVSessionManager.createAVSession(context, 'SESSION_NAME', type);
// 设置必要的媒体信息和监听。
let metadata: AVSessionManager.AVMetadata = {
assetId: '0',
title: 'TITLE',
};
await session.setAVMetadata(metadata);
session.on('play', () => {
console.info(`onPlay`);
});
session.on('playNext', () => {
console.info(`onPlayNext`);
});
// 播控中心显示循环模式按钮:注册监听 + 设置范围。
// 注册'setTargetLoopMode'监听。
session.on('setTargetLoopMode', (loopMode: AVSessionManager.LoopMode) => {
console.info(`targetLoopMode change: ${loopMode}`);
});
// 设置支持的循环模式范围。
session.setSupportedLoopModes(
[AVSessionManager.LoopMode.LOOP_MODE_SINGLE, AVSessionManager.LoopMode.LOOP_MODE_LIST,
AVSessionManager.LoopMode.LOOP_MODE_SHUFFLE]);
// 播控中心显示倍速按钮:注册监听 + 设置范围。
// 注册'setSpeed'监听。
session.on('setSpeed', (speed: number) => {
console.info(`speed change: ${speed}`);
});
// 设置支持的倍速范围。
session.setSupportedPlaySpeeds([0.5, 1.0, 2]);
// 调用接口设置支持的控制命令类型列表。
session.setMediaCenterControlType(['playNext', 'setLoopMode', 'setSpeed']);
// 设置完成后,播控中心三元组会显示上一首、播放/暂停、下一首;五元组会显示循环模式、上一首、播放/暂停、下一首、倍速。
// ...
} catch (err) {
console.error(`Failed to setMediaCenterControlType. Code: ${err.code}, message: ${err.message}`);
}
})
}
.width('100%')
.height('100%')
}
}