openharmony 鸿蒙 js-apis-avMusicTemplate-sys

2026-08-25 浏览 (1)

@ohos.multimedia.avMusicTemplate(音频模板)(系统接口)

音频模板控制相关接口，可用于向接入音频模板的媒体应用查询数据，进行统一风格的页面展示，并下发页面操作指令。

该模块提供如下功能：

AVMusicTemplateDescriptor：音频模板描述，包含音频模板唯一标识，应用的包名和用户ID信息。

说明：

  • 本模块首批接口从API version 23开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
  • 当前页面仅包含本模块的系统接口，其他公开接口参见@ohos.multimedia.avMusicTemplate (音频模板)。
  • 本模块仅适用于API version 23及以上版本的Car设备。

导入模块

import { avMusicTemplate } from '@kit.AVSessionKit';

avMusicTemplate.createAVMusicTemplateController

createAVMusicTemplateController(sessionId: string): AVMusicTemplateController

创建音频模板控制器，返回音频模板控制器对象。

模型约束： 此接口仅可在Stage模型下使用。

系统接口： 此接口为系统接口。

需要权限： ohos.permission.MANAGE_MEDIA_RESOURCES

系统能力： SystemCapability.Multimedia.AVSession.AVMusicTemplate

参数：

参数名类型必填说明
sessionIdstring是AVSession对象唯一的会话标识。

返回值：

类型说明
AVMusicTemplateController音频模板控制器，可以获得音频模板控制器唯一的标识，用于与接入音频模板的媒体应用数据交互。

错误码：

以下错误码的详细介绍请参见通用错误码和音频模板错误码。

错误码ID错误信息
201Permission verify failed.
202Not System App.
801Capability not supported.function createAVMusicTemplateController can not work correctly due to limited device capabilities.
35000002Failed to create the AVMusicTemplate controller.
35000005AVMusicTemplate does not exist.

示例：

import { avMusicTemplate } from '@kit.AVSessionKit';

const TAG: string = 'ControllerManager';

export class ControllerManager {
  private controller: avMusicTemplate.AVMusicTemplateController|undefined = undefined;
  private currentBundleName: string|undefined = undefined;
  private templateCreateCallback: Callback<avMusicTemplate.AVMusicTemplateDescriptor> =
    (descriptor: avMusicTemplate.AVMusicTemplateDescriptor) => {
      if (this.isInvalid(descriptor)) {
        console.warn(TAG, 'templateCreateCallback: descriptor is invalid');
        return;
      }
      console.info(TAG, `templateCreateCallback, bundleName: ${descriptor.bundleName}`);
      this.createController(descriptor.sessionId, descriptor.bundleName);
    };
  private templateDestroyCallback: Callback<avMusicTemplate.AVMusicTemplateDescriptor> =
    (descriptor: avMusicTemplate.AVMusicTemplateDescriptor) => {
      if (this.isInvalid(descriptor)) {
        console.warn(TAG, 'templateDestroyCallback: descriptor is invalid');
        return;
      }
      if (this.isStringEmpty(this.currentBundleName)) {
        console.warn(TAG, 'templateDestroyCallback: current bundleName is empty');
        return;
      }
      if (this.currentBundleName !== descriptor.bundleName) {
        console.warn(TAG, 'templateDestroyCallback: not current bundleName');
        return;
      }
      this.unregisterListener();
      this.destroyController();
    };

  /**
   * 通过getAllAVMusicTemplateDescriptors创建模板。
   */
  public createAvMusicTemplateController(bundleName: string) {
    if (this.isStringEmpty(bundleName)) {
      console.warn(TAG, 'createAvMusicTemplateController: bundleName is empty');
      return;
    }
    this.currentBundleName = bundleName;
    try {
      // 该方法需要权限ohos.permission.MANAGE_MEDIA_RESOURCES。
      let descriptors: avMusicTemplate.AVMusicTemplateDescriptor[] = avMusicTemplate.getAllAVMusicTemplateDescriptors();
      if (this.isEmptyArray(descriptors)) {
        console.info(TAG, 'createAvMusicTemplateController: descriptors is empty');
        return;
      }
      for (let descriptor of descriptors) {
        if (descriptor === null||descriptor === undefined) {
          console.warn(TAG, 'createAvMusicTemplateController: descriptor is invalid continue');
          continue;
        }
        if (this.currentBundleName === descriptor.bundleName) {
          this.createController(descriptor.sessionId, descriptor.bundleName);
          return;
        }
      }
    } catch (e) {
      console.error(TAG, `getAllAVMusicTemplateDescriptors failed, errCode: ${e?.code}`);
    }
  };

  private isInvalid<T>(obj: T): boolean {
    return obj === undefined||obj === null;
  }

  private isStringEmpty(str: string|undefined): boolean {
    return str === undefined||str === null||str.trim().length === 0;
  }

  private isEmptyArray<T>(array: T[]): boolean {
    return this.isInvalid(array)||array.length <= 0;
  }

  /**
   * 注册模板监听。
   */
  public registerAVMusicTemplateListener() {
    try {
      // 该方法需要权限ohos.permission.MANAGE_MEDIA_RESOURCES。
      avMusicTemplate.onAVMusicTemplateCreate(this.templateCreateCallback);

      // 该方法需要权限ohos.permission.MANAGE_MEDIA_RESOURCES。
      avMusicTemplate.onAVMusicTemplateDestroy(this.templateDestroyCallback);
    } catch (e) {
      console.error(TAG, `registerAVMusicTemplateListener: errCode: ${e?.code}`);
    }
  }

  private createController(sessionId: string, bundleName: string) {
    if (this.currentBundleName === null||this.currentBundleName === undefined) {
      console.warn(TAG, 'createController: sessionId is invalid');
      return;
    }
    if (sessionId === null||sessionId === undefined) {
      console.warn(TAG, 'createController: sessionId is invalid');
      return;
    }
    if (bundleName === null||bundleName === undefined) {
      console.warn(TAG, 'createController: bundleName is invalid');
      return;
    }
    if (this.currentBundleName !== bundleName) {
      console.warn(TAG, 'createController: not current bundleName');
      return;
    }
    if (this.controller != undefined) {
      console.warn(TAG, 'createController: controller not undefined');
      return;
    }
    try {
      this.controller = avMusicTemplate.createAVMusicTemplateController(sessionId);
      console.info('Succeeded in creating controller.');
    } catch (e) {
      console.error(TAG, `createController: errCode: ${e?.code}`);
    }
  }

  /**
   * 注销监听。
   */
  public unregisterListener() {
    // 注销用户信息改变的监听。
    this.controller?.offUserInfoChange();

    // 注销对话框命令改变的监听。
    this.controller?.offDialogCommandChange();

    // 注销当前单曲改变的监听。
    this.controller?.offCurrentSingleChange();

    // 注销媒体实体改变的监听。
    this.controller?.offMediaEntitiesChange();

    // 注销标签页内容改变的监听。
    this.controller?.offTabContentChange();

    // 注销播放列表改变的监听。
    this.controller?.offPlaylistChange();

    // 注销下载媒体状态改变的监听。
    this.controller?.offDownloadMediaEntityStatusChange();

    // 注销自定义元素改变的监听。
    this.controller?.offCustomElementsChange();

    // 注销设置改变的监听。
    this.controller?.offSettingsChange();

    // 注销上报执行动作的监听。
    this.controller?.offReportExecuteAction();

    // 注销通知媒体中心拉起指定三方应用界面的信息的监听。
    this.controller?.offExtensionAbilityChange();
  }

  /**
   * 销毁控制器。
   */
  public destroyController() {
    console.info(TAG, 'destroyController')
    this.controller?.destroy();
    this.controller = undefined;
    this.currentBundleName = undefined;
  }

  /**
   * 反注册模板监听。
   */
  public unregisterAVMusicTemplateListener() {
    try {
      avMusicTemplate.offAVMusicTemplateCreate();
      avMusicTemplate.offAVMusicTemplateDestroy();
    } catch (e) {
      console.error(TAG, `unregisterAVMusicTemplateListener: errCode: ${e?.code}`);
    }
  }
}

avMusicTemplate.getAllAVMusicTemplateDescriptors

getAllAVMusicTemplateDescriptors(userId?: number): AVMusicTemplateDescriptor[]

获取所有的音频模板描述，返回音频模板描述的集合。

模型约束： 此接口仅可在Stage模型下使用。

系统接口： 此接口为系统接口。

需要权限： ohos.permission.MANAGE_MEDIA_RESOURCES

系统能力： SystemCapability.Multimedia.AVSession.AVMusicTemplate

参数：

参数名类型必填说明
userIdnumber否用户ID。以用户传递为准，可为空。

返回值：

类型说明
AVMusicTemplateDescriptor[]音频模板描述的集合。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID错误信息
201Permission verify failed.
202Not System App.
801Capability not supported.function getAllAVMusicTemplateDescriptors can not work correctly due to limited device capabilities.

示例：

import { avMusicTemplate } from '@kit.AVSessionKit';

const TAG: string = 'ControllerManager';

export class ControllerManager {
  private currentBundleName: string|undefined = undefined;

  /**
   * 创建模板。
   */
  public createAvMusicTemplateController(bundleName: string) {
    if (this.isStringEmpty(bundleName)) {
      console.warn(TAG, 'createAvMusicTemplateController: bundleName is empty');
      return;
    }
    this.currentBundleName = bundleName;
    try {
      // 该方法需要权限ohos.permission.MANAGE_MEDIA_RESOURCES。
      let descriptors: avMusicTemplate.AVMusicTemplateDescriptor[] = avMusicTemplate.getAllAVMusicTemplateDescriptors();
    } catch (e) {
      console.error(TAG, `getAllAVMusicTemplateDescriptors failed, errCode: ${e?.code}`);
    }
  };

  private isStringEmpty(str: string|undefined): boolean {
    return str === undefined||str === null||str.trim().length === 0;
  }
}

avMusicTemplate.onAVMusicTemplateCreate

onAVMusicTemplateCreate(callback: Callback<AVMusicTemplateDescriptor>): void

注册音频模板创建的监听。使用callback异步回调。

模型约束： 此接口仅可在Stage模型下使用。

系统接口： 此接口为系统接口。

需要权限： ohos.permission.MANAGE_MEDIA_RESOURCES

系统能力： SystemCapability.Multimedia.AVSession.AVMusicTemplate

参数：

参数名类型必填说明
callbackCallback<AVMusicTemplateDescriptor>是回调函数，返回音频模板描述。用于处理会话创建的命令。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID错误信息
201Permission verify failed.
202Not System App.
801Capability not supported.function onAVMusicTemplateCreate can not work correctly due to limited device capabilities.

示例：

import { avMusicTemplate } from '@kit.AVSessionKit';

const TAG: string = 'ControllerManager';

export class ControllerManager {
  private templateCreateCallback: Callback<avMusicTemplate.AVMusicTemplateDescriptor> =
    (descriptor: avMusicTemplate.AVMusicTemplateDescriptor) => {
      if (this.isInvalid(descriptor)) {
        console.warn(TAG, 'templateCreateCallback: descriptor is invalid');
        return;
      }
      console.info(TAG, `templateCreateCallback, bundleName: ${descriptor.bundleName}`);
    };

  private isInvalid<T>(obj: T): boolean {
    return obj === undefined||obj === null;
  }

  /**
   * 注册模板监听。
   */
  public registerAVMusicTemplateListener() {
    try {
      // 该方法需要权限ohos.permission.MANAGE_MEDIA_RESOURCES。
      avMusicTemplate.onAVMusicTemplateCreate(this.templateCreateCallback);
    } catch (e) {
      console.error(TAG, `registerAVMusicTemplateListener: errCode: ${e?.code}`);
    }
  }
}

avMusicTemplate.offAVMusicTemplateCreate

offAVMusicTemplateCreate(callback?: Callback<AVMusicTemplateDescriptor>): void

注销音频模板创建监听。

模型约束： 此接口仅可在Stage模型下使用。

系统接口： 此接口为系统接口。

需要权限： ohos.permission.MANAGE_MEDIA_RESOURCES

系统能力： SystemCapability.Multimedia.AVSession.AVMusicTemplate

参数：

参数名类型必填说明
callbackCallback<AVMusicTemplateDescriptor>否回调函数，返回音频模板描述。不填该参数则注销该类型对应的所有回调。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID错误信息
201Permission verify failed.
202Not System App.
801Capability not supported.function offAVMusicTemplateCreate can not work correctly due to limited device capabilities.

示例：

import { avMusicTemplate } from '@kit.AVSessionKit';

const TAG: string = 'ControllerManager';

export class ControllerManager {
  /**
   * 反注册模板监听。
   */
  public unregisterAVMusicTemplateListener() {
    try {
      avMusicTemplate.offAVMusicTemplateCreate();
    } catch (e) {
      console.error(TAG, `unregisterAVMusicTemplateListener: errCode: ${e?.code}`);
    }
  }
}

avMusicTemplate.onAVMusicTemplateDestroy

onAVMusicTemplateDestroy(callback: Callback<AVMusicTemplateDescriptor>): void

注册音频模板销毁监听。使用callback异步回调。

模型约束： 此接口仅可在Stage模型下使用。

系统接口： 此接口为系统接口。

需要权限： ohos.permission.MANAGE_MEDIA_RESOURCES

系统能力： SystemCapability.Multimedia.AVSession.AVMusicTemplate

参数：

参数名类型必填说明
callbackCallback<AVMusicTemplateDescriptor>是回调函数，返回音频模板描述。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID错误信息
201Permission verify failed.
202Not System App.
801Capability not supported.function onAVMusicTemplateDestroy can not work correctly due to limited device capabilities.

示例：

import { avMusicTemplate } from '@kit.AVSessionKit';

const TAG: string = 'ControllerManager';

export class ControllerManager {
  private templateDestroyCallback: Callback<avMusicTemplate.AVMusicTemplateDescriptor> =
    (descriptor: avMusicTemplate.AVMusicTemplateDescriptor) => {
    };

  /**
   * 注册模板监听。
   */
  public registerAVMusicTemplateListener() {
    try {
      // 该方法需要权限ohos.permission.MANAGE_MEDIA_RESOURCES。
      avMusicTemplate.onAVMusicTemplateDestroy(this.templateDestroyCallback);
    } catch (e) {
      console.error(TAG, `registerAVMusicTemplateListener: errCode: ${e?.code}`);
    }
  }
}

avMusicTemplate.offAVMusicTemplateDestroy

offAVMusicTemplateDestroy(callback?: Callback<AVMusicTemplateDescriptor>): void

注销音频模板销毁监听。

模型约束： 此接口仅可在Stage模型下使用。

系统接口： 此接口为系统接口。

需要权限： ohos.permission.MANAGE_MEDIA_RESOURCES

系统能力： SystemCapability.Multimedia.AVSession.AVMusicTemplate

参数：

参数名类型必填说明
callbackCallback<AVMusicTemplateDescriptor>否回调函数，返回音频模板描述。不填该参数则注销该类型对应的所有回调。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID错误信息
201Permission verify failed.
202Not System App.
801Capability not supported.function offAVMusicTemplateDestroy can not work correctly due to limited device capabilities.

示例：

import { avMusicTemplate } from '@kit.AVSessionKit';

const TAG: string = 'ControllerManager';

export class ControllerManager {
  /**
   * 反注册模板监听。
   */
  public unregisterAVMusicTemplateListener() {
    try {
      avMusicTemplate.offAVMusicTemplateDestroy();
    } catch (e) {
      console.error(TAG, `unregisterAVMusicTemplateListener: errCode: ${e?.code}`);
    }
  }
}

AVMusicTemplateDescriptor

音频模板描述。包含音频模板唯一标识，应用的包名和用户ID。

模型约束： 此接口仅可在Stage模型下使用。

系统接口： 此接口为系统接口。

系统能力： SystemCapability.Multimedia.AVSession.AVMusicTemplate

名称类型只读可选说明
sessionIdstring否否音频模板唯一标识。
bundleNamestring否否应用的包名。
userIdnumber否否用户ID。

你可能感兴趣的鸿蒙文章

openharmony 鸿蒙 arkts-apis-avsession

openharmony 鸿蒙 arkts-apis-avsession-e

openharmony 鸿蒙 capi-native-avsession-h

openharmony 鸿蒙 errorcode-avsession

openharmony 鸿蒙 js-apis-inner-application-MediaControlExtensionContext-sys

openharmony 鸿蒙 arkts-apis-avMusicTemplate-AVMusicTemplateController

openharmony 鸿蒙 capi-native-avsession-base-h

openharmony 鸿蒙 arkts-apis-avMusicTemplate-t

openharmony 鸿蒙 arkts-apis-avMusicTemplate-i

openharmony 鸿蒙 capi-native-avcastcontroller-h

  • 所属分类： 后端技术
  • 本文标签： 鸿蒙 软件
  • 版权声明： 本文链接 https://seaxiang.com/blog/3HlqDNpO