# @exodus/react-native-sound 中文文档

规范地址：https://npmcn.com/package/%40exodus/react-native-sound/

版本：0\.13\.0-exodus\.2
npm 元数据更新时间：2026-10-06T21:03:02.282Z
中文译文更新时间：2026-11-14T04:14:32.785Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：55.2 kB，14 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：react-native \>=0\.8\.0
- 首次发布：2019-06-30T19:03:37.599Z
- 最新版本发布：2026-04-29T21:44:45.102Z
- 近 30 天下载量：10623（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：4（近 12 个月 1 个）

## 中文简介

在iOS、Android和Windows上播放声音剪辑的原生模块

## 安装

```sh
npm install @exodus/react-native-sound
```

也可以使用：`pnpm add @exodus/react-native-sound`、`yarn add @exodus/react-native-sound`、`bun add @exodus/react-native-sound`

## README

# 反应-原声

反应原生模块用于在iOS,Android,和Windows上播放声音剪辑.

'注:反应-内生-声不支持流出". 更多信息见#353. 当然,如果有人愿意的话,我们会欢迎公关.

## 特性矩阵

| 特性 | iOS系统 | 机器人 | 窗口 |
| --- | --- | --- | --- |
| 从应用程序捆绑中装入声音 | ✓ | ✓ | ✓ |
| 从其他目录装入声音 | ✓ | ✓ | ✓ |
| 从网络装入声音 | ✓ | ✓ |  |
| 播放声音 | ✓ | ✓ | ✓ |
| 回放补全调用 | ✓ | ✓ | ✓ |
| 暂停 | ✓ | ✓ | ✓ |
| 继续 | ✓ | ✓ | ✓ |
| 停下来 | ✓ | ✓ | ✓ |
| 重设 |  | ✓ |  |
| 释放资源 | ✓ | ✓ | ✓ |
| 获取持续时间 | ✓ | ✓ | ✓ |
| 获取频道数 | ✓ |  |  |
| 获取/设置音量 | ✓ | ✓ | ✓ |
| 获取系统音量 | ✓ | ✓ |  |
| 设定系统音量 |  | ✓ |  |
| 获取/设置平板 | ✓ |  |  |
| 获取/设置循环 | ✓ | ✓ | ✓ |
| 获取/ 设定当前时间 | ✓ | ✓ | ✓ |
| 设置速度 | ✓ | ✓ |  |

## 安装

首先从您的应用目录安装 npm 包 :

```javascript
npm install react-native-sound --save
```

然后自动链接它使用 :

```javascript
react-native link react-native-sound
```

### 手动安装注释

详情请参见维基百科 [https://github.com/zmxv/resact-native-sound/wiki/ 安装](https://github.com/zmxv/react-native-sound/wiki/Installation)

## 辅助反应声

-   用于反应- 原声开发者 [![Gitter chat](https://badges.gitter.im/gitterHQ/services.png)](https://gitter.im/react-native-sound/developers)
-   帮助使用反应- 原声 [![Gitter chat](https://badges.gitter.im/gitterHQ/services.png)](https://gitter.im/react-native-sound/Help)

## Demo项目

[https://github.com/zmxv/resact-native-sound-demo (英语)](https://github.com/zmxv/react-native-sound-demo)

## 玩家

![](https://github.com/benevbright/react-native-sound-playerview/blob/master/docs/demo.gif?raw=true)

[https://github.com/benevbright/ react-native-相声-玩家观](https://github.com/benevbright/react-native-sound-playerview)

## 基本用途

首先,你需要添加音频文件到您的项目中.

-   Android: 在目录下保存您的声音剪辑文件 `android/app/src/main/res/raw`。请注意,此目录中的文件必须是小写并下划线(例如我的 file name.mp3),子目录不被Android支持.
-   iOS: 打开 Xcode 并添加到工程中的声音文件( 右键单击工程并选择) `Add Files to [PROJECTNAME]`(中文(简体) )

```js
// Import the react-native-sound module
var Sound = require('react-native-sound');

// Enable playback in silence mode
Sound.setCategory('Playback');

// Load the sound file 'whoosh.mp3' from the app bundle
// See notes below about preloading sounds within initialization code below.
var whoosh = new Sound('whoosh.mp3', Sound.MAIN_BUNDLE, (error) => {
  if (error) {
    console.log('failed to load the sound', error);
    return;
  }
  // loaded successfully
  console.log('duration in seconds: ' + whoosh.getDuration() + 'number of channels: ' + whoosh.getNumberOfChannels());

  // Play the sound with an onEnd callback
  whoosh.play((success) => {
    if (success) {
      console.log('successfully finished playing');
    } else {
      console.log('playback failed due to audio decoding errors');
    }
  });
});

// Reduce the volume by half
whoosh.setVolume(0.5);

// Position the sound to the full right in a stereo field
whoosh.setPan(1);

// Loop indefinitely until stop() is called
whoosh.setNumberOfLoops(-1);

// Get properties of the player instance
console.log('volume: ' + whoosh.getVolume());
console.log('pan: ' + whoosh.getPan());
console.log('loops: ' + whoosh.getNumberOfLoops());

// Seek to a specific point in seconds
whoosh.setCurrentTime(2.5);

// Get the current playback point in seconds
whoosh.getCurrentTime((seconds) => console.log('at ' + seconds));

// Pause the sound
whoosh.pause();

// Stop the sound and rewind to the beginning
whoosh.stop(() => {
  // Note: If you want to play a sound after stopping and rewinding it,
  // it is important to call play() in a callback.
  whoosh.play();
});

// Release the audio player resource
whoosh.release();
```

## 页:1

-   为了尽量减少回放延迟, 您可能想要在不调用的情况下预装一个声音文件 `play()` (例如:. `var s = new Sound(...);`在应用初始化期间。 这也有助于避免种族条件 `play()` 在装入声音完成之前,可以调用,这导致没有声音,但没有出错,因为装入仍在处理中.
-   可以同时播放多个声音文件. 在引擎盖下,这个模块使用 `AVAudioSessionCategoryAmbient` 在iOS上混合声音.
-   你可以重用一个 `Sound` 例如,多次重播.
-   在iOS上,模块包接 `AVAudioPlayer` 支持 Aac, aiff, mp3, wav 等。 支持格式的完整列表可见于 [https://developer.apple.com/library/content/documentation/MusicAudio/Conceptual/CoreAudio Overview/支持的AudioFormatsMacOSX/支持的AudioFormatsMacOSX.html 互联网档案馆的存檔,存档日期2011-12-20](https://developer.apple.com/library/content/documentation/MusicAudio/Conceptual/CoreAudioOverview/SupportedAudioFormatsMacOSX/SupportedAudioFormatsMacOSX.html)
-   在Android上,模块包裹 `android.media.MediaPlayer`。支持格式的完整列表可见于 [https://developer.android.com/guide/topics/media/media-formats.html 互联网档案馆的存檔,存档日期2014-12-21](https://developer.android.com/guide/topics/media/media-formats.html)
-   在Android上,绝对路径可以从"/sdcard/"开始. 所以,如果要在下載資料夾上访问一个叫"my sound.mp3"的声音,绝对路径会是:"/sdcard/Downloads/my sound.mp3".
-   举例来说,你可能会连锁非更好的电话, `sound.setVolume(.5).setPan(.5).play()`。 。 。 .

## 常见问题

### @exodus/react-native-sound 是什么？

在iOS、Android和Windows上播放声音剪辑的原生模块

### 如何安装 @exodus/react-native-sound？

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

### @exodus/react-native-sound 支持 TypeScript 吗？

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

### @exodus/react-native-sound 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @exodus/react-native-sound 可以商用吗？

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

### @exodus/react-native-sound 的下载量有多少？

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

### @exodus/react-native-sound 还在维护吗？

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