前端【免费下载链接】vueuseCollection of essential Vue Composition Utilities for Vue 3项目地址https://gitcode.com/gh_mirrors/vu/vueuse点击查看免费下载导读useSpeechRecognition是 VueUse 提供的一个响应式组合式函数它将浏览器原生的 SpeechRecognition并结合 核心实现源码、类型定义、在线演示 与 测试用例完整讲解其 API 形态、配置选项、底层工作原理与实战写法读完即可在自己的 Vue 3 项目中接入语音识别能力。一、功能定位与适用场景SpeechRecognition API 允许网页将用户的语音实时转录为文本但由于该 API 长期未进入稳定规范各浏览器实现差异较大Chrome 系浏览器支持SpeechRecognition或带前缀的webkitSpeechRecognition部分浏览器完全不支持。VueUse 的useSpeechRecognition正是为抹平这一差异而设计统一能力检测自动探测window.SpeechRecognition或window.webkitSpeechRecognition并通过isSupported暴露支持状态响应式状态将isListening、isFinal、result、confidence、error等回调结果转为 Vue 的 shallowRef可直接在模板与组合式逻辑中绑定生命周期自动管理组件卸载时自动停止识别避免资源泄漏。该函数归类于 VueUse 的Sensors传感器类别与useBattery、useGeolocation等浏览器能力封装同属一个体系通过 core 包入口 导出。浏览器兼容性提示语音识别能力高度依赖浏览器与语音服务可用性正式发布前建议通过isSupported做降级处理具体支持矩阵可参考 caniuse 中SpeechRecognition相关条目。二、快速开始最小可用示例参考文档给出的最小用法如下import { useSpeechRecognition } from vueuse/core const { isSupported, isListening, isFinal, result, confidence, start, stop, } useSpeechRecognition()配合模板即可实现“点击开始/停止、实时显示转录文本”的最简交互template div p v-if!isSupported当前浏览器不支持 SpeechRecognition/p template v-else button clickisListening ? stop() : start() {{ isListening ? 停止 : 开始说话 }} /button p识别结果{{ result }}/p p v-ifisFinal本轮已结束/p /template /div /template这段代码中所有返回值都来自useSpeechRecognition()的解构其中result、isFinal等是响应式引用会随语音识别事件的到来自动更新无需手动维护回调。三、返回对象全解析根据 index.ts 的返回值定义 与 类型声明UseSpeechRecognitionReturn完整返回对象如下属性类型说明isSupportedComputedRefboolean当前环境是否支持语音识别来自Supportable基接口isListeningShallowRefboolean是否正在监听语音isFinalReadonlyShallowRefboolean最新一条结果是否为最终结果非临时结果recognitionSpeechRecognition \| undefined底层识别器实例可用于设置 grammars 等额外配置resultReadonlyShallowRefstring最新识别的转录文本confidenceReadonlyShallowRefnumber最新结果的置信度取值区间 01errorShallowRefSpeechRecognitionErrorEvent \| Error \| undefined最近一次错误事件或异常对象toggle(value?: boolean) void切换监听状态可显式传入布尔值start() void开始识别stop() void停止识别几个需要重点理解的状态confidence置信度参考文档特别指出该 ref 追踪的是“最新结果”的置信度数值范围 01对应 Web API 中SpeechRecognitionAlternative.confidence。置信度越高表示识别引擎对结果越有把握可用于过滤低质量识别例如低于 0.5 的结果提示用户重说。其默认初始值为 0见 index.ts#L77。isFinal与result的配合当interimResults: true时识别过程中会不断产生临时结果此时isFinal为false当一段语音结束、产生最终结果时isFinal变为true。因此一个常见的模式是只把isFinal true时的result提交到业务逻辑避免把中间过程的不稳定文本当真。error既可能是原生SpeechRecognitionErrorEvent含error码与message也可能是底层start()/stop()调用抛出的普通Error见 index.ts#L151-L153。四、配置选项Options参考文档明确指出以下选项的默认值会直接透传给原生SpeechRecognition实例。默认配置示例如下import { useSpeechRecognition } from vueuse/core useSpeechRecognition({ lang: en-US, interimResults: true, continuous: true, })完整选项定义见 UseSpeechRecognitionOptions整理如下选项类型默认值说明continuousbooleantrue是否连续返回多轮识别结果还是只返回单条结果对应原生continuousinterimResultsbooleantrue是否返回尚未定稿的临时结果对应原生interimResultslangMaybeRefOrGetterstringen-US识别语言支持传入 ref/getter 实现响应式切换对应原生langmaxAlternativesnumber1每条结果最多返回几个候选对应原生maxAlternativeswindowWindowdefaultWindow自定义window实例来自ConfigurableWindow用于 iframe 或测试环境注入关于各选项在源码中的落地可见 index.ts#L65-L71 的解构默认值以及 index.ts#L105-L108 中将这些值写入识别器实例的代码const { interimResults true, continuous true, maxAlternatives 1, window defaultWindow, } options const lang toRef(options.lang || en-US) // ... recognition.continuous continuous recognition.interimResults interimResults recognition.lang toValue(lang) recognition.maxAlternatives maxAlternativeslang的响应式特性lang是五个选项中唯一支持MaybeRefOrGetter即string/Ref/Getter的类型。源码用toRef将其规范化后通过watch(lang, ...)监听仅在未监听语音时才把新语言写入识别器见 index.ts#L115-L118。这是有意的设计——语音识别进行中修改语言会破坏当前会话因此需要先stop()再切换语言下一次start()即使用新语言。watch(lang, (lang) { if (recognition !isListening.value) recognition.lang lang })window的可注入性window选项继承自 ConfigurableWindow 接口这在 VueUse 中是通用的测试与隔离手段。默认取defaultWindow客户端环境下即window见 _configurable.ts#L39。测试文件正是利用这一点注入 Mock 实例详见下文“测试验证”。五、源码级原理从调用到事件的完整链路useSpeechRecognition的实现思路非常清晰以 Vue 的响应式状态为“数据中枢”用原生 API 的事件回调驱动这些状态再用watch把状态的改变反向翻译为对原生 API 的调用。全流程如下1. 能力检测isSupportedconst SpeechRecognition window (window.SpeechRecognition || window.webkitSpeechRecognition) const isSupported useSupported(() SpeechRecognition)通过 useSupported 将检测结果包装为计算属性同时兼容带webkit前缀的实现。isSupported继承自Supportable接口见 core 类型定义是整个函数的“能力开关”。2. 实例创建与初始化if (isSupported.value) { recognition new SpeechRecognition() as SpeechRecognition recognition.continuous continuous recognition.interimResults interimResults recognition.lang toValue(lang) recognition.maxAlternatives maxAlternatives }仅在支持时才创建实例避免在不支持的浏览器上抛错。3. 事件回调 → 响应式状态四个关键回调把原生事件翻译为 ref 更新index.ts#L110-L137onstart置isListening true、重置isFinal falseonresult取event.results[event.resultIndex]的首个候选解构出transcript与confidence分别写入result、confidenceisFinal由currentResult.isFinal决定同时清空erroronerror把SpeechRecognitionErrorEvent写入erroronend置isListening false并恢复recognition.lang为当前lang值。4. 响应式状态 → 原生调用反向联动watch(isListening, (newValue, oldValue) { if (newValue oldValue) return try { if (newValue) recognition!.start() else recognition!.stop() } catch (err) { error.value err as unknown as Error } })当isListening变化时触发start()/stop()并把可能抛出的异常捕获到error。这意味着你不需要直接调用recognition.start()——只需修改isListening或调用start/stop/toggle这三个内部会改动isListening的函数即可驱动底层这正是start/stop实现如此简洁的原因index.ts#L82-L97const start () { isListening.value true } const stop () { isListening.value false } const toggle (value !isListening.value) { if (value) start() else stop() }5. 自动清理tryOnScopeDispose(() { stop() })组件卸载或副作用作用域销毁时自动停止识别与 VueUse 其他组合式函数保持一致。6. 完整类型支撑由于 SpeechRecognition 属于实验性 API仓库在 types.ts 中提供了完整的 TypeScript 类型补全包括SpeechRecognition接口、事件映射SpeechRecognitionEventMap以及错误码联合类型export type SpeechRecognitionErrorCode | aborted | audio-capture | bad-grammar | language-not-supported | network | no-speech | not-allowed | service-not-allowed这些错误码恰好是你在处理error状态时可以用来做分支提示的枚举例如not-allowed表示用户拒绝了麦克风权限、network表示网络错误等。六、实战进阶颜色口令识别官方 Demo 拆解官方演示 demo.vue 是一个很好的综合示例它利用JSGF 语法SpeechGrammarList限制识别词表实现“说颜色名 → 界面变色”的交互。核心逻辑如下const colors [aqua, azure, beige, /* ... */] const grammar #JSGF V1.0; grammar colors; public color ${colors.join( | )} ; const speech useSpeechRecognition({ lang, continuous: true, }) if (speech.isSupported.value) { // 浏览器存在前缀差异时做兼容 const SpeechGrammarList window.SpeechGrammarList || window.webkitSpeechGrammarList const speechRecognitionList new SpeechGrammarList() speechRecognitionList.addFromString(grammar, 1) speech.recognition!.grammars speechRecognitionList // 监听转录结果匹配颜色词 watch(speech.result, () { for (const i of speech.result.value.toLowerCase().split( ).reverse()) { if (colors.includes(i)) { color.value i break } } }) }要点提炼自定义语法通过speech.recognition!.grammars直接操作底层实例recognition暴露出来正是为了这类扩展场景addFromString(grammar, 1)中的第二个参数是该语法的权重语言实时切换lang用shallowRef(en-US)传入配合模板中的单选按钮在en-US/fr/es间切换切换后需重新开始识别才生效Demo 中通过isListening联动更新已选语言文案结果后处理把result分词、小写化后反向匹配词表命中即更新 UI——说明result是一个可以被watch的普通响应式值。七、测试验证行为被测试锁定的部分仓库为useSpeechRecognition提供了浏览器环境测试 index.browser.test.ts它用createMockWindow()注入一个MockSpeechRecognition类来模拟原生 API验证了以下行为函数可被正常定义与导出confidence初始值为0触发onresult事件后result更新为hello world、confidence更新为0.85同时验证了transcript与confidence的解构取数逻辑无window时仍保持返回结构完整confidence.value 0、result.value 、isListening.value false即 SSR / 非浏览器环境下不会抛错只是能力不可用。这意味着如果你需要在自己的项目中为这个函数编写单元测试同样可以借助window选项注入 mock而不必依赖真实麦克风。八、使用建议与注意事项先检测后使用模板中务必先渲染isSupported为false的降级 UI如 Demo 中提示“Your browser does not support SpeechRecognition API”权限与安全识别前浏览器会请求麦克风权限error为not-allowed时应引导用户开启权限语音数据由浏览器/语音服务处理涉及隐私场景需在页面内明示语言切换需先停止由于watch(lang)只在!isListening时生效切换lang前应先stop()区分临时与最终结果业务上一般以isFinal true为准避免把识别过程中的中间文本提交置信度阈值confidence在 01 之间可结合场景设置阈值过滤低质量识别生命周期tryOnScopeDispose保证组件卸载自动停止无需手动清理但长时间页面建议在不需要时显式stop()以节省资源。小结useSpeechRecognition用约 170 行代码把实验性强、回调密集的 Web Speech API 封装成了“解构即用、状态响应式、生命周期自管理”的 Vue 组合式函数。本文涉及的关键文件均可继续深入研读官方参考文档、核心实现、类型定义、演示源码 与 测试用例。若想了解其作为 Sensors 类函数的通用模式可对比 useSupported 与 可配置 window 约定。赞分享前端【免费下载链接】vueuseCollection of essential Vue Composition Utilities for Vue 3项目地址https://gitcode.com/gh_mirrors/vu/vueuse点击查看免费下载相关推荐VueUse 的 useSpeechRecognition在 Vue 3 中把浏览器语音识别变成响应式状态VueUse 的 useSpeechRecognition在 Vue 3 中把浏览器语音识别变成响应式状态 导读 useSpeechRecognition 是前端VueUse useShare 深度指南在 Vue 3 中响应式封装 Web Share APIVueUse useShare 深度指南在 Vue 3 中响应式封装 Web Share API 本文以 useShare/index.md https://前端VueUse usePermission 完全指南用 Vue 3 响应式封装 Web Permissions APIVueUse usePermission 完全指南用 Vue 3 响应式封装 Web Permissions API 导读 usePermission 是 V前端上一篇一条命令永久关闭 Windows Defenderdefender-control 完整操作指南附恢复方案下一篇免费开源的 diff-pdf快速对比两份 PDF 文件的完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考