165 lines
4.1 KiB
Markdown
165 lines
4.1 KiB
Markdown
# 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. **易于测试** - 支持依赖注入，便于单元测试
|
||
|
||
这样的设计既保持了简单性，又提供了必要的灵活性，避免了过度设计的问题。
|