引言

在移动应用开发中，音频管理是一个容易被忽视但极其重要的领域。无论是播放音乐时被电话打断、设置闹钟时检查铃声音量，还是在游戏中检测静音模式——这些场景都需要应用与系统的音频服务进行交互。

HarmonyOS NEXT 通过 @ohos.multimedia.audio（AudioKit）提供了完整的音频管理能力。其中 AudioManager 是音频管理的入口单例，它允许开发者查询系统中各音频流的音量状态、获取最大/最小音量、检查铃音模式等。与直接操控音频播放（AudioRenderer）或录音（AudioCapturer）不同，AudioManager 关注的是系统级音频策略——哪些音频流正在工作、音量分别处于什么水平。

本文将构建一个音频音量管理器 Demo，展示如何使用 AudioManager 读取四种核心音频流的当前音量、最大音量和最小音量，并通过视觉进度条呈现各流的相对水平。

读完本文，你将掌握：

• AudioManager 获取：audio.getAudioManager() 获取系统音频管理器单例
• 音频流类型：AudioVolumeType 枚举（通话音量、铃声音量、媒体音量、闹钟音量）
• 音量查询：getVolume() / getMaxVolume() / getMinVolume() 三件套
• 流对比：不同音频流的音量范围差异——通话和铃声音量可能有不同的最大值
• 权限边界：读操作无需权限，写操作需要系统级授权

环境与权限

@ohos.multimedia.audio 属于 AudioKit 工具包，自 API 7 开始提供。读取音量信息不需要任何权限——这是一个友好的设计，让开发者可以自由地查询音频状态来优化用户体验。

import { audio } from '@kit.AudioKit';

注意：如果需要设置音量（setVolume()），则需要申请 ohos.permission.ACCESS_NOTIFICATION_POLICY 权限。这是一个系统级权限，普通应用无法获得——这也意味着 App 不能随意更改用户的音量设置。

一、AudioManager：音频管理的中枢

AudioManager 是整个音频模块的入口单例。通过它，你可以：

• 查询各音频流的音量（getVolume）
• 获取音量范围（getMinVolume / getMaxVolume）
• 获取响铃模式（getRingerMode）：正常/震动/静音
• 查询麦克风静音状态（isMicrophoneMute）
• 获取音频设备列表（getDevices）

AudioManager 通过 audio.getAudioManager() 获取，这是一个同步函数，返回单例对象：

import { audio } from '@kit.AudioKit';

let audioManager: audio.AudioManager = audio.getAudioManager();
// AudioManager 已就绪，可以开始查询

注意：getAudioManager() 不需要任何参数（新版 API）或只需要回调（旧版 API）。在 API 12 上测试的是同步版本，直接返回实例。

二、AudioVolumeType：四种核心音频流

HarmonyOS 将系统的音频输出划分为多个独立的音频流（Volume Stream），每种流有独立的音量控制。这种设计让用户可以分别设置铃声音量和媒体音量，互不干扰。

AudioVolumeType 枚举定义了这些流类型：

枚举值	数值	说明	典型场景
VOICE_CALL	0	通话音量	电话通话时的听筒/扬声器音量
RINGTONE	2	铃声音量	来电铃声、通知提示音
MEDIA	3	媒体音量	音乐播放、视频、游戏音效
ALARM	4	闹钟音量	闹钟响铃

注意枚举值不是连续的——VOICE_CALL = 0、RINGTONE = 2、MEDIA = 3、ALARM = 4。数字 1 被跳过了，这是历史原因导致的。

在 Demo 中，我们查询全部四种流的音量状态：

let streamTypes: audio.AudioVolumeType[] = [
  audio.AudioVolumeType.VOICE_CALL,
  audio.AudioVolumeType.RINGTONE,
  audio.AudioVolumeType.MEDIA,
  audio.AudioVolumeType.ALARM,
];

三、核心 API：音量查询三件套

AudioManager 提供了三个核心方法来查询每个音频流的音量信息：

3.1 getVolume(type) — 获取当前音量

audioManager.getVolume(audio.AudioVolumeType.MEDIA).then((vol: number) => {
  console.log('当前媒体音量: ' + vol);
});

返回一个 Promise<number>，表示该音频流的当前音量值。这个值是整数，范围为 [minVolume, maxVolume]。

注意：旧版 API（API 7-8）中 getVolume 是 AudioManager 的直接方法，新版（API 9+）已迁移到 AudioVolumeGroupManager，但为了兼容性，旧版方法仍然可用。

3.2 getMaxVolume(type) — 获取最大音量

audioManager.getMaxVolume(audio.AudioVolumeType.MEDIA).then((max: number) => {
  console.log('媒体音量最大值: ' + max);
});

不同音频流的最大音量可能不同。例如，通话音量通常范围较小（7 级），而媒体音量的范围较大（15 级）。这个差异源于硬件和用户体验的权衡——通话时用户不需要精细调节，而音乐播放则需要更多音量档位。

3.3 getMinVolume(type) — 获取最小音量

audioManager.getMinVolume(audio.AudioVolumeType.MEDIA).then((min: number) => {
  console.log('媒体音量最小值: ' + min);
});

绝大多数情况下，最小值返回 0。但理论上某些特殊设备可能有不同的最小值。

3.4 计算音量百分比

结合三个值，可以计算出当前音量的百分比：

let percent = max > min
  ? Math.round(((current - min) / (max - min)) * 100)
  : 0;

在 Demo 中，这个百分比直接驱动进度条的长度和颜色：

• 66% 以上：绿色（音量充足）
• 33%-66%：橙色（音量适中）
• 33% 以下：红色（音量偏低）
  
  

四、Stream 管理：为何需要独立音频流？

初学者常问：为什么系统不设置一个"总音量"而是分成四个独立流？

答案在于使用场景的冲突解决：

1. 通话优先：当你戴着耳机听音乐时，来电铃声和通话音量需要独立于媒体音量——你不想在通话时被音乐的音量影响对话清晰度。

2. 闹钟可靠性：闹钟需要独立于其他所有音量——即使你把媒体音量和铃声音量都设为静音，闹钟仍然需要以预设音量响铃（否则用户可能会错过重要日程）。

3. 用户心智模型：用户理解"这是通话音量"比理解"这是总音量的 60% 分配给通话"要直观得多。

HarmonyOS 的 AudioVolumeType 设计遵循了 Android 的 AudioStream 模式，这是一个经过市场验证的良好设计。

五、实战 Demo：音频音量管理器

页面结构

音频音量管理器
├── 状态栏 — 实时操作反馈
├── 操作面板 — "获取全部音量"按钮
├── 音频流音量列表
│   ├── 通话音量 (📞) — 进度条 + 当前值/最小/最大
│   ├── 铃声音量 (🔔) — 进度条 + 当前值/最小/最大
│   ├── 媒体音量 (🎵) — 进度条 + 当前值/最小/最大
│   └── 闹钟音量 (⏰) — 进度条 + 当前值/最小/最大
├── AudioManager 能力标签 — getVolume/getMaxVolume/getMinVolume/setVolume*
└── 核心 API 参考 — 8 个关键 API

4 个交互点

1. 获取全部音量 — 点击按钮依次查询四个音频流，异步返回当前/最大/最小音量
2. 音量进度条 — 每条流的当前音量以百分比进度条呈现，颜色根据音量高低自动变化（绿/橙/红）
3. 流对比 — 同时展示四条流，方便直观对比通话音量与媒体音量的范围差异
4. 权限提示 — setVolume API 标注星号，说明需要系统权限

核心代码位置

完整代码在 dev/entry/src/main/ets/pages/AudioVolumePage.ets（约 260 行），路由已注册为 pages/AudioVolumePage。

六、权限设计：读开放、写受限

AudioManager 的权限模型遵循"读开放、写受限"的原则：

操作	方法	权限要求
读取音量	getVolume()	无需权限
读取最大/最小	getMaxVolume() / getMinVolume()	无需权限
读取铃声模式	getRingerMode()	无需权限
读取麦克风静音	isMicrophoneMute()	无需权限
设置音量	setVolume()	ohos.permission.ACCESS_NOTIFICATION_POLICY
AudioRenderer	createAudioRenderer()	无需权限（取决于用途）
AudioCapturer	createAudioCapturer()	ohos.permission.MICROPHONE

这种设计保证了用户对设备音频的控制权——应用可以随时查询音频状态以提供更好的体验（比如播放前检测到媒体音量为 0 时提醒用户），但不能擅自修改设置。

七、API 总结表

API	返回值	说明
audio.getAudioManager()	AudioManager	获取 AudioManager 单例（同步）
am.getVolume(type)	Promise<number>	获取指定音频流当前音量
am.getMaxVolume(type)	Promise<number>	获取指定音频流最大音量
am.getMinVolume(type)	Promise<number>	获取指定音频流最小音量
am.getRingerMode()	Promise<AudioRingMode>	获取铃声模式（正常/震动/静音）
am.isMicrophoneMute()	Promise<boolean>	麦克风是否静音
AudioVolumeType	枚举	VOICE_CALL=0 / RINGTONE=2 / MEDIA=3 / ALARM=4

八、实际应用场景

1. 播放器启动前检查音量

let am = audio.getAudioManager();
let curVol = await am.getVolume(audio.AudioVolumeType.MEDIA);
let maxVol = await am.getMaxVolume(audio.AudioVolumeType.MEDIA);
if (curVol === 0) {
  // 提示用户："当前媒体音量为0，可能听不到声音哦"
  this.showVolumeTip();
}

2. 来电时自动降低音乐音量

// 监听通话音量变化
// 当检测到通话态时，保存当前媒体音量并降低
let savedMediaVol = await am.getVolume(audio.AudioVolumeType.MEDIA);
// 注意：setVolume 需要系统权限

3. 闹钟应用验证音量

let alarmVol = await am.getVolume(audio.AudioVolumeType.ALARM);
if (alarmVol < 2) {
  // 提醒用户闹钟音量过低，可能错过闹钟
  this.showAlarmVolumeWarning();
}

九、总结

@ohos.multimedia.audio 的 AudioManager 为 HarmonyOS NEXT 应用提供了系统级音频状态的查询能力：

1. 零权限读取 — getVolume/getMaxVolume/getMinVolume 完全开放，鼓励开发者获取音频上下文
2. 独立音频流 — 四种 AudioVolumeType 各司其职，覆盖通话、铃声、媒体和闹钟场景
3. 音量范围 — 不同流的最大音量可能不同，需要查询后计算百分比
4. 权限边界清晰 — 只读 = 免费，写入 = 系统权限，设计合理

这个 Demo 虽然代码量不大，但涵盖了一个容易被忽视的实用领域。在下一个迭代中，可以结合 AudioRenderer 实现实际的音频播放，或结合 getRingerMode() 检测静音/震动模式，为应用提供更智能的音频行为。

---