# @capacitor-community/native-audio 中文文档

规范地址：https://npmcn.com/package/%40capacitor-community/native-audio/

版本：8\.0\.0
npm 元数据更新时间：2026-10-23T21:47:59.066Z
中文译文更新时间：2026-11-09T03:11:23.368Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40capacitor-community/native-audio
原文对照：https://npmcn.com/package/%40capacitor-community/native-audio/?lang=original
项目主页：https://github.com/capacitor-community/native-audio#readme
源码仓库：https://github.com/capacitor-community/native-audio

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

- 包体积（解压后）：108 kB，32 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@capacitor/core \>=8\.0\.0
- 首次发布：2020-06-23T17:14:45.686Z
- 最新版本发布：2025-12-30T07:37:29.034Z
- 近 30 天下载量：58128（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：16（近 12 个月 1 个）

## 中文简介

本地音频引擎的本地插件

## 安装

```sh
npm install @capacitor-community/native-audio
```

也可以使用：`pnpm add @capacitor-community/native-audio`、`yarn add @capacitor-community/native-audio`、`bun add @capacitor-community/native-audio`

## README

  
![](https://user-images.githubusercontent.com/236501/85893648-1c92e880-b7a8-11ea-926d-95355b8175c7.png)

### 原声

**`@capacitor-community/native-audio`**

QQ 电容插件, 用于在本地播放声音 .

![](https://img.shields.io/maintenance/yes/2025?style=flat-square) [![](https://img.shields.io/github/actions/workflow/status/capacitor-community/native-audio/ci.yml?branch=master&style=flat-square)](https://github.com/capacitor-community/native-audio/actions?query=workflow%3A%22CI%22) [![](https://img.shields.io/npm/l/@capacitor-community/native-audio?style=flat-square)](https://www.npmjs.com/package/@capacitor-community/native-audio)  
[![](https://img.shields.io/npm/dw/@capacitor-community/native-audio?style=flat-square)](https://www.npmjs.com/package/@capacitor-community/native-audio) [![](https://img.shields.io/npm/v/@capacitor-community/native-audio?style=flat-square)](https://www.npmjs.com/package/@capacitor-community/native-audio) [![](https://img.shields.io/badge/all%20contributors-2-orange?style=flat-square)](https://npmcn.com/package/%40capacitor-community/native-audio/#readme-contributors-)

## 维护者

| 维护者 | GitHub 图像 | 社会 |
| --- | --- | --- |
| 马克西姆·巴苏耶夫 | [bazuka5801 (英语)](https://github.com/bazuka5801) | [电报](https://t.me/bazuka5801) |

## 演示

[![YouTube Example](https://img.youtube.com/vi/XpUGlWWtwHs/0.jpg)](https://www.youtube.com/watch?v=XpUGlWWtwHs)

## 筹备

特定平台文件夹中的所有音频位置

安道尔: `android/app/src/assets`

iOS: (英语) `ios/App/App/sounds`

网络 : `assets/sounds`

## 安装

用于 npm

```bash
npm install @capacitor-community/native-audio
```

用纱线

```bash
yarn add @capacitor-community/native-audio
```

同步本地文件

```bash
npx cap sync
```

在iOS,Android和Web上,不需要进一步的步骤.

## 配置

此插件不需要配置 .

## 支持的方法

| 名称 | 机器人 | iOS系统 | 网页 |
| --- | --- | --- | --- |
| 配置 | ✅ | ✅ | ❌ |
| 预装 | ✅ | ✅ | ✅ |
| 播放 | ✅ | ✅ | ✅ |
| 暂停 | ✅ | ✅ | ✅ |
| 恢复 | ✅ | ✅ | ✅ |
| 循环 | ✅ | ✅ | ✅ |
| 停下来 | ✅ | ✅ | ✅ |
| 卸货 | ✅ | ✅ | ✅ |
| 设置 | ✅ | ✅ | ✅ |
| 获取期限 | ✅ | ✅ | ✅ |
| 获取当前时间 | ✅ | ✅ | ✅ |
| 正在播放 | ✅ | ✅ | ✅ |

## 使用量

[示例存储库](https://github.com/bazuka5801/native-audio-example) 或 另一个完整的 Ionic/Angular 应用程序可以显示每个插件方法 **示例应用程序** 目录

```typescript
import {NativeAudio} from '@capacitor-community/native-audio'


/**
 * This method will load more optimized audio files for background into memory.
 * @param assetPath - relative path of the file or absolute url (file://)
 *        assetId - unique identifier of the file
 *        audioChannelNum - number of audio channels
 *        isUrl - pass true if assetPath is a `file://` url
 * @returns void
 */
NativeAudio.preload({
    assetId: "fire",
    assetPath: "fire.mp3",
    audioChannelNum: 1,
    isUrl: false
});

/**
 * This method will play the loaded audio file if present in the memory.
 * @param assetId - identifier of the asset
 * @param time - (optional) play with seek. example: 6.0 - start playing track from 6 sec
 * @returns void
 */
NativeAudio.play({
    assetId: 'fire',
    // time: 6.0 - seek time
});

/**
 * This method will loop the audio file for playback.
 * @param assetId - identifier of the asset
 * @returns void
 */
NativeAudio.loop({
  assetId: 'fire',
});


/**
 * This method will stop the audio file if it's currently playing.
 * @param assetId - identifier of the asset
 * @returns void
 */
NativeAudio.stop({
  assetId: 'fire',
});

/**
 * This method will unload the audio file from the memory.
 * @param assetId - identifier of the asset
 * @returns void
 */
NativeAudio.unload({
  assetId: 'fire',
});

/**
 * This method will set the new volume for a audio file.
 * @param assetId - identifier of the asset
 *        volume - numerical value of the volume between 0.1 - 1.0
 * @returns void
 */
NativeAudio.setVolume({
  assetId: 'fire',
  volume: 0.4,
});

/**
 * this method will get the duration of an audio file.
 * only works if channels == 1
 */
NativeAudio.getDuration({
  assetId: 'fire'
})
.then(result => {
  console.log(result.duration);
})

/**
 * this method will get the current time of a playing audio file.
 * only works if channels == 1
 */
NativeAudio.getCurrentTime({
  assetId: 'fire'
});
.then(result => {
  console.log(result.currentTime);
})

/**
 * This method will return false if audio is paused or not loaded.
 * @param assetId - identifier of the asset
 * @returns {isPlaying: boolean}
 */
NativeAudio.isPlaying({
  assetId: 'fire'
})
.then(result => {
  console.log(result.isPlaying);
})
```

## API 密码

### 配置(...)

```typescript
configure(options: ConfigureOptions) => Promise<void>
```

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[ConfigureOptions](https://npmcn.com/package/%40capacitor-community/native-audio/#readme-configureoptions)` |

* * *

### 预装(...)

```typescript
preload(options: PreloadOptions) => Promise<void>
```

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[PreloadOptions](https://npmcn.com/package/%40capacitor-community/native-audio/#readme-preloadoptions)` |

* * *

### 播放(...)

```typescript
play(options: { assetId: string; time?: number; }) => Promise<void>
```

| 参数 | 类型 |
| --- | --- |
| **`options`** | `{ assetId: string; time?: number; }` |

* * *

### 暂停(...)

```typescript
pause(options: { assetId: string; }) => Promise<void>
```

| 参数 | 类型 |
| --- | --- |
| **`options`** | `{ assetId: string; }` |

* * *

### 恢复(...)

```typescript
resume(options: { assetId: string; }) => Promise<void>
```

| 参数 | 类型 |
| --- | --- |
| **`options`** | `{ assetId: string; }` |

* * *

### 循环(...)

```typescript
loop(options: { assetId: string; }) => Promise<void>
```

| 参数 | 类型 |
| --- | --- |
| **`options`** | `{ assetId: string; }` |

* * *

### 停止(...)

```typescript
stop(options: { assetId: string; }) => Promise<void>
```

| 参数 | 类型 |
| --- | --- |
| **`options`** | `{ assetId: string; }` |

* * *

### 卸载(...)

```typescript
unload(options: { assetId: string; }) => Promise<void>
```

| 参数 | 类型 |
| --- | --- |
| **`options`** | `{ assetId: string; }` |

* * *

### 设置卷 (...)

```typescript
setVolume(options: { assetId: string; volume: number; }) => Promise<void>
```

| 参数 | 类型 |
| --- | --- |
| **`options`** | `{ assetId: string; volume: number; }` |

* * *

### 获取当前时间(...)

```typescript
getCurrentTime(options: { assetId: string; }) => Promise<{ currentTime: number; }>
```

| 参数 | 类型 |
| --- | --- |
| **`options`** | `{ assetId: string; }` |

**回返情况:** `Promise<{ currentTime: number; }>`

* * *

### 获取期限(...)

```typescript
getDuration(options: { assetId: string; }) => Promise<{ duration: number; }>
```

| 参数 | 类型 |
| --- | --- |
| **`options`** | `{ assetId: string; }` |

**回返情况:** `Promise<{ duration: number; }>`

* * *

### 正在播放(...)

```typescript
isPlaying(options: { assetId: string; }) => Promise<{ isPlaying: boolean; }>
```

| 参数 | 类型 |
| --- | --- |
| **`options`** | `{ assetId: string; }` |

**回返情况:** `Promise<{ isPlaying: boolean; }>`

* * *

### 添加倾听器( “ 完整 ” ,...)

```typescript
addListener(eventName: 'complete', listenerFunc: (event: { assetId: string; }) => void) => Promise<PluginListenerHandle>
```

监听已完成的资产播放事件

| 参数 | 类型 |
| --- | --- |
| **`eventName`** | `'complete'` |
| **`listenerFunc`** | `(event: { assetId: string; }) => void` |

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

**自:** 第5.0.1条

* * *

### 接口

#### 配置选项

| Prop | 类型 | 说明 | 默认 |
| --- | --- | --- | --- |
| **`fade`** | `boolean` | 表示是否要淡出音频. | `false` |
| **`focus`** | `boolean` | 显示是否禁用混合音频 . | `false` |

#### 预装选项

| Prop | 类型 |
| --- | --- |
| **`assetPath`** | `string` |
| **`assetId`** | `string` |
| **`volume`** | `number` |
| **`audioChannelNum`** | `number` |
| **`isUrl`** | `boolean` |

#### 插件听筒

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

## 常见问题

### @capacitor-community/native-audio 是什么？

本地音频引擎的本地插件

### 如何安装 @capacitor-community/native-audio？

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

### @capacitor-community/native-audio 支持 TypeScript 吗？

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

### @capacitor-community/native-audio 支持 ESM 还是 CommonJS？

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

### @capacitor-community/native-audio 可以商用吗？

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

### @capacitor-community/native-audio 的下载量有多少？

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

### @capacitor-community/native-audio 还在维护吗？

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