# @ascendtis/react-native-voice-to-text 中文文档

规范地址：https://npmcn.com/package/%40ascendtis/react-native-voice-to-text/

版本：0\.4\.2
npm 元数据更新时间：2026-10-06T06:48:45.406Z
中文译文更新时间：2026-11-06T22:13:40.935Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：97.3 kB，43 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：react \*，react-native \*
- 首次发布：2025-05-29T08:23:13.122Z
- 最新版本发布：2026-10-06T06:48:45.238Z
- 近 30 天下载量：3281（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 3 个）

## 中文简介

这可以用来在设备中将语音实时转换为文本

## 安装

```sh
npm install @ascendtis/react-native-voice-to-text
```

也可以使用：`pnpm add @ascendtis/react-native-voice-to-text`、`yarn add @ascendtis/react-native-voice-to-text`、`bun add @ascendtis/react-native-voice-to-text`

## README

# @ ascendtis/ react-native-voice-to-text (英语)

[![npm version](https://img.shields.io/npm/v/@ascendtis/react-native-voice-to-text)](https://www.npmjs.com/package/@ascendtis/react-native-voice-to-text) [![npm downloads](https://img.shields.io/npm/dw/@ascendtis/react-native-voice-to-text)](https://www.npmjs.com/package/@ascendtis/react-native-voice-to-text) [![license](https://img.shields.io/npm/l/@ascendtis/react-native-voice-to-text)](https://www.npmjs.com/package/@ascendtis/react-native-voice-to-text)

使用iOS和Android的本地语音识别能力实时将语音转换为文本.

这个包裹是未保存的 [`react-native-voice-to-text`](https://www.npmjs.com/package/react-native-voice-to-text),在完全iOS支持下重建,新架构(TurboModule)兼容性,并持续维护.

## 特征

-   IOS上的原生语音识别(`SFSpeechRecognizer`)和Android(英语:`SpeechRecognizer`(中文(简体) )
-   用户说话时实时部分结果
-   带有信心分数的最后抄写(Android)
-   体积水平检测(Android)
-   多语言支持:查询、列表和切换识别语言
-   新建筑已准备就绪( 有代码的 TurboModule)
-   以类型定义写入脚本

## 所需资源

| 平台 | 最低 |
| --- | --- |
| iOS系统 | 第15.1条 |
| 机器人 | API 24 (Android 7.0) (英语) |
| 原生反应 | 0.78+(建造和试验,对照0.78.1) |

> **说明:** 此软件包包含本地代码, 因此无法在 **博览去**使用一个 [发展](https://docs.expo.dev/develop/development-builds/introduction/) 或者一个赤裸裸的反射原生项目.

## 安装

```sh
npm install @ascendtis/react-native-voice-to-text
```

或者说

```sh
yarn add @ascendtis/react-native-voice-to-text
```

该软件包在两个平台上自动链接. 在iOS上,安装CocoaPods依赖:

```sh
cd ios && pod install
```

然后重建您的应用程序, 以便本地模块注册 .

## 权限

### iOS系统

将以下密钥添加到您的 `Info.plist`数字 :

```xml
<key>NSMicrophoneUsageDescription</key>
<string>This app needs access to your microphone for speech recognition</string>
<key>NSSpeechRecognitionUsageDescription</key>
<string>This app needs access to speech recognition to convert your voice to text</string>
```

### 机器人

向您添加以下权限 `AndroidManifest.xml`数字 :

```xml
<uses-permission android:name="android.permission.RECORD_AUDIO" />
```

对于Android 6.0+(API 23),您还需要在运行时请求权限:

```js
import { Platform, PermissionsAndroid } from 'react-native';

// Request microphone permission
async function requestMicrophonePermission() {
  if (Platform.OS !== 'android') return true;

  try {
    const granted = await PermissionsAndroid.request(
      PermissionsAndroid.PERMISSIONS.RECORD_AUDIO,
      {
        title: 'Microphone Permission',
        message: 'This app needs access to your microphone for speech recognition',
        buttonPositive: 'OK',
      }
    );
    return granted === PermissionsAndroid.RESULTS.GRANTED;
  } catch (err) {
    console.warn(err);
    return false;
  }
}
```

## 使用量

```js
import React, { useEffect, useState } from 'react';
import { Button, Text, View } from 'react-native';
import {
  addEventListener,
  destroy,
  startListening,
  stopListening,
} from '@ascendtis/react-native-voice-to-text';

export default function SpeechToText() {
  const [result, setResult] = useState('');
  const [isListening, setIsListening] = useState(false);

  useEffect(() => {
    const subscriptions = [
      addEventListener('onSpeechStart', () => setIsListening(true)),
      addEventListener('onSpeechEnd', () => setIsListening(false)),
      addEventListener('onSpeechResults', (event) => {
        setResult(event.value ?? '');
      }),
      addEventListener('onSpeechError', (event) => {
        console.error('Speech recognition error:', event.message);
        setIsListening(false);
      }),
    ];

    return () => {
      subscriptions.forEach((subscription) => subscription.remove());
      destroy();
    };
  }, []);

  const toggleListening = async () => {
    try {
      if (isListening) {
        await stopListening();
      } else {
        setResult('');
        await startListening();
      }
    } catch (error) {
      console.error(error);
    }
  };

  return (
    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
      <Text>{result || 'Say something...'}</Text>
      <Button
        title={isListening ? 'Stop Listening' : 'Start Listening'}
        onPress={toggleListening}
      />
    </View>
  );
}
```

### 切换识别语言

```js
import {
  getSupportedLanguages,
  setRecognitionLanguage,
} from '@ascendtis/react-native-voice-to-text';

const languages = await getSupportedLanguages(); // e.g. ['en-US', 'en-GB', 'fr-FR', ...]
const success = await setRecognitionLanguage('en-GB');
```

## API 参考

所有函数都命名为软件包的导出. 如果本地模块不可用(例如应用程序安装后没有重建),或 `pod install` ,每个函数都会出现描述性错误,解释如何修复设置.

### 方法

| 方法 | 说明 | 返回类型 |
| --- | --- | --- |
| `startListening()` | 开始语音识别 | `Promise<string>` |
| `stopListening()` | 停止语音识别 | `Promise<string>` |
| `destroy()` | 清理语音识别资源 | `Promise<string>` |
| `getRecognitionLanguage()` | 获取当前识别语言 | `Promise<string>` |
| `setRecognitionLanguage(languageTag)` | 设置识别语言( 如. `'en-US'`(中文(简体) ) | `Promise<boolean>` |
| `isRecognitionAvailable()` | 检查设备是否有语音识别功能 | `Promise<boolean>` |
| `getSupportedLanguages()` | 获取支持的语言代码列表 | `Promise<string[]>` |
| `addEventListener(eventName, handler)` | 订阅事件; 调用 `.remove()` 返回的订阅 | `EventSubscription` |
| `removeAllListeners(eventName)` | 删除事件的所有听众 | `void` |

### 活动

订阅 `addEventListener('onSpeechResults', handler)` 包括: 事件名称是简单的字符串 .

| 活动 | 平台 | 有效载荷 |
| --- | --- | --- |
| `onSpeechStart` | iOS, Android 软件 | \- (承认开始) |
| `onSpeechBegin` | 机器人 | \- (用户开始说话) |
| `onSpeechEnd` | iOS, Android 软件 | `{ message?: string }` |
| `onSpeechError` | iOS, Android 软件 | `{ code: number, message: string }` —— 说 `code` 是针对平台的(iOS上的负值, `SpeechRecognizer.ERROR_*` android上数值) |
| `onSpeechResults` | iOS, Android 软件 | `{ value: string, results?: { transcriptions: Array<{ text: string, confidence: number }> } }` —— 说 `results` 仅为Android |
| `onSpeechPartialResults` | iOS, Android 软件 | `{ value: string, results?: { transcriptions: Array<{ text: string }> } }` —— 说 `results` 仅为Android |
| `onSpeechVolumeChanged` | 机器人 | `{ value: number }` (RMS 在dB中发声) |
| `onSpeechAudioBuffer` | 机器人 | `{ buffer: string }` (Base64-编码原始音频) |
| `onSpeechEvent` | 机器人 | `{ eventType: number, ... }` (特定服务活动) |

## 解决问题

**`The native module "VoiceToText" is not available`** 土著方面没有登记。 记得跑 `pod install` 在iOS上,并在安装了软件包后重建了应用程序. 博览会Go没有这个模块——使用一个开发建筑. 自 v. 4. 0 起, 此显示为调用时的描述错误, 而不是在导入时崩溃 .

**语音识别对 iOS 模拟器无效** 模拟支持 `SFSpeechRecognizer` 不同Xcode/模拟器版本不同. 总是在物理设备上验证语音特性.

**Android 构建失败 `Cannot add extension with name 'kotlin'`** 由Android Gradle插件9 注册内置的克特林支持导致. 固定在v. 4.1——升级至 `@ascendtis/react-native-voice-to-text@0.4.1` 或后会.

**Android 运行时出错(`should be used only from the application main thread`, (中文(简体) ), `Cannot convert argument` 编号 : `ArrayList`(中文(简体) )** 两者均固定在0.3.x释放中. 如果您在旧版本上, 则升级 .

## 捐款

欢迎提问和拉票请求! 见 [问题跟踪器](https://github.com/sufyan297/react-native-voice-to-text/issues)。 。 。 .

```sh
corepack yarn            # install dependencies (Yarn 3 via corepack)
corepack yarn prepare    # build lib/ with react-native-builder-bob
corepack yarn test       # run the Jest test suite
corepack yarn typecheck  # TypeScript
corepack yarn lint       # ESLint
corepack yarn example    # run the example app (react-native run-android / run-ios)
```

如果Yarn报告锁文件已过期, 请运行 `corepack yarn install` 一次第一个.

## 许可证

麻省理工学院

## 贷项

这个软件包是连续叉 [`react-native-voice-to-text`](https://www.npmjs.com/package/react-native-voice-to-text) 以 [阿布哈亚·库马尔·萨胡](https://github.com/abhaya-kumar-sahoo) (仅Android,不再维护). 感谢伟大的起点.

脚手架与 [创建- 反应- 本土- 图书馆](https://github.com/callstack/create-react-native-library)。 。 。 .

## 常见问题

### @ascendtis/react-native-voice-to-text 是什么？

这可以用来在设备中将语音实时转换为文本

### 如何安装 @ascendtis/react-native-voice-to-text？

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

### @ascendtis/react-native-voice-to-text 支持 TypeScript 吗？

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

### @ascendtis/react-native-voice-to-text 支持 ESM 还是 CommonJS？

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

### @ascendtis/react-native-voice-to-text 可以商用吗？

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

### @ascendtis/react-native-voice-to-text 的下载量有多少？

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

### @ascendtis/react-native-voice-to-text 还在维护吗？

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