参考文档 :

• Flutter 官方文档 : https://docs.flutter.dev/install/quick
• 使用出现网络问题 , 参考 在中国网络环境下使用 Flutter 文档 ;
• 使用 VS Code 开发 Flutter 环境安装 : https://docs.flutter.cn/install/with-vs-code
• VS Code 安装 : https://code.visualstudio.com/docs/setup/setup-overview

前言

随着移动应用交互体验的不断升级 , 语音播报 ( Text To Speech , TTS ) 功能 在 导航类、阅读类、工具类 App 中的应用越来越广泛 ;

在 Flutter 跨平台开发中 , 我们可以 通过成熟的插件快速实现 TTS 能力 , 同时支持 Android、iOS、Web 等多端运行 ;

本文就详细介绍 Flutter 中 TTS 功能的集成方案、核心 API 使用、参数配置以及常见踩坑点 ;

---

一、Flutter TTS 方案概述

---

1、flutter_tts 插件方案简介

目前 Flutter 生态中最主流的 TTS 实现方案是 flutter_tts 插件 , 它 基于各平台系统原生的 TTS 引擎封装 , 无需额外接入第三方语音服务 , 开箱即用 , 支持离线播报 , 该插件有如下特性 :

• 支持 Android、iOS、macOS、Web、Windows 多平台
• 可调节语速、音调、音量
• 支持多语言 / 多音色切换
• 提供播放、暂停、停止、继续等完整控制能力
• 支持播报进度、完成、错误等状态回调
• 支持队列模式 , 可连续播报多段文本

2、其它备选方案

备选方案 :

• flutter_tts 插件 : 系统原生 TTS , 免费无限制 , 推荐首选 ;
• 百度 / 讯飞 / 阿里云语音 SDK : 需单独集成 , 音色更丰富 , 支持云端合成 , 适合对音质要求高的场景 ;
• tts_flutter 插件 : 轻量封装 , 功能相对基础 ;

二、flutter_tts 插件配置流程

---

1、引入依赖

在 pubspec.yaml 中添加 flutter_tts 依赖 :

dependencies:
  flutter_tts: ^4.0.2  # 请使用最新稳定版本

执行下面的命令 , 安装依赖 ;

flutter pub get

2、Android 端配置

Android 12 及以上需要 在 android/app/src/main/AndroidManifest.xml 中添加网络与 TTS 相关权限 ( 大部分系统 TTS 无需额外权限 , 部分定制 ROM 可能需要 ) :

<uses-permission android:name="android.permission.INTERNET" />

同时确保 minSdkVersion >= 21 :

android {
    defaultConfig {
        minSdkVersion 21
    }
}

3、iOS 端配置

iOS 使用系统 AVSpeechSynthesizer , 无需额外权限 , 直接使用即可 ; 如需后台播报 , 需在 Info.plist 中开启后台音频模式 :

<key>UIBackgroundModes</key>
<array>
    <string>audio</string>
</array>

三、flutter_tts 插件代码

---

1、TTS 单例服务类

TTS 单例服务类 :

import 'package:flutter_tts/flutter_tts.dart';

class TtsService {
  static final TtsService _instance = TtsService._internal();
  factory TtsService() => _instance;
  TtsService._internal();

  final FlutterTts _flutterTts = FlutterTts();
  bool _isInitialized = false;

  Future<void> init() async {
    if (_isInitialized) return;
    
    // 设置语言
    await _flutterTts.setLanguage('zh-CN');
    
    // 设置语速 (0.0 ~ 1.0)
    await _flutterTts.setSpeechRate(0.5);
    
    // 设置音调 (0.5 ~ 2.0)
    await _flutterTts.setPitch(1.0);
    
    // 设置音量 (0.0 ~ 1.0)
    await _flutterTts.setVolume(1.0);
    
    _isInitialized = true;
  }
}

开始 TTS 播报 :

Future speak(String text) async {
  if (text.isEmpty) return;
  await _flutterTts.stop(); // 先停止当前播报
  await _flutterTts.speak(text);
}

停止 / 暂停 TTS 播报 :

Future stop() async {
  await _flutterTts.stop();
}

Future pause() async {
  await _flutterTts.pause();
}

2、TTS 事件监听

通过监听回调获取播报状态 , 用于 UI 状态同步、进度展示等 :

void _initListeners() {
  // 播报开始
  _flutterTts.setStartHandler(() {
    print('TTS 开始播报');
  });

  // 播报完成
  _flutterTts.setCompletionHandler(() {
    print('TTS 播报完成');
  });

  // 播报取消/停止
  _flutterTts.setCancelHandler(() {
    print('TTS 播报已取消');
  });

  // 播报出错
  _flutterTts.setErrorHandler((msg) {
    print('TTS 报错: $msg');
  });

  // 播报进度回调
  _flutterTts.setProgressHandler((text, start, end, word) {
    print('当前播报: $word, 位置: $start - $end');
  });
}

3、获取可用语言与音色

查询当前设备支持的语言列表和音色列表 , 用于动态切换 :

// 获取支持的语言列表
Future<List<String>> getLanguages() async {
  List<dynamic> languages = await _flutterTts.getLanguages;
  return languages.map((e) => e.toString()).toList();
}

// 获取指定语言的音色
Future<List<String>> getVoices(String lang) async {
  List<dynamic> voices = await _flutterTts.getVoices;
  return voices
      .where((v) => v['locale']?.startsWith(lang) ?? false)
      .map((v) => v['name'].toString())
      .toList();
}

// 设置指定音色
Future setVoice(String name) async {
  await _flutterTts.setVoice({"name": name, "locale": "zh-CN"});
}

4、完整工具类封装

import 'package:flutter_tts/flutter_tts.dart';

enum TtsState { playing, stopped, paused }

class TtsManager {
  static final TtsManager _instance = TtsManager._internal();
  factory TtsManager() => _instance;
  TtsManager._internal();

  final FlutterTts _tts = FlutterTts();
  TtsState _state = TtsState.stopped;
  TtsState get state => _state;

  Function()? onStart;
  Function()? onComplete;
  Function(String)? onError;

  Future<void> init({
    String language = 'zh-CN',
    double speechRate = 0.5,
    double pitch = 1.0,
    double volume = 1.0,
  }) async {
    await _tts.setLanguage(language);
    await _tts.setSpeechRate(speechRate);
    await _tts.setPitch(pitch);
    await _tts.setVolume(volume);

    _tts.setStartHandler(() {
      _state = TtsState.playing;
      onStart?.call();
    });

    _tts.setCompletionHandler(() {
      _state = TtsState.stopped;
      onComplete?.call();
    });

    _tts.setCancelHandler(() {
      _state = TtsState.stopped;
    });

    _tts.setErrorHandler((msg) {
      _state = TtsState.stopped;
      onError?.call(msg.toString());
    });
  }

  Future speak(String text) async {
    if (text.isEmpty) return;
    await _tts.stop();
    await _tts.speak(text);
  }

  Future stop() async {
    await _tts.stop();
    _state = TtsState.stopped;
  }

  Future pause() async {
    await _tts.pause();
    _state = TtsState.paused;
  }

  Future dispose() async {
    await _tts.stop();
  }
}

5、页面中调用示例

class TtsDemoPage extends StatefulWidget {
  const TtsDemoPage({super.key});

  @override
  State<TtsDemoPage> createState() => _TtsDemoPageState();
}

class _TtsDemoPageState extends State<TtsDemoPage> {
  final TextEditingController _controller = TextEditingController(
    text: '你好 , 欢迎使用 Flutter 语音播报功能',
  );
  final TtsManager _tts = TtsManager();

  @override
  void initState() {
    super.initState();
    _tts.init();
  }

  @override
  void dispose() {
    _tts.dispose();
    _controller.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Flutter TTS 示例')),
      body: Padding(
        padding: const EdgeInsets.all(16),
        child: Column(
          children: [
            TextField(
              controller: _controller,
              maxLines: 3,
              decoration: const InputDecoration(
                border: OutlineInputBorder(),
                labelText: '输入播报文本',
              ),
            ),
            const SizedBox(height: 20),
            Row(
              mainAxisAlignment: MainAxisAlignment.spaceEvenly,
              children: [
                ElevatedButton(
                  onPressed: () => _tts.speak(_controller.text),
                  child: const Text('播放'),
                ),
                ElevatedButton(
                  onPressed: () => _tts.pause(),
                  child: const Text('暂停'),
                ),
                ElevatedButton(
                  onPressed: () => _tts.stop(),
                  child: const Text('停止'),
                ),
              ],
            ),
          ],
        ),
      ),
    );
  }
}

• 中文播报失效 : 部分 Android 原生系统默认引擎不支持中文 , 需要用户安装支持中文的 TTS 引擎 ( 如 Google 文字转语音、讯飞语记等 ) ; 可在代码中提前检测 :

Future<bool> isLanguageAvailable(String lang) async {
  return await _flutterTts.isLanguageAvailable(lang);
}

四、开发注意事项

---

开发注意事项 :

• 长文本截断问题 : 系统 TTS 对单次播报文本长度有限制 ( 通常约 4000 字符 ) , 超长文本建议按标点分段 , 通过队列依次播报 ;
• iOS 后台播报无声 : 需在 Info.plist 中开启 UIBackgroundModes 的 audio 模式 , 并配置音频会话为播放模式 ;
• 语速参数差异 : Android 与 iOS 的语速取值范围不一致 : Android 为 0.0~1.0 , iOS 为 AVSpeechUtteranceDefaultSpeechRate 基准 ; 实际使用时建议分平台调整参数 ;
• 不支持 Web 部分 API : Web 端基于 Web Speech API , 部分高级特性 ( 如暂停、音色列表 ) 在不同浏览器中支持程度不同 , 需做降级处理 ;

---

总结

本文详细介绍了 Flutter 中 TTS 功能的完整实现方案 ;

flutter_tts 插件通过封装各平台原生语音合成能力 , 让我们可以 快速接入文字转语音功能 , 配合语速、音调、音量调节和状态回调 , 能够满足绝大多数业务场景 ;

对于有更高音质要求或需要离线多音色的场景 , 也可以 在此基础上接入百度、讯飞等专业语音 SDK 进行扩展 ;