fix: review suggestion

Author: SonyLeo

docs/demos/sender/voice-input.vue

@@ -22,24 +22,22 @@ const voiceMode = ref<'append' | 'replace'>('append')
       {{
         voiceMode === 'append'
           ? '追加模式：每次语音识别结果会追加到输入框末尾，适合混合输入'
-          : '替换模式：在录音期间使用最新识别结果直接替换整个输入框内容'
+          : '替换模式：在录音期间使用识别结果持续替换整个输入框内容'
       }}
     </div>
     <tr-sender
       :key="voiceMode"
       mode="multiple"
       :placeholder="
-        voiceMode === 'append'
-          ? '可以打字或点击麦克风说话，语音内容会追加...'
-          : '点击麦克风连续说话，输入框内容会被语音结果持续替换...'
+        voiceMode === 'append' ? '可以打字或点击麦克风说话，语音内容会追加...' : '点击麦克风说话，输入框内容持续替换...'
       "
     >
       <template #footer-right>
         <VoiceButton
           :speech-config="
             voiceMode === 'append'
-              ? { autoReplace: false, interimResults: true }
-              : { autoReplace: true, continuous: true, interimResults: true }
+              ? { autoReplace: false, continuous: true, interimResults: true }
+              : { autoReplace: true, interimResults: true }
           "
         />
       </template>

docs/src/components/sender.md

@@ -1,4 +1,4 @@
----
+---
 outline: [1, 3]
 ---
 
@@ -159,6 +159,12 @@ TrSender.Suggestion.configure({ items: suggestions, filterFn: customFilter })
 
 <demo vue="../../demos/sender/voice-input.vue" title="基础语音输入" description="使用浏览器内置语音识别，展示追加写入和整框替换两种体验。" />
 
+:::tip 替换模式说明
+当 `speechConfig.autoReplace` 为 `true` 时，输入框会被当前录音结果整框替换。
+
+如果同时开启 `speechConfig.continuous`，替换进去的是“当前录音会话的累计识别结果”，也就是后续说出的内容会和前面已确认的内容一起更新，而不是仅保留最后一句。
+:::
+
 :::tip lang 语言说明
 `lang` 用于指定语音识别语言，建议显式传入，并与页面的 `html lang` 保持一致，避免页面语言和浏览器环境语言不一致时出现识别偏差。
 

packages/components/src/sender-actions/voice-button/index.vue

@@ -5,6 +5,7 @@ import { useSpeechHandler } from './useSpeechHandler'
 import ActionButton from '../action-button/index.vue'
 import { IconVoice, IconRecordingWave } from '@opentiny/tiny-robot-svgs'
 import type { VoiceButtonProps, VoiceButtonEmits } from './index.type'
+import type { SpeechHookOptions } from './speech.types'
 
 const props = withDefaults(defineProps<VoiceButtonProps>(), {
   tooltipPlacement: 'top',
@@ -59,8 +60,7 @@ const mergeCommittedTranscript = (transcript: string) => {
   return committedTranscript.value
 }
 
-// 语音配置 - 使用普通对象而不是 computed，避免每次都创建新对象
-const speechOptions = {
+const getSpeechOptions = (): SpeechHookOptions => ({
   ...props.speechConfig,
   onStart: () => {
     resetSpeechSession()
@@ -91,10 +91,10 @@ const speechOptions = {
     resetSpeechSession()
     emit('speech-error', error)
   },
-}
+})
 
 // 使用语音 Hook
-const { speechState, start, stop } = useSpeechHandler(speechOptions)
+const { speechState, start, stop } = useSpeechHandler(getSpeechOptions)
 
 // 处理点击
 const handleClick = async () => {

packages/components/src/sender-actions/voice-button/useSpeechHandler.ts

@@ -1,4 +1,5 @@
-import { reactive, onUnmounted, ref } from 'vue'
+import { reactive, onUnmounted, shallowRef, toValue, watch } from 'vue'
+import type { MaybeRefOrGetter } from 'vue'
 import type {
   SpeechHookOptions,
   SpeechHandlerResult,
@@ -16,9 +17,10 @@ import { WebSpeechHandler } from './webSpeechHandler'
  * @param options 语音识别配置
  * @returns 语音识别控制器
  */
-export function useSpeechHandler(options: SpeechHookOptions): SpeechHandlerResult {
-  // 使用 ref 存储 options，确保能获取最新值
-  const optionsRef = ref(options)
+export function useSpeechHandler(options: MaybeRefOrGetter<SpeechHookOptions>): SpeechHandlerResult {
+  const handlerRef = shallowRef<SpeechHandler | null>(null)
+  const pendingRestart = shallowRef(false)
+  const suppressEndCallback = shallowRef(false)
 
   // 语音识别状态
   const speechState = reactive<SpeechState>({
@@ -27,86 +29,150 @@ export function useSpeechHandler(options: SpeechHookOptions): SpeechHandlerResul
     error: undefined,
   })
 
-  // 创建回调函数集合 - 使用函数形式，每次调用时获取最新的 options
+  const resolveOptions = () => toValue(options)
+
+  const updateSupportState = () => {
+    const currentOptions = resolveOptions()
+    speechState.isSupported = currentOptions.customHandler
+      ? currentOptions.customHandler.isSupported()
+      : WebSpeechHandler.isSupported()
+  }
+
+  const createHandler = (currentOptions: SpeechHookOptions): SpeechHandler | null => {
+    if (currentOptions.customHandler) {
+      return currentOptions.customHandler
+    }
+
+    if (!WebSpeechHandler.isSupported()) {
+      return null
+    }
+
+    return new WebSpeechHandler(currentOptions)
+  }
+
+  // 创建回调函数集合 - 每次调用时都获取最新的 options
   const callbacks: SpeechCallbacks = {
     onStart: () => {
       speechState.isRecording = true
       speechState.error = undefined
-      optionsRef.value.onStart?.()
+      resolveOptions().onStart?.()
     },
     onInterim: (transcript: string) => {
-      optionsRef.value.onInterim?.(transcript)
+      resolveOptions().onInterim?.(transcript)
     },
     onFinal: (transcript: string) => {
-      optionsRef.value.onFinal?.(transcript)
+      resolveOptions().onFinal?.(transcript)
     },
     onEnd: (transcript?: string) => {
+      const shouldEmitEnd = !suppressEndCallback.value
+      const shouldRestart = pendingRestart.value
+
+      suppressEndCallback.value = false
+      pendingRestart.value = false
+      handlerRef.value = null
+
       if (speechState.isRecording) {
         speechState.isRecording = false
-        optionsRef.value.onEnd?.(transcript)
+      }
+
+      if (shouldEmitEnd) {
+        resolveOptions().onEnd?.(transcript)
+      }
+
+      updateSupportState()
+
+      if (shouldRestart) {
+        start()
       }
     },
     onError: (error: Error) => {
       speechState.error = error
       speechState.isRecording = false
-      optionsRef.value.onError?.(error)
+      pendingRestart.value = false
+      suppressEndCallback.value = false
+      handlerRef.value = null
+      resolveOptions().onError?.(error)
+      updateSupportState()
     },
   }
 
-  // 检查是否支持（对于内置 Handler，提前检查避免无效创建）
-  const isBuiltinSupported = WebSpeechHandler.isSupported()
-  speechState.isSupported = options.customHandler ? options.customHandler.isSupported() : isBuiltinSupported
-
-  // 选择语音处理器：如果提供了 customHandler，直接使用；否则在支持的情况下创建 WebSpeechHandler
-  const handler: SpeechHandler | null =
-    options.customHandler ?? (isBuiltinSupported ? new WebSpeechHandler(options) : null)
+  watch(
+    () => resolveOptions().customHandler,
+    () => {
+      if (!speechState.isRecording) {
+        handlerRef.value = null
+      }
+      updateSupportState()
+    },
+    { immediate: true },
+  )
 
   // 开始录音
   const start = () => {
-    if (!speechState.isSupported || !handler) {
+    const currentOptions = resolveOptions()
+
+    updateSupportState()
+
+    if (!speechState.isSupported) {
       const error = new Error('语音识别不受支持')
       speechState.error = error
-      optionsRef.value.onError?.(error)
+      currentOptions.onError?.(error)
       return
     }
 
-    // 如果正在录音，先停止再重新开始
+    // 如果正在录音，等待当前会话自然结束后再重启
     if (speechState.isRecording) {
-      handler.stop()
-      speechState.isRecording = false
-      // 短暂延迟后重新开始
-      setTimeout(() => {
-        handler.start(callbacks)
-      }, 200)
+      pendingRestart.value = true
+      handlerRef.value?.stop()
       return
     }
 
+    const nextHandler = createHandler(currentOptions)
+
+    if (!nextHandler || !nextHandler.isSupported()) {
+      const error = new Error('语音识别不受支持')
+      speechState.error = error
+      currentOptions.onError?.(error)
+      updateSupportState()
+      return
+    }
+
+    handlerRef.value = nextHandler
+    pendingRestart.value = false
+    suppressEndCallback.value = false
+
     try {
-      handler.start(callbacks)
+      nextHandler.start(callbacks)
     } catch (error) {
       speechState.error = error instanceof Error ? error : new Error('启动失败')
-      optionsRef.value.onError?.(speechState.error)
+      handlerRef.value = null
+      currentOptions.onError?.(speechState.error)
     }
   }
 
   // 停止录音
   const stop = () => {
-    if (!speechState.isRecording || !handler) {
+    if (!speechState.isRecording || !handlerRef.value) {
       return
     }
 
-    handler.stop()
-    callbacks.onEnd()
+    pendingRestart.value = false
+    suppressEndCallback.value = false
+    handlerRef.value.stop()
   }
 
   // 组件卸载时清理资源
   onUnmounted(() => {
     // 如果正在录音，先停止
-    if (speechState.isRecording && handler) {
-      handler.stop()
+    if (speechState.isRecording && handlerRef.value) {
+      pendingRestart.value = false
+      suppressEndCallback.value = true
+      handlerRef.value.stop()
       // 卸载时不触发 onEnd 回调，避免不必要的副作用
       speechState.isRecording = false
     }
+
+    handlerRef.value = null
   })
 
   return {

packages/components/src/sender-actions/voice-button/webSpeechHandler.ts

@@ -88,6 +88,7 @@ export class WebSpeechHandler implements SpeechHandler {
 
     this.recognition.onend = () => {
       callbacks.onEnd(this.finalizedTranscript || undefined)
+      this.cleanup()
       this.resetSessionTranscript()
     }
 
@@ -148,12 +149,11 @@ export class WebSpeechHandler implements SpeechHandler {
   stop(): void {
     if (!this.recognition) return
 
-    this.cleanup()
-    this.resetSessionTranscript()
-
     try {
       this.recognition.stop()
     } catch (error) {
+      this.cleanup()
+      this.resetSessionTranscript()
       console.warn('停止语音识别时发生错误:', error)
     }
   }