目录

自定义播控中心控制按钮显示布局

从API版本26.0.0开始,系统支持自定义播控中心控制按钮的显示布局。本文档介绍播控中心控制按钮的默认显示规则,以及应用如何自定义控制按钮的显示。

基本概念

播控中心常见的控制按钮类型有:播放/暂停、上一首、下一首、快进、快退等。不同的播控页面会显示不同的控制按钮布局,目前主要有以下两种布局方式:

播控中心根据应用设置的AVSessionType会话类型(本文提到的会话类型均指应用设置的AVSessionType)决定三元组/五元组控制按钮的显示:

音视频类应用默认显示规则

播控中心默认三元组/五元组显示规则如下:

[h2]说明

应用自定义显示规则

应用可以通过setMediaCenterControlType接口自定义设置三元组/五元组控制按钮的显示,可设置的控制类型详见AVMediaCenterControlType。系统根据应用设置的AVMediaCenterControlType列表,结合系统显示优先级进行最终的三元组/五元组控制按钮显示,详细规则如下:

[h2]三元组自定义规则

编号 audio类型显示优先级(从左往右优先级依次降低) video类型显示优先级(从左往右优先级依次降低)
1号位 播放/暂停 播放/暂停
2号位 上一首 > 快退 > 循环模式 > 收藏 快退 > 上一首 > 循环模式 > 收藏
3号位 下一首 > 快进 > 收藏 > 倍速 快进 > 下一首 > 收藏 > 倍速

[h2]五元组自定义规则

编号 显示优先级(不区分audio和video类型,从左往右优先级依次降低)
1号位 播放/暂停
2号位 上一首 > 快退 > 循环模式 > 收藏
3号位 下一首 > 快进 > 收藏 > 倍速
4号位 快退 > 循环模式 > 收藏
5号位 快进 > 收藏 > 倍速

[h2]说明

参考案例

以下示例代码展示了应用如何在播控中心五元组上从左到右依次显示循环模式、上一首、播放/暂停、下一首、倍速。

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%')
  }
}