1# @ohos.multimedia.avVolumePanel (音量面板) 2<!--Kit: Audio Kit--> 3<!--Subsystem: Multimedia--> 4<!--Owner: @ccfriend; @liao_qian--> 5<!--Designer: @ccfriend--> 6<!--Tester: @chenmingxi1_huawei--> 7<!--Adviser: @zengyawen--> 8 9本模块提供创建音量面板AVVolumePanel的功能，提供展示和调节系统音量的统一面板。 10 11应用无法直接调节系统音量，可以通过系统音量面板，让用户通过界面操作来调节音量。当用户通过应用内音量面板调节音量时，系统会展示音量提示界面，显性地提示用户系统音量发生改变。 12 13 14> **说明：** 15> 16> - 本模块首批接口从API version 12开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 17> - 示例效果请以真机为准，当前DevEco Studio预览器无真实音量展示和调节功能。 18> - **设备限制：** 19> - 在穿戴设备上，可用于调节系统音量，但不显示UX界面，需开发者自行设计界面。 20 21## 导入模块 22 23```js 24import { AVVolumePanel } from '@kit.AudioKit'; 25``` 26 27## 属性 28 29支持[通用属性](../apis-arkui/arkui-ts/ts-component-general-attributes.md)。 30 31## AVVolumePanel 32 33AVVolumePanel({volumeLevel?: number, volumeParameter?: AVVolumePanelParameter}) 34 35音量面板，可用于在当前应用内展示音量调节面板。 36 37**装饰器类型：** [@Component](../../ui/state-management/arkts-create-custom-components.md) 38 39**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 40 41**系统能力：** SystemCapability.Multimedia.Audio.Volume 42 43| 名称 | 类型 | 必填 | 装饰器类型 | 说明 | 44| -------- | -------- | -------- |--------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 45|volumeLevel | number | 否 | \@Prop | 通过音量面板设置的音量值。<br>该值应介于当前设备音量的最小值和最大值之间。<br>如果该值大于当前设备音量的最大值，则视为设置最大音量值。<br>如果该值小于当前设备音量的最小值，则视为设置最小音量值。<br>获取设备的最大值、最小值和当前值，可参考[AudioVolumeGroupManager](../apis-audio-kit/arkts-apis-audio-AudioVolumeGroupManager.md)。 | 46|volumeParameter | [AVVolumePanelParameter](#avvolumepanelparameter) | 否 | \@Prop |设置音量面板的自定义参数。 <br>如果不设置该参数，则为系统音量条。| 47 48## AVVolumePanelParameter 49 50音量面板参数设置。 51 52**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 53 54**系统能力：** SystemCapability.Multimedia.Audio.Volume 55 56| 名称 | 类型 | 必填 | 说明 | 57| -------- | -------- | -------- | -------- | 58|position | [Position](../apis-arkui/arkui-ts/ts-types.md#position) | 否 | 设置音量面板的位置。<br>如果不设置该参数，则为系统音量条位置。<br>如果设置该参数且参数对应屏幕内位置，则显示开发者设置的位置。<br>如果设置该参数且参数对应屏幕外位置，例如（-1， -1），不显示系统音量条，建议开发者显示自定义音量条。 | 59 60## 事件 61 62支持[通用事件](../apis-arkui/arkui-ts/ts-component-general-events.md)。 63 64## 使用建议 65 661. 应用在实现自定义音量条的过程中，建议使用音频框架的音量变化监听接口，通过接口回调的音量类型volumeEvent.volumeType，音量等级volumeEvent.volume以及是否显示音量条volumeEvent.updateUi等信息，应用可以判断是否需要处理当前数据和显示自定义的音量条，具体可参考[音量变化回调接口](arkts-apis-audio-AudioVolumeManager.md#onstreamvolumechange20)介绍。 672. 为确保用户能感知音量变化，不允许应用后台调节音量，系统会做出对应的控制措施。 68 69## 示例 70 71音量面板功能的示例说明参考如下。需要实际修改volume值或者按压音量按键体验调节音量效果。 72 73```ts 74import { AVVolumePanel } from '@kit.AudioKit'; 75 76@Entry 77@Component 78struct Index { 79 80 @State volume: number = 0; 81 82 build() { 83 Row() { 84 Column() { 85 AVVolumePanel({ 86 volumeLevel: this.volume, 87 volumeParameter: { 88 position: { 89 x: 100, 90 y: 200 91 } 92 } 93 }) 94 } 95 }.width('50%').height('50%') 96 } 97} 98``` 99