# @capawesome/capacitor-volume 中文文档

规范地址：https://npmcn.com/package/%40capawesome/capacitor-volume/

版本：0\.1\.3
npm 元数据更新时间：2026-09-02T08:23:53.385Z
中文译文更新时间：2026-11-09T08:15:43.413Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40capawesome/capacitor-volume
原文对照：https://npmcn.com/package/%40capawesome/capacitor-volume/?lang=original
项目主页：https://capawesome.io/docs/sdks/capacitor/volume/
源码仓库：https://github.com/capawesome-team/capacitor-plugins

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：113 kB，50 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@capacitor/core \>=8\.0\.0
- 首次发布：2026-07-07T06:22:32.685Z
- 最新版本发布：2026-09-02T08:23:52.514Z
- 近 30 天下载量：3646（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：5（近 12 个月 5 个）

## 中文简介

Capacitor插件来控制音量并观察Android和iOS上的硬件音量按钮.

## 安装

```sh
npm install @capawesome/capacitor-volume
```

也可以使用：`pnpm add @capawesome/capacitor-volume`、`yarn add @capawesome/capacitor-volume`、`bun add @capawesome/capacitor-volume`

## README

# 电容卷插件

控制音量并观察硬件音量按钮的电容插件.

[![Deliver Live Updates to your Capacitor app with Capawesome Cloud](https://cloud.capawesome.io/assets/banners/cloud-build-and-deploy-capacitor-apps.png?t=1)](https://cloud.capawesome.io/)

## 特征

-   🔊 **量控**: 获取并设置音量关卡.
-   🎚️ **音频流**:控制Android上的单个音频流(音乐,戒指,警报等).
-   🔘 **音量按钮**: 听取硬件音量按钮按下.
-   🤫 **取缔**:保持音量不变,在观看时隐藏系统音量指示器.
-   👂 **改变事件**: 聆听音量级别的变化.
-   🤝 **兼容性**: 与 [音频会话](https://capawesome.io/docs/sdks/capacitor/audio-session/), (中文(简体) ), [媒体会议](https://capawesome.io/docs/sdks/capacitor/media-session/) 财务报告和审定财务报表 [静态](https://capawesome.io/docs/sdks/capacitor/silent-mode/) 插件 .
-   📦 **可可花和SPM**:支持CocoaPods和Swift软件包管理器用于iOS.
-   🔁 **最新数据**:总是支持最新的Capacitor版本.

缺少一个功能? 刚刚 [打开一个问题](https://github.com/capawesome-team/capacitor-plugins/issues) 我们看看!

## 使用大小写

音量插件通常用于应用程序需要控制音量或对硬件音量按钮作出反应时,例如:

-   **媒体应用程序**:从自己的玩家UI读取并调整媒体卷.
-   **相机应用程序**:在保持音量不变的同时,使用硬件音量按钮作为快门触发.
-   **远程控制应用程序**:将音量按钮映射到自定义动作上,例如用于控制外部设备.
-   **音频指导**:当音量过低,无法听到重要音频提示时警告用户.

## 兼容性

| 插件版本 | 电容版本 | 状态 |
| --- | --- | --- |
| 0.x.x (中文(简体) ) | \>=8.x.x | 积极支持 |

## 安装

你可以用我们的 **AI 辅助设置** 以安装插件. 添加数据 [超级技能](https://github.com/capawesome-team/skills) 至您的 AI 工具,使用以下命令:

```bash
npx skills add capawesome-team/skills --skill capacitor-plugins
```

然后使用下列提示:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-volume` plugin in my project.
```

如果你喜欢 **手动设置**,通过运行以下命令来安装插件,并遵循下面的平台特定指令:

```bash
npm install @capawesome/capacitor-volume
npx cap sync
```

此插件仅可用于 **机器人** 财务报告和审定财务报表 **iOS系统**。在网络上,所有方法都认为未执行.

## 配置

此插件不需要配置 .

## 使用量

以下例子显示如何获取并设定当前音量,观看硬件音量按钮,收听音量按钮按下和音量变化,并删除所有收听者.

### 获取当前音量

读取当前音量级别为值 `0` 财务报告和审定财务报表 `1`。在Android上,您可以选择带有以下内容的音频流(例如环流) `stream` 选项。 在iOS上,这总是返回媒体的音量:

```typescript
import { Volume, VolumeStream } from '@capawesome/capacitor-volume';

const getVolume = async () => {
  const { volume } = await Volume.getVolume();
  return volume;
};

const getRingVolume = async () => {
  const { volume } = await Volume.getVolume({ stream: VolumeStream.Ring });
  return volume;
};
```

### 设定音量

将音量级别设定为值 `0` 财务报告和审定财务报表 `1`在Android上,您可以选择带有 `stream` 选项。 在iOS上,这总是设置媒体量:

```typescript
import { Volume } from '@capawesome/capacitor-volume';

const setVolume = async () => {
  await Volume.setVolume({ volume: 0.5 });
};
```

### 注意硬件音量按钮

开始监视硬件音量按钮以接收 `volumeButtonPressed` 财务报告和审定财务报表 `volumeChange` 事件。 与 `suppressVolumeChange` 选项,音量级别保持不变,系统音量指标在监视时被隐藏:

```typescript
import { Volume } from '@capawesome/capacitor-volume';

const startWatching = async () => {
  await Volume.startWatching({ suppressVolumeChange: true });
};

const stopWatching = async () => {
  await Volume.stopWatching();
};

const isWatching = async () => {
  const { watching } = await Volume.isWatching();
  return watching;
};
```

### 听音量按钮按下

在按下硬件音量按钮时得到通知 。 活动只在观看时才发布(见上文):

```typescript
import { Volume } from '@capawesome/capacitor-volume';

const addVolumeButtonPressedListener = async () => {
  await Volume.addListener('volumeButtonPressed', event => {
    console.log('Volume button pressed:', event.direction);
  });
};
```

### 音量变化

当音量级别发生变化时得到通知. 活动只在观看时才发布(见上文):

```typescript
import { Volume } from '@capawesome/capacitor-volume';

const addVolumeChangeListener = async () => {
  await Volume.addListener('volumeChange', event => {
    console.log('Volume changed:', event.volume);
  });
};
```

### 删除所有听众

当此插件不再需要时, 移除全部监听器 :

```typescript
import { Volume } from '@capawesome/capacitor-volume';

const removeAllListeners = async () => {
  await Volume.removeAllListeners();
};
```

## API 密码

-   [`getVolume(...)`](https://npmcn.com/package/%40capawesome/capacitor-volume/#readme-getvolume)
-   [`isWatching()`](https://npmcn.com/package/%40capawesome/capacitor-volume/#readme-iswatching)
-   [`setVolume(...)`](https://npmcn.com/package/%40capawesome/capacitor-volume/#readme-setvolume)
-   [`startWatching(...)`](https://npmcn.com/package/%40capawesome/capacitor-volume/#readme-startwatching)
-   [`stopWatching()`](https://npmcn.com/package/%40capawesome/capacitor-volume/#readme-stopwatching)
-   [`addListener('volumeButtonPressed', ...)`](https://npmcn.com/package/%40capawesome/capacitor-volume/#readme-addlistenervolumebuttonpressed-)
-   [`addListener('volumeButtonReleased', ...)`](https://npmcn.com/package/%40capawesome/capacitor-volume/#readme-addlistenervolumebuttonreleased-)
-   [`addListener('volumeChange', ...)`](https://npmcn.com/package/%40capawesome/capacitor-volume/#readme-addlistenervolumechange-)
-   [`removeAllListeners()`](https://npmcn.com/package/%40capawesome/capacitor-volume/#readme-removealllisteners)
-   [接口](https://npmcn.com/package/%40capawesome/capacitor-volume/#readme-interfaces)
-   [类型异名](https://npmcn.com/package/%40capawesome/capacitor-volume/#readme-type-aliases)
-   [数字](https://npmcn.com/package/%40capawesome/capacitor-volume/#readme-enums)

### 获取Volume (...)

```typescript
getVolume(options?: GetVolumeOptions | undefined) => Promise<GetVolumeResult>
```

获取当前音量级别 .

在iOS上,这总是返回媒体的音量.

仅在Android和iOS上提供.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[GetVolumeOptions](https://npmcn.com/package/%40capawesome/capacitor-volume/#readme-getvolumeoptions)` |

**回返情况:** `Promise<[GetVolumeResult](https://npmcn.com/package/%40capawesome/capacitor-volume/#readme-getvolumeresult)>`

**自:** 0.1.0 (中文(简体) )

* * *

### 正在观察 ()

```typescript
isWatching() => Promise<IsWatchingResult>
```

检查硬件音量按钮是否正在被监视 .

仅在Android和iOS上提供.

**回返情况:** `Promise<[IsWatchingResult](https://npmcn.com/package/%40capawesome/capacitor-volume/#readme-iswatchingresult)>`

**自:** 0.1.0 (中文(简体) )

* * *

### 设置卷 (...)

```typescript
setVolume(options: SetVolumeOptions) => Promise<void>
```

设置音量关.

在iOS上,这总是设置媒体量.

仅在Android和iOS上提供.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[SetVolumeOptions](https://npmcn.com/package/%40capawesome/capacitor-volume/#readme-setvolumeoptions)` |

**自:** 0.1.0 (中文(简体) )

* * *

### 开始监视(...)

```typescript
startWatching(options?: StartWatchingOptions | undefined) => Promise<void>
```

开始观看硬件音量按钮.

这个 `volumeButtonPressed`, (中文(简体) ), `volumeButtonReleased` 财务报告和审定财务报表 `volumeChange` 事件只在观看时才被释放.

如果音量按钮已经被监视了,这个呼叫已经 没有效果。 打电话 `stopWatching()` 首先更改选项.

仅在Android和iOS上提供.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[StartWatchingOptions](https://npmcn.com/package/%40capawesome/capacitor-volume/#readme-startwatchingoptions)` |

**自:** 0.1.0 (中文(简体) )

* * *

### 停止监视( C)

```typescript
stopWatching() => Promise<void>
```

停止观看硬件音量按钮.

在 iOS 上,这也恢复了当 观看如果 `suppressVolumeChange` 选项已启用.

仅在Android和iOS上提供.

**自:** 0.1.0 (中文(简体) )

* * *

### 添加倾听器( “ opulations Button Pressed ” ,...)

```typescript
addListener(eventName: 'volumeButtonPressed', listenerFunc: (event: VolumeButtonPressedEvent) => void) => Promise<PluginListenerHandle>
```

在观看时按下硬件音量按钮时调用 .

仅在Android和iOS上提供.

| 参数 | 类型 |
| --- | --- |
| **`eventName`** | `'volumeButtonPressed'` |
| **`listenerFunc`** | `(event: [VolumeButtonPressedEvent](https://npmcn.com/package/%40capawesome/capacitor-volume/#readme-volumebuttonpressedevent)) => void` |

**回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capawesome/capacitor-volume/#readme-pluginlistenerhandle)>`

**自:** 0.1.0 (中文(简体) )

* * *

### 添加倾听器( “ 批量按钮释放 ” ,...)

```typescript
addListener(eventName: 'volumeButtonReleased', listenerFunc: (event: VolumeButtonReleasedEvent) => void) => Promise<PluginListenerHandle>
```

在观看时发布硬件音量按钮时调用 .

只能从Android上找到.

| 参数 | 类型 |
| --- | --- |
| **`eventName`** | `'volumeButtonReleased'` |
| **`listenerFunc`** | `(event: [VolumeButtonReleasedEvent](https://npmcn.com/package/%40capawesome/capacitor-volume/#readme-volumebuttonreleasedevent)) => void` |

**回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capawesome/capacitor-volume/#readme-pluginlistenerhandle)>`

**自:** 0.2.0 (中文(简体) )

* * *

### 添加倾听器( “ 量变化 ” ,...)

```typescript
addListener(eventName: 'volumeChange', listenerFunc: (event: VolumeChangeEvent) => void) => Promise<PluginListenerHandle>
```

当量级变化时在观看时调用 .

在Android上,这被叫作要改变音乐流. 在iOS上,这需要修改媒体量,并且是 未调用时 `suppressVolumeChange` 选项已启用.

仅在Android和iOS上提供.

| 参数 | 类型 |
| --- | --- |
| **`eventName`** | `'volumeChange'` |
| **`listenerFunc`** | `(event: [VolumeChangeEvent](https://npmcn.com/package/%40capawesome/capacitor-volume/#readme-volumechangeevent)) => void` |

**回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capawesome/capacitor-volume/#readme-pluginlistenerhandle)>`

**自:** 0.1.0 (中文(简体) )

* * *

### 删除所有收听器( )

```typescript
removeAllListeners() => Promise<void>
```

删除此插件的所有听众 .

**自:** 0.1.0 (中文(简体) )

* * *

### 接口

#### 获取卷起

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`volume`** | `number` | 当前数量水平作为值介于 `0` 财务报告和审定财务报表 `1`。 。 。 . | 0.1.0 (中文(简体) ) |

#### 获取Volume 选项

| Prop | 类型 | 说明 | 默认 | 自兹 |
| --- | --- | --- | --- | --- |
| **`stream`** | `[VolumeStream](https://npmcn.com/package/%40capawesome/capacitor-volume/#readme-volumestream)` | 音流取出音量为用. 只能从Android上找到. | `VolumeStream.Music` | 0.1.0 (中文(简体) ) |

#### 正在观看结果

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`watching`** | `boolean` | 硬件音量按钮是否正在被监视 . | 0.1.0 (中文(简体) ) |

#### 设置组合选项

| Prop | 类型 | 说明 | 默认 | 自兹 |
| --- | --- | --- | --- | --- |
| **`stream`** | `[VolumeStream](https://npmcn.com/package/%40capawesome/capacitor-volume/#readme-volumestream)` | 音流来设出音量. 只能从Android上找到. | `VolumeStream.Music` | 0.1.0 (中文(简体) ) |
| **`volume`** | `number` | 设定为值之间的音量级别 `0` 财务报告和审定财务报表 `1`。 。 。 . |  | 0.1.0 (中文(简体) ) |

#### 开始观察选项

| Prop | 类型 | 说明 | 默认 | 自兹 |
| --- | --- | --- | --- | --- |
| **`suppressVolumeChange`** | `boolean` | 是否在观看时按下硬件音量按钮时保持音量级别不变 。 在Android上,卷关键事件被消耗,这样系统就不会应用卷变化或显示卷面板. 在iOS上,每个按钮按下后立即重置音量级别并隐藏系统音量指示器. 如果音量级别接近最小或最大,则被压入一个值,从中仍然可以检测出两个按钮. 观看停止时会恢复原音量级别. | `false` | 0.1.0 (中文(简体) ) |

#### 插件听筒

| Prop | 类型 |
| --- | --- |
| **`remove`** | `() => Promise<void>` |

#### 音量按钮预览活动

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`direction`** | `[Direction](https://npmcn.com/package/%40capawesome/capacitor-volume/#readme-direction)` | 按下硬件音量按钮的方向 . | 0.1.0 (中文(简体) ) |

#### 音量按钮释放事件

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`direction`** | `[Direction](https://npmcn.com/package/%40capawesome/capacitor-volume/#readme-direction)` | 发布硬件音量按钮的方向. | 0.2.0 (中文(简体) ) |

#### 变化事件

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`volume`** | `number` | 新量级作为值介于 `0` 财务报告和审定财务报表 `1`。 。 。 . | 0.1.0 (中文(简体) ) |

### 类型异名

#### 方向

硬件音量按钮的方向 .

-   `up`:音量向上按钮.
-   `down`:音量下调按钮.

`'down' | 'up'`

### 数字

#### 卷轴

| 成员 | 数值 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`Alarm`** | `'ALARM'` | 用于警报的音频流. | 0.1.0 (中文(简体) ) |
| **`Music`** | `'MUSIC'` | 音乐与媒体回放的音频流. | 0.1.0 (中文(简体) ) |
| **`Notification`** | `'NOTIFICATION'` | 通知的音频流 . | 0.1.0 (中文(简体) ) |
| **`Ring`** | `'RING'` | 电话铃的音频流. | 0.1.0 (中文(简体) ) |
| **`System`** | `'SYSTEM'` | 系统的声音流. | 0.1.0 (中文(简体) ) |
| **`VoiceCall`** | `'VOICE_CALL'` | 电话的音频流. | 0.1.0 (中文(简体) ) |

## 音量控制

在获取和设定音量时,要铭记以下平台差异:

-   **机器人**: 音量可以被读取并设定每个音频流(参见: `stream` 选项)。 如果 Do Not Distrib 活动,改变环的体积,通知或系统流需要 Do Not Distrib 访问. 如果没有这种访问,电话就与 `DO_NOT_DISTURB_ACCESS_REQUIRED` 错误代码 。 您可以使用 [`ACTION_NOTIFICATION_POLICY_ACCESS_SETTINGS`](https://developer.android.com/reference/android/provider/Settings#ACTION_NOTIFICATION_POLICY_ACCESS_SETTINGS) 意图,例如: [应用程序启动器](https://capacitorjs.com/docs/apis/app-launcher) 插件 .
-   **iOS系统**:没有公共API直接设置系统音量. 因此插件使用隐藏的系统音量视图来改变介质音量,而介质音量是唯一能够被读取并设定的音量. 这个 `stream` 选项被忽略.

## 音量按钮监视

在观看硬件音量按钮时注意以下平台差异:

-   **机器人**:音量关键事件被网页视图所截取,因此按钮按键只在应用程序处于前景时被检测出. 与 `suppressVolumeChange` 选项,关键事件被消耗,使音量保持不变,防止系统音量面板出现.
-   **iOS系统**:按钮按出自媒体音量的变化,因此按钮按出只在应用程序处于前台时被检测出. 没有 `suppressVolumeChange` 选项,当音量达到最小或最大时,无法检测出按压。 启用选项后,每次按下后会立即重置音量(如果需要的话会从边上滑出),系统音量指示器被隐藏,在观看停止时会恢复原音量. 请注意,在观看时也报告其他来源(如控制中心)的体积变化.

## 财务问题

### 此插件与其他类似插件有何不同?

它将体积控制与硬件按钮事件合并在一个统一的API中——一种自然地适合iOS,两者都依赖于相同的基础系统机械. 它在Android上增加了每个流控并处理iOS卷指标抑制,全部通过一个完全打出,积极维护的包来进行,所以一个单一的依赖覆盖了整个卷子故事.

### 此插件支持哪些平台 ?

插件可以在Android和iOS上找到. 在网络上,所有方法都否认未执行.

### 为什么 `stream` 在 iOS 上忽略选项吗 ?

在iOS上,没有公共API直接设置系统音量. 因此插件使用隐藏的系统卷视图来改变介质卷,而介质卷是唯一可以被读取并设置在iOS上的卷. 这个 `stream` 选项仅在Android上支持,参见 [音量控制](https://npmcn.com/package/%40capawesome/capacitor-volume/#readme-volume-control) 详细情况.

### 为什么 `setVolume` 与 `DO_NOT_DISTURB_ACCESS_REQUIRED` 错误代码 ?

在Android上,改变环的体积,通知或系统流,而Do Not Distrib活动时需要Do Not Distrib访问. 您可以使用 `ACTION_NOTIFICATION_POLICY_ACCESS_SETTINGS` 意图,例如使用 App 启动器插件,参见 [音量控制](https://npmcn.com/package/%40capawesome/capacitor-volume/#readme-volume-control) 详细情况.

### 为什么没有检测到音量按钮?

这个 `volumeButtonPressed` 事件只在观察时被释放,所以请确认您已拨打 `startWatching(...)` 先说 在两个平台上,仅在应用程序处于前景时检测出按键. 在iOS上,当音量达到最小或最大时,压力也无法被检测出,除非 `suppressVolumeChange` 选项已启用,参见 [音量按钮监视](https://npmcn.com/package/%40capawesome/capacitor-volume/#readme-volume-button-watching) 详细情况.

### 这有什么 `suppressVolumeChange` 选项可以吗?

启用此选项后, 在观看时按下硬件音量按钮不会改变音量, 而系统音量指示器会隐藏 。 在Android上,大量的关键事件被消耗. 在iOS上,每个按钮按下后立即重置音量级别,在观看停止时恢复原音量级别.

### 我能用这个插件吗? 有Ionic、React、Vue或Angular?

是的,插件是框架不可知的。 它在任意网络框架的Capacitor app中工作,包括有Angular,React,或Vue的Ionic,以及平版JavaScript等项目.

## 相关插件

-   [音频会话](https://capawesome.io/docs/sdks/capacitor/audio-session/): 配置并观察iOS音频会话.
-   [媒体会议](https://capawesome.io/docs/sdks/capacitor/media-session/): 与媒体控制器,音量键和媒体按钮进行交互.
-   [静态](https://capawesome.io/docs/sdks/capacitor/silent-mode/):检测设备是否处于无声模式.

## 通讯

随时更新有关卡帕韦索姆、Capacitor和Ionic生态系统的最新消息和最新消息,因为我们 [《卡帕索克通讯》](https://cloud.capawesome.io/newsletter/)。 。 。 .

## 更改日志

见 [变动情况](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/volume/CHANGELOG.md)。 。 。 .

## 许可证

见 [自由主义](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/volume/LICENSE)。 。 。 .

## 常见问题

### @capawesome/capacitor-volume 是什么？

Capacitor插件来控制音量并观察Android和iOS上的硬件音量按钮\.

### 如何安装 @capawesome/capacitor-volume？

在项目目录运行 npm install @capawesome/capacitor-volume，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@capacitor/core（\>=8\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @capawesome/capacitor-volume 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @capawesome/capacitor-volume 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @capawesome/capacitor-volume 可以商用吗？

@capawesome/capacitor-volume 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @capawesome/capacitor-volume 的下载量有多少？

根据 npm 官方下载统计，@capawesome/capacitor-volume 在 2026/10/09 – 2026/11/07 这 30 天内被下载 3,646 次，日均约 122 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @capawesome/capacitor-volume 还在维护吗？

最新版本 0\.1\.3 发布于 2026/09/02（2 个月前）；至今共发布 5 个版本，其中过去 12 个月发布了 5 个；首次发布于 2026/07/07。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。