更新记录

1.1.0（2025-05-13）

支持六种音量类型的获取和设置

• 提供同步和异步接口
• 修复整数除法导致的音量计算问题

1.0.0（2025-05-12）

制作uts插件，控制安卓端音量

平台兼容性

uni-app

uni-app x

volume-controller 音量控制插件

简介

音量控制插件是一个基于UTS（UniApp Type Script）开发的uni-app插件，用于获取和设置安卓系统的音量。插件支持控制多种音量类型，包括媒体音量、通话音量、系统音量等，并提供了同步和异步两种调用方式。

功能特点

• 多种音量类型支持：媒体音量、通话音量、系统音量、铃声音量、闹钟音量、通知音量
• 灵活的接口设计：提供同步和异步两种调用方式
• 精确的音量控制：支持0-1之间的小数精确控制
• 可选的UI显示：可选择是否显示系统音量UI
• 完善的错误处理：提供标准化的错误码和错误信息

平台支持

• Android: ✓ 支持
• iOS: × 不支持
• 其他平台: × 不支持

安装使用

方式一：从HBuilder插件市场导入

1. 在HBuilderX中，点击顶部菜单栏的"工具" -> "插件市场"
2. 搜索"音量控制插件"或"volume-controller"
3. 点击导入到项目
4. 选择要导入的项目，点击确定

方式二：手动导入

将插件目录复制到项目的uni_modules目录下。

配置 manifest.json

在项目的manifest.json文件中添加以下配置：

{
  "app-plus": {
    "modules": {
      "VolumeController": {}
    }
  }
}

API 说明

插件提供了4个主要API：

• getVolume: 异步获取系统音量
• setVolume: 异步设置系统音量
• getVolumeSync: 同步获取系统音量
• setVolumeSync: 同步设置系统音量

异步 API

getVolume(options)

异步获取系统音量。

参数说明

success 回调参数

fail 回调参数

示例代码

import { getVolume } from '@/uni_modules/volume-controller';

// 获取媒体音量
getVolume({
  type: 'music',
  success: (res) => {
    console.log('当前音量：', res.volume);
    // volume值范围为0-1之间的小数，可以乘以100转为百分比
    const volumePercent = Math.round(res.volume * 100);
    console.log('当前音量百分比：', volumePercent + '%');
  },
  fail: (err) => {
    console.error('获取音量失败：', err.errMsg);
  }
});

setVolume(options)

异步设置系统音量。

参数说明

success 回调参数

示例代码

import { setVolume } from '@/uni_modules/volume-controller';

// 设置媒体音量为50%
setVolume({
  volume: 0.5,
  type: 'music',
  showUI: true,
  success: (res) => {
    console.log('设置音量' + (res.success ? '成功' : '失败'));
  },
  fail: (err) => {
    console.error('设置音量失败：', err.errMsg);
  }
});

同步 API

getVolumeSync([type])

同步获取系统音量。

参数说明

返回值

示例代码

import { getVolumeSync } from '@/uni_modules/volume-controller';

// 获取媒体音量
const result = getVolumeSync('music');
console.log('当前音量：', result.volume);
console.log('当前音量百分比：', Math.round(result.volume * 100) + '%');

setVolumeSync(volume[, type[, showUI]])

同步设置系统音量。

参数说明

返回值

示例代码

import { setVolumeSync } from '@/uni_modules/volume-controller';

// 设置媒体音量为50%
const result = setVolumeSync(0.5, 'music', true);
console.log('设置音量' + (result.success ? '成功' : '失败'));

技术实现

插件使用Android原生的AudioManager类来获取和设置音量，确保操作的精确性和高效性。主要实现方式如下：

1. 通过getSystemService(Context.AUDIO_SERVICE)获取系统音频服务
2. 使用getStreamVolume和getStreamMaxVolume获取当前音量和最大音量
3. 将当前音量与最大音量比值转换为0-1之间的小数
4. 设置音量时将0-1之间的小数转换为实际音量等级

插件对各种边缘情况进行了处理，如音频服务不可用、参数类型错误等，确保稳定可靠的工作。

错误码说明

使用场景示例

音量设置面板

可以创建一个音量设置面板，允许用户调整不同类型的系统音量：

<template>
  <view class="volume-panel">
    <view class="volume-item">
      <text>媒体音量</text>
      <slider :value="mediaVolume * 100" @change="changeMediaVolume" show-value />
    </view>
    <view class="volume-item">
      <text>铃声音量</text>
      <slider :value="ringVolume * 100" @change="changeRingVolume" show-value />
    </view>
  </view>
</template>

<script>
import { getVolume, setVolume } from '@/uni_modules/volume-controller';

export default {
  data() {
    return {
      mediaVolume: 0.5,
      ringVolume: 0.5
    }
  },
  mounted() {
    this.refreshVolumes();
  },
  methods: {
    refreshVolumes() {
      // 获取媒体音量
      getVolume({
        type: 'music',
        success: (res) => {
          this.mediaVolume = res.volume;
        }
      });

      // 获取铃声音量
      getVolume({
        type: 'ring',
        success: (res) => {
          this.ringVolume = res.volume;
        }
      });
    },
    changeMediaVolume(e) {
      const volume = e.detail.value / 100;
      setVolume({
        volume: volume,
        type: 'music',
        showUI: true,
        success: () => {
          this.mediaVolume = volume;
        }
      });
    },
    changeRingVolume(e) {
      const volume = e.detail.value / 100;
      setVolume({
        volume: volume,
        type: 'ring',
        showUI: true,
        success: () => {
          this.ringVolume = volume;
        }
      });
    }
  }
}
</script>

音量控制组件

可以创建一个用于视频或音频播放界面的音量控制组件：

<template>
  <view class="volume-control">
    <view class="volume-icon" @click="toggleMute">
      <uni-icons :type="isMuted ? 'sound-filled' : 'sound'" size="24"></uni-icons>
    </view>
    <slider 
      class="volume-slider" 
      :value="currentVolume * 100" 
      @change="" 
      block-size="18" 
      activeColor="#007AFF" 
      backgroundColor="#E0E0E0" 
    />
  </view>
</template>

<script>
import { getVolumeSync, setVolume } from '@/uni_modules/volume-controller';

export default {
  data() {
    return {
      currentVolume: 0.5,
      lastVolume: 0.5,
      isMuted: false
    }
  },
  mounted() {
    // 获取当前媒体音量
    const result = getVolumeSync('music');
    this.currentVolume = result.volume;
    this.lastVolume = result.volume;
  },
  methods: {
    (e) {
      const newVolume = e.detail.value / 100;
      this.setSystemVolume(newVolume);
      this.isMuted = newVolume === 0;
      this.lastVolume = newVolume > 0 ? newVolume : this.lastVolume;
    },
    toggleMute() {
      if (this.isMuted) {
        // 取消静音
        this.setSystemVolume(this.lastVolume);
        this.isMuted = false;
      } else {
        // 静音
        this.setSystemVolume(0);
        this.isMuted = true;
      }
    },
    setSystemVolume(volume) {
      this.currentVolume = volume;
      setVolume({
        volume: volume,
        type: 'music',
        showUI: true
      });
    }
  }
}
</script>

<style lang="scss">
.volume-control {
  display: flex;
  align-items: center;
  background-color: rgba(0, 0, 0, 0.05);
  padding: 8px 12px;
  border-radius: 20px;

  .volume-icon {
    margin-right: 10px;
  }

  .volume-slider {
    flex: 1;
    margin: 0 4px;
  }
}
</style>

注意事项

1. 该插件仅在Android平台支持，在其他平台上调用不会生效。
2. 使用插件需要设备权限支持，请确保应用有相应的权限。
3. 音量值范围为0-1之间的小数，表示音量百分比。
4. 在使用前必须先在manifest.json中配置模块并制作自定义基座。
5. 系统可能对音量调节进行限制，例如静音模式下可能无法调节某些类型的音量。
6. 使用整数除法时需要特别注意，应先将整数转换为浮点数再进行除法运算，否则会导致小数部分被截断。

常见问题解答

Q: 插件返回的音量始终为0，怎么解决？

A: 这可能是因为整数除法导致的。在UTS中，两个整数相除会丢弃小数部分。请确保计算音量比例时，先将整数转换为浮点数(number)再进行除法运算。

Q: 如何在manifest.json中正确配置插件？

A: 请在manifest.json的"app-plus"→"modules"部分添加"VolumeController": {}配置，而不是添加到"nativePlugins"部分。

Q: 在iOS设备上调用插件没有反应怎么办？

A: 本插件仅支持Android平台，在iOS或其他平台上无效。请在使用前进行平台判断。

关于作者

本插件由UTS插件开发者提供，遵循相关开源协议。欢迎使用和贡献。

更新日志

v1.1.0 (2025-05-13)

• 初始版本发布
• 支持六种音量类型的获取和设置
• 提供同步和异步接口
• 修复整数除法导致的音量计算问题