JS应用框架文档

# 系统音量 volume

# 导入模块

import volume from '@system.volume';

# volume.getMediaValue(OBJECT)

获取当前多媒体音量。

  • 参数
参数名 类型 必填 说明
success Function 否 成功回调。
fail Function 否 失败回调。
complete Function 否 执行结束后的回调。
  • 返回值
参数名 类型 说明
value Number 系统媒体当前音量，共有 5 个音量档次 0, 0.4, 0.6, 0.8, 1。
  • 示例
volume.getMediaValue({
	success: function(data) {
		console.log(`handling success: ${data.value}`);
	},
	fail: function(data, code) {
		console.log(`handling fail, code = ${code}`);
	}
});

# volume.setMediaValue(OBJECT)

设置当前多媒体音量。

  • 参数
参数名 类型 必填 说明
value Number 是 设置的音量，共有 5 个音量档次 0, 0.4, 0.6, 0.8, 1。
success Function 否 成功回调。
fail Function 是 失败回调，连接蓝牙耳机加大音量时，会有弹窗提醒，点取消按钮会走 fail 回调，音量不会变化。
complete Function 否 执行结束后的回调。
  • 示例
volume.setMediaValue({
	value: 0.8,
	success: function() {
		console.log('handling success');
	},
	fail: function(data, code) {
		console.log(`handling fail, code = ${code}`);
	}
});

# 音量调节

新的音量调节支持三种类型音量单独调节。注：部分机型支持。

import volume from '@system.volume';

// 媒体音量，目前大部分场景都是调节此音量
volume.TYPE_MEDIA;

// 系统音量，通知音/提示音等系统音量
volume.TYPE_SYSTEM;

// 闹钟音量
volume.TYPE_ALARM;

# volume.getMaxVolume(TYPE)

获取指定类型音量的最大值。

  • 参数
参数名 类型 必填 说明
type Number 是 音量类型，可取 volume.TYPE_MEDIA、volume.TYPE_SYSTEM、volume.TYPE_ALARM。
  • 返回值
类型 说明
Number 指定类型音量的最大值。
  • 示例
// 获取媒体最大音量
let maxVolume = volume.getMaxVolume(volume.TYPE_MEDIA);

# volume.setVolume(OBJECT)

设置指定类型的音量。

  • 参数
参数名 类型 必填 说明
type Number 是 音量类型，可取 volume.TYPE_MEDIA、volume.TYPE_SYSTEM、volume.TYPE_ALARM。
value Number 是 设置的音量，取值范围为 0 到最大音量。
success Function 否 成功回调。部分场景会提示音量过大，此时音量不会增加，需在回调中再次获取当前音量确保显示正确。
fail Function 否 失败回调。
complete Function 否 执行结束后的回调。
  • 示例
volume.setVolume({
	type: volume.TYPE_MEDIA, // 设置媒体音量
	value: vol, // 合法值范围为 0 <= vol <= maxVolume
	success: data => {
		// 不管最终音量是否增加/减少，都会回调 success，部分场景会提示音量过大，
		// 此时音量不会增加，需在回调中再次获取当前音量，确保 UI 音量显示正确
	}
});

# volume.getVolume(OBJECT)

获取指定类型的当前音量大小。

  • 参数
参数名 类型 必填 说明
type Number 是 音量类型，可取 volume.TYPE_MEDIA、volume.TYPE_SYSTEM、volume.TYPE_ALARM。
success Function 否 成功回调。
fail Function 否 失败回调。
complete Function 否 执行结束后的回调。
  • success 返回值
参数名 类型 说明
value Number 当前音量。
  • 示例
volume.getVolume({
	type: volume.TYPE_MEDIA, // 音量类型
	success: data => {
		// data.value 即为当前音量
		this.curVolume = data.value;
	}
});

# volume.subscribe(OBJECT)

监听音量改变。

  • 参数
参数名 类型 必填 说明
type Number 否 音量类型，可取 volume.TYPE_MEDIA、volume.TYPE_SYSTEM、volume.TYPE_ALARM。不传默认为 volume.TYPE_MEDIA。
onchange Function 是 音量改变时的回调，参数 value 为当前音量。
success Function 否 成功回调。
fail Function 否 失败回调。
complete Function 否 执行结束后的回调。
  • 示例
volume.subscribe({
	type: volume.TYPE_MEDIA, // 可选参数，监听哪个类型音量改变，不传默认为 TYPE_MEDIA
	onchange: value => {
		// value 为当前音量
		console.log('volume changed:' + value);
	},
	success: data => {
	},
	fail: (msg, code) => {
	}
});

# volume.unsubscribe(OBJECT)

取消监听音量改变。

  • 参数
参数名 类型 必填 说明
success Function 否 成功回调。
fail Function 否 失败回调。
complete Function 否 执行结束后的回调。
  • 示例
volume.unsubscribe({
	success: data => {
	},
	fail: (msg, code) => {
	}
});

# 最佳实践

进入音量调节界面后，监听音量改变，UI 上音量值始终和 onchange 回调中的值保持一致，这样不管是设置音量由于系统策略拦截了，还是系统其他功能导致音量改变了，都可以在 UI 上实时更新。

← 电量信息 battery →