# RecordingButton 简化使用指南

## 🎯 设计理念

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

## 🚀 基本使用

### 1. 最简单的使用方式

```dart
import 'package:yx_asr/yx_asr.dart';

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

### 2. 自定义模型路径

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

### 3. 依赖注入自定义服务

```dart
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();
  }
}
```

## 🎨 自定义外观

```dart
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` | 提示文本 |

## 🧪 测试支持

```dart
// 创建模拟服务进行测试
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()`

## 🔄 迁移指南

### 从旧版本迁移

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

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

## 🎯 设计优势

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

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