feat: 增强 HomeScreen 录音交互与 ChatBloc 状态管理

- 新增录音启动延迟处理，解决权限未就绪时的竞态问题 - 实现历史分页滚动位置保持，提升加载体验 - 添加文本输入框点击键盘显示与焦点管理 - 优化 ChatBloc provider 到 MultiBlocProvider 支持 - 修复 ApiException 429 错误详情解析（支持 JSON 字符串 body） - 改进 LocalNotificationService 精确闹钟权限请求 - 优化 UiSchemaRenderer GridView children 生成 - 支持导航 action 的 replace 参数 - 移除 Agent router 速率限制逻辑（_allow_run_request, _allow_transcribe_request） - 补充相关单元测试与集成测试
2026-03-18 17:03:22 +08:00
parent b34697660d
commit 8539f05a66
13 changed files with 578 additions and 143 deletions
@@ -1,5 +1,6 @@
 import 'dart:io';

+import 'package:flutter/foundation.dart';
 import 'package:flutter/material.dart';
 import 'package:flutter/services.dart';
 import 'package:flutter_bloc/flutter_bloc.dart';
@@ -85,6 +86,7 @@ class HomeScreen extends StatefulWidget {
 class _HomeScreenState extends State<HomeScreen>
    with SingleTickerProviderStateMixin {
  final TextEditingController _messageController = TextEditingController();
+  final FocusNode _messageFocusNode = FocusNode();
  final ScrollController _scrollController = ScrollController();
  late final ChatBloc _chatBloc;
  late final VoiceRecorder _voiceRecorder;
@@ -92,20 +94,31 @@ class _HomeScreenState extends State<HomeScreen>
  late final Future<String> Function(String filePath) _transcribeAudio;
  late final AnimationController _listeningAnimationController;
  bool _isRecording = false;
+  bool _isRecordingStarting = false;
  bool _isHoldToSpeakMode = true;
  bool _isTranscribing = false;
  bool _isCancelGestureActive = false;
+  bool _shouldCancelWhenStartCompletes = false;
+  bool _shouldStopWhenStartCompletes = false;
  bool _isSendingMessage = false;
  bool _isPullRefreshing = false;
+  bool _isHistoryPaginationInFlight = false;
  int _unreadCount = 0;
  final List<XFile> _selectedImages = [];
  int _lastObservedItemCount = 0;
  bool _lastObservedWaiting = false;
+  double? _historyViewportPixels;
+  double? _historyViewportMaxExtent;

  @override
  void initState() {
    super.initState();
-    _chatBloc = widget.chatBloc ?? ChatBloc(apiClient: sl());
+    final providedChatBloc = widget.chatBloc;
+    if (providedChatBloc != null) {
+      _chatBloc = providedChatBloc;
+    } else {
+      _chatBloc = context.read<ChatBloc>();
+    }
    _voiceRecorder = widget.voiceRecorder ?? RecordVoiceRecorder();
    _inboxApi = sl<InboxApi>();
    _transcribeAudio =
@@ -137,12 +150,10 @@ class _HomeScreenState extends State<HomeScreen>
  @override
  void dispose() {
    _messageController.dispose();
+    _messageFocusNode.dispose();
    _scrollController.dispose();
    _listeningAnimationController.dispose();
    _voiceRecorder.dispose();
-    if (widget.chatBloc == null) {
-      _chatBloc.close();
-    }
    super.dispose();
  }

@@ -159,7 +170,11 @@ class _HomeScreenState extends State<HomeScreen>
          final hasItemCountChanged =
              state.items.length != _lastObservedItemCount;
          final waitingStateChanged = isWaitingNow != _lastObservedWaiting;
-          if (hasItemCountChanged || waitingStateChanged) {
+          final shouldAutoScroll =
+              !_isHistoryPaginationInFlight &&
+              !state.isLoadingHistory &&
+              (hasItemCountChanged || waitingStateChanged);
+          if (shouldAutoScroll) {
            _scheduleAutoScroll(animated: hasItemCountChanged);
          }
          _lastObservedItemCount = state.items.length;
@@ -373,7 +388,7 @@ class _HomeScreenState extends State<HomeScreen>
      return;
    }
    final chatBloc = context.read<ChatBloc>();
-    if (chatBloc.state.isLoadingHistory) {
+    if (chatBloc.state.isLoadingHistory || _isHistoryPaginationInFlight) {
      return;
    }
    final hasEarlierHistory = chatBloc.state.hasEarlierHistory;
@@ -383,7 +398,7 @@ class _HomeScreenState extends State<HomeScreen>
    final startedAt = DateTime.now();
    try {
      if (hasEarlierHistory) {
-        await chatBloc.loadMoreHistory();
+        await _loadMoreHistoryPreservingViewport(chatBloc);
      } else {
        Toast.show(context, '没有更早的历史记录了', type: ToastType.info);
      }
@@ -401,8 +416,63 @@ class _HomeScreenState extends State<HomeScreen>
    }
  }

-  void _onLoadMore(BuildContext context) {
-    context.read<ChatBloc>().loadMoreHistory();
+  Future<void> _onLoadMore(BuildContext context) async {
+    final chatBloc = context.read<ChatBloc>();
+    await _loadMoreHistoryPreservingViewport(chatBloc);
+  }
+
+  Future<void> _loadMoreHistoryPreservingViewport(ChatBloc chatBloc) async {
+    if (_isHistoryPaginationInFlight) {
+      return;
+    }
+    _captureHistoryViewportAnchor();
+    if (mounted) {
+      setState(() {
+        _isHistoryPaginationInFlight = true;
+      });
+    }
+    try {
+      await chatBloc.loadMoreHistory();
+    } finally {
+      _restoreHistoryViewportAnchor();
+      if (mounted) {
+        setState(() {
+          _isHistoryPaginationInFlight = false;
+        });
+      }
+    }
+  }
+
+  void _captureHistoryViewportAnchor() {
+    if (!_scrollController.hasClients) {
+      _historyViewportPixels = null;
+      _historyViewportMaxExtent = null;
+      return;
+    }
+    final position = _scrollController.position;
+    _historyViewportPixels = position.pixels;
+    _historyViewportMaxExtent = position.maxScrollExtent;
+  }
+
+  void _restoreHistoryViewportAnchor() {
+    final previousPixels = _historyViewportPixels;
+    final previousMaxExtent = _historyViewportMaxExtent;
+    _historyViewportPixels = null;
+    _historyViewportMaxExtent = null;
+    if (previousPixels == null || previousMaxExtent == null) {
+      return;
+    }
+    WidgetsBinding.instance.addPostFrameCallback((_) {
+      if (!_scrollController.hasClients) {
+        return;
+      }
+      final position = _scrollController.position;
+      final extentDelta = position.maxScrollExtent - previousMaxExtent;
+      final targetOffset = (previousPixels + extentDelta)
+          .clamp(position.minScrollExtent, position.maxScrollExtent)
+          .toDouble();
+      _scrollController.jumpTo(targetOffset);
+    });
  }

  bool _isAgentWaiting(ChatState state) {
@@ -742,8 +812,7 @@ class _HomeScreenState extends State<HomeScreen>
  }

  Widget _buildInputContainer(BuildContext context, ChatState state) {
-    final isWaitingAgent =
-        state.isWaitingFirstToken || state.isStreaming || state.isCancelling;
+    final isWaitingAgent = _isSendingMessage || _isAgentWaiting(state);
    return ValueListenableBuilder<TextEditingValue>(
      valueListenable: _messageController,
      builder: (context, value, child) {
@@ -797,6 +866,7 @@ class _HomeScreenState extends State<HomeScreen>
        alignment: Alignment.centerLeft,
        child: TextField(
          controller: _messageController,
+          focusNode: _messageFocusNode,
          minLines: 1,
          maxLines: 1,
          style: const TextStyle(
@@ -822,19 +892,38 @@ class _HomeScreenState extends State<HomeScreen>
            contentPadding: EdgeInsets.zero,
            filled: false,
          ),
+          onTap: _onTextFieldTap,
          onSubmitted: (_) => _sendMessage(context),
        ),
      ),
    );
  }

-  void _onRightActionTap(BuildContext context, ChatState state) {
-    if (_isTranscribing || _isRecording || _isSendingMessage) {
+  void _onTextFieldTap() {
+    final alreadyFocused = _messageFocusNode.hasFocus;
+    if (!alreadyFocused) {
+      _messageFocusNode.requestFocus();
      return;
    }
-    final isWaitingAgent =
-        state.isWaitingFirstToken || state.isStreaming || state.isCancelling;
-    if (isWaitingAgent) {
+    if (!_supportsProgrammaticKeyboardShow()) {
+      return;
+    }
+    SystemChannels.textInput.invokeMethod<void>('TextInput.show');
+  }
+
+  bool _supportsProgrammaticKeyboardShow() {
+    if (kIsWeb) {
+      return false;
+    }
+    return defaultTargetPlatform == TargetPlatform.android ||
+        defaultTargetPlatform == TargetPlatform.iOS;
+  }
+
+  void _onRightActionTap(BuildContext context, ChatState state) {
+    if (_isTranscribing || _isRecording) {
+      return;
+    }
+    if (_isSendingMessage || _isAgentWaiting(state)) {
      _onStopGenerating();
      return;
    }
@@ -849,9 +938,13 @@ class _HomeScreenState extends State<HomeScreen>
    if (_isRecording || _isTranscribing) {
      return;
    }
+    final willSwitchToText = _isHoldToSpeakMode;
    setState(() {
-      _isHoldToSpeakMode = !_isHoldToSpeakMode;
+      _isHoldToSpeakMode = !willSwitchToText;
    });
+    if (!willSwitchToText) {
+      _messageFocusNode.unfocus();
+    }
  }

  void _onHoldToSpeakStart() {
@@ -863,6 +956,14 @@ class _HomeScreenState extends State<HomeScreen>
  }

  void _onHoldToSpeakEnd() {
+    if (_isRecordingStarting) {
+      _shouldCancelWhenStartCompletes = false;
+      _shouldStopWhenStartCompletes = true;
+      return;
+    }
+    if (!_isRecording) {
+      return;
+    }
    if (_isCancelGestureActive) {
      HapticFeedback.selectionClick();
      _cancelRecording(showToast: false);
@@ -883,6 +984,11 @@ class _HomeScreenState extends State<HomeScreen>
  }

  void _onHoldToSpeakCancel() {
+    if (_isRecordingStarting) {
+      _shouldStopWhenStartCompletes = false;
+      _shouldCancelWhenStartCompletes = true;
+      return;
+    }
    _cancelRecording(showToast: false);
  }

@@ -1064,13 +1170,41 @@ class _HomeScreenState extends State<HomeScreen>
  }

  Future<void> _startRecording() async {
+    if (_isRecording || _isRecordingStarting) {
+      return;
+    }
+    if (mounted) {
+      setState(() {
+        _isRecordingStarting = true;
+        _shouldCancelWhenStartCompletes = false;
+        _shouldStopWhenStartCompletes = false;
+      });
+    }
    try {
      await _voiceRecorder.start();
      _listeningAnimationController.repeat();
      if (!mounted) {
        return;
      }
+      if (_shouldStopWhenStartCompletes || _shouldCancelWhenStartCompletes) {
+        final shouldCancelAfterStart =
+            _shouldCancelWhenStartCompletes || _isCancelGestureActive;
+        setState(() {
+          _isRecordingStarting = false;
+          _shouldCancelWhenStartCompletes = false;
+          _shouldStopWhenStartCompletes = false;
+          _isRecording = true;
+          _isCancelGestureActive = false;
+        });
+        if (shouldCancelAfterStart) {
+          await _cancelRecording(showToast: false);
+          return;
+        }
+        await _stopRecording(autoSendAfterTranscribe: true);
+        return;
+      }
      setState(() {
+        _isRecordingStarting = false;
        _isRecording = true;
        _isCancelGestureActive = false;
      });
@@ -1078,6 +1212,11 @@ class _HomeScreenState extends State<HomeScreen>
      if (!mounted) {
        return;
      }
+      setState(() {
+        _isRecordingStarting = false;
+        _shouldCancelWhenStartCompletes = false;
+        _shouldStopWhenStartCompletes = false;
+      });
      Toast.show(context, _readableError(error), type: ToastType.error);
    }
  }
@@ -1107,15 +1246,14 @@ class _HomeScreenState extends State<HomeScreen>
        Toast.show(context, '未识别到有效语音，请靠近麦克风并连续说话后重试', type: ToastType.error);
        return;
      }
-      _messageController.text = transcript;
+      _messageController.text = normalizedTranscript;
      _messageController.selection = TextSelection.fromPosition(
-        TextPosition(offset: transcript.length),
+        TextPosition(offset: normalizedTranscript.length),
      );
      if (autoSendAfterTranscribe) {
-        _messageController.text = normalizedTranscript;
-        _messageController.selection = TextSelection.fromPosition(
-          TextPosition(offset: normalizedTranscript.length),
-        );
+        setState(() {
+          _isTranscribing = false;
+        });
        await _sendMessage(context);
      }
    } catch (error) {