想在应用里直接修改系统媒体音量,按照 Audio 管理文档调用 getVolumeManager 和 setVolume,结果在真机上运行时抛 BusinessError.code = 801,错误信息为 Unsupported API。
import { audio } from '@kit.AudioKit';
import { BusinessError } from '@kit.BasicServicesKit';
async function setMediaVolume(volume: number) {
const audioManager = audio.getAudioManager();
const volumeManager = await audioManager.getVolumeManager();
volumeManager.setVolume(audio.AudioVolumeType.STREAM_MUSIC, volume)
.then(() => {
console.info('setVolume success');
})
.catch((err: BusinessError) => {
console.error(`setVolume error: code=${err.code}, msg=${err.message}`);
});
}
日志:
setVolume error: code=801, msg=Unsupported API.
这个场景下 不是你的代码写错了,而是调用了「System API」。
在 Audio 管理文档里,AudioVolumeManager 上的很多接口(比如 getVolumeGroupInfos、setVolume 等)都标记为:
System API:This is a system API.
这类 API 只有系统应用 / 预置应用才能访问,普通三方应用即使在 SDK 里能看到类型,也会在运行时收到类似 801 Unsupported API 的错误码。Gitee
因此:
-
801 对应「Unsupported API」,通常意味着当前应用不具备调用该 System API 的资格;
-
不是权限声明的问题,即便在
module.json5里声明了相关权限,也无法绕过 System API 限制。
对于第三方应用,有两种常见的处理方式:
-
只读不改
使用公开 API(非 System API)查询当前音量状态,在 UI 中展示信息,但不直接修改系统音量。 -
引导用户手动调整
在需要调节音量的场景弹出说明,引导用户使用硬件音量键或跳转到系统设置页面。
如果你是在做系统级 ROM / 预置应用开发,则需要:
-
确保应用拥有系统签名;
-
在系统工程中配置为系统应用;
-
按文档要求增加必要权限,然后才能正常调用
setVolume这类 System API。
总结一下:普通 Harmony 应用遇到 801 + System API 标签时,应当视为该能力不对三方开放,选择降级方案,而不是继续纠结代码写法。