yx_speech_to_text_flutter/简化使用指南.md

RecordingButton 简化使用指南

🎯 设计理念

简化设计，去除过度复杂性，提供一个既支持依赖注入又保持简单易用的录音按钮组件。

🚀 基本使用

1. 最简单的使用方式

import 'package:yx_asr/yx_asr.dart';

RecordingButton(
  onResult: (result) {
    print('识别结果: ${result.recognizedWords}');
  },
  onError: (error) {
    print('错误: ${error.errorMsg}');
  },
)

2. 自定义模型路径

RecordingButton(
  modelPath: 'assets/models/my-model',  // 自定义模型路径
  onResult: (result) => handleResult(result),
  onError: (error) => handleError(error),
)

3. 依赖注入自定义服务

class MyPage extends StatefulWidget {
  @override
  _MyPageState createState() => _MyPageState();
}

class _MyPageState extends State<MyPage> {
  late YxAsrService _speechService;

  @override
  void initState() {
    super.initState();
    _speechService = YxAsrService();
  }

  @override
  Widget build(BuildContext context) {
    return RecordingButton(
      speechService: _speechService,  // 注入已配置的服务
      onResult: (result) {
        setState(() {
          // 处理结果
        });
      },
    );
  }

  @override
  void dispose() {
    _speechService.dispose();
    super.dispose();
  }
}

🎨 自定义外观

RecordingButton(
  size: 100.0,                    // 按钮大小
  idleColor: Colors.blue,         // 未录音时颜色
  recordingColor: Colors.red,     // 录音时颜色
  disabledColor: Colors.grey,     // 禁用时颜色
  tooltip: '点击开始录音',         // 提示文本
  partialResults: true,           // 是否返回部分结果
  onResult: (result) => print(result.recognizedWords),
)

🔧 API 参考

构造函数参数

参数	类型	默认值	说明
speechService	SpeechRecognitionService?	null	语音识别服务实例（可选）
modelPath	String	'assets/models'	模型文件路径
onResult	Function?	null	识别结果回调
onError	Function?	null	错误回调
onListeningStatusChanged	Function?	null	状态变化回调
partialResults	bool	true	是否返回部分结果
size	double	80.0	按钮大小
idleColor	Color?	null	未录音时颜色
recordingColor	Color?	null	录音时颜色
disabledColor	Color?	null	禁用时颜色
enabled	bool	true	是否启用
tooltip	String?	null	提示文本

🧪 测试支持

// 创建模拟服务进行测试
class MockSpeechService implements SpeechRecognitionService {
  // 实现接口方法...
}

// 在测试中使用
testWidgets('recording button test', (tester) async {
  final mockService = MockSpeechService();
  
  await tester.pumpWidget(
    MaterialApp(
      home: RecordingButton(
        speechService: mockService,
        onResult: (result) {},
      ),
    ),
  );
  
  // 测试逻辑...
});

💡 最佳实践

1. 默认使用 - 大多数情况下直接使用默认配置即可
2. 服务复用 - 在同一页面有多个按钮时，共享同一个服务实例
3. 错误处理 - 始终提供 onError 回调处理错误情况
4. 权限管理 - 组件会自动处理权限申请，无需手动处理
5. 资源释放 - 如果注入了自定义服务，记得在页面销毁时调用 dispose()

🔄 迁移指南

从旧版本迁移

// 旧版本
RecordingButton(
  localeId: 'zh-CN',
  onDevice: false,
  // ... 其他参数
)

// 新版本（简化）
RecordingButton(
  modelPath: 'assets/models',  // 直接指定模型路径
  // ... 其他参数保持不变
)

🎯 设计优势

1. 简单易用 - 默认配置即可工作
2. 支持注入 - 可以注入自定义服务进行测试
3. 向后兼容 - API 保持稳定
4. 职责清晰 - UI 组件专注于 UI，业务逻辑可外置
5. 易于测试 - 支持依赖注入，便于单元测试

这样的设计既保持了简单性，又提供了必要的灵活性，避免了过度设计的问题。