【免费下载链接】ZCodeZ.ais coding agent harness. Powerful, intelligent, extensible.项目地址https://gitcode.com/gh_mirrors/zco/ZCode点击查看免费下载导读本指南围绕 ZCode 仓库中集成的 AI Elements 技能所附带的VoiceSelector组件文档展开见 voice-selector.md该组件是一个用于在 AI 应用中挑选语音voice的可组合对话框内置元数据展示性别、口音、年龄段与实时搜索过滤能力。读完本文你将掌握VoiceSelector全部 18 个组成部件的 Props 契约、受控/非受控两种使用模式、useVoiceSelector()上下文 Hook 的调用方式以及如何参照仓库中的 voice-selector.tsx 示例在基于 shadcn/ui 的 React 项目中落地一个带试听preview、分组、键盘导航的完整语音选择器。背景说明AI Elements 是一套基于 shadcn/ui 构建、面向 AI 原生应用的前端组件库。ZCode 仓库以 Apache-2.0 许可将其组件文档与示例以 Skill 的形式集成在.agents/skills/ai-elements/目录下详见仓库根目录 THIRD-PARTY-NOTICES.md 中的 ai-elements 条目供构建对话、消息、工具展示、语音输入等 AI 聊天界面时参考与复用。组件概览与设计理念VoiceSelector是一个高度可组合fully composable的语音选择对话框组件。它并不把 UI 固化为一个黑盒而是像乐高积木一样拆分为粒度极小的控制部件granular control components由使用者按需拼接。其底层依赖shadcn/ui 的 Dialog 组件承载弹出层、遮罩modal与焦点管理shadcn/ui 的 Command 组件提供命令面板式的搜索过滤、键盘导航与列表渲染React Context API由根组件VoiceSelector注入上下文任何嵌套子组件都能通过useVoiceSelector()读取或改写当前选中语音与对话框开关状态。这种一个根组件 一堆细粒度子组件 一个上下文 Hook的结构使其既能在示例脚本 voice-selector.tsx 中呈现完整用法也能被拆散到任意自定义布局中复用。核心能力清单对应原文档 Features完全可组合的架构与细粒度控制组件基于 shadcn/ui 的 Dialog 与 Command 构建通过 React Context API 在嵌套组件中访问状态支持实时过滤的可搜索语音列表语音元数据展示性别图标Lucide、口音旗帜 emoji、年龄段语音试听按钮含播放/暂停/加载三态语音分组支持分隔线与圆点bullet分隔符键盘导航支持受控controlled与非受控uncontrolled两种使用模式全 TypeScript 类型支持。安装Voice Selector 属于 AI Elements 组件之一可通过官方 CLI 安装npx ai-elementslatest add voice-selector根据 SKILL.md 中的说明请使用项目packageManager对应的包管理器运行器如pnpm dlx ai-elementslatest或bunx --bun ai-elementslatest代替npx ai-elementslatest。安装前置条件包括Node.js 18 或更高版本安装了 AI SDK 的 Next.js 项目项目内已安装 shadcn/ui若未安装CLI 会自动补装默认组件会被添加至/components/ai-elements/目录或你在 shadcn 配置中指定的 components 目录。Props 全解析以下按原文档逐一给出全部组件的 Props 契约含类型、默认值与说明并补充仓库示例 voice-selector.tsx 中的实际使用佐证。根组件VoiceSelector /根 Dialog 组件为所有子组件提供上下文同时管理语音选择与对话框开关两个状态。PropTypeDefaultDescriptionvaluestring-被选中的语音 ID受控。defaultValuestring-默认选中的语音 ID非受控。onValueChange(value: string \| undefined) void-选中语音变化时的回调。defaultOpenbooleanfalse默认打开状态非受控。openboolean-打开状态受控。onOpenChange(open: boolean) void-打开状态变化时的回调。modalbooleantrue对话框是否模态阻止与页面其余部分交互。...propsReact.ComponentPropstypeof Dialog-其余 props 透传给 Dialog 组件。示例脚本中的受控用法const [open, setOpen] useState(false); const [selectedVoice, setSelectedVoice] useStatestring | null(null); // ... VoiceSelector onOpenChange{setOpen} open{open}触发部件VoiceSelectorTrigger /打开语音选择对话框的按钮或元素。PropTypeDefaultDescriptionasChildbooleanfalse将渲染元素替换为传入的子元素并合并其 props 与行为。...propsReact.ComponentPropstypeof DialogTrigger-其余 props 透传给 DialogTrigger。示例中使用asChild包裹 shadcn/ui 的Button并在按钮内展示当前选中语音的名称、口音、年龄段与性别未选中时显示占位文案 Select a voice...VoiceSelectorTrigger asChild Button classNamew-full max-w-xs variantoutline {selectedVoiceData ? ( VoiceSelectorName{selectedVoiceData.name}/VoiceSelectorName VoiceSelectorAccent value{selectedVoiceData.accent} / VoiceSelectorBullet / VoiceSelectorAge{selectedVoiceData.age}/VoiceSelectorAge VoiceSelectorBullet / VoiceSelectorGender value{selectedVoiceData.gender} / / ) : ( span classNameflex-1 text-left text-smSelect a voice.../span )} /Button /VoiceSelectorTrigger内容容器VoiceSelectorContent /承载 Command 组件与语音列表的对话框内容容器。PropTypeDefaultDescriptiontitleReactNode-供屏幕阅读器使用的标题视觉上隐藏但对辅助技术可见。classNamestring-附加到对话框内容的 CSS 类。...propsReact.ComponentPropstypeof DialogContent-其余 props 透传给 DialogContent。示例中通过classNamemax-w-md约束对话框宽度VoiceSelectorContent classNamemax-w-md命令面板风格实现VoiceSelectorDialog /基于CommandDialog的另一种对话框实现呈现全屏命令面板command palette风格。PropTypeDefaultDescription...propsReact.ComponentPropstypeof CommandDialog-其余 props 透传给 CommandDialog。搜索输入VoiceSelectorInput /用于过滤语音的搜索输入框。PropTypeDefaultDescriptionplaceholderstring-输入框占位文本。classNamestring-附加 CSS 类。...propsReact.ComponentPropstypeof CommandInput-其余 props 透传给 CommandInput。示例VoiceSelectorInput placeholderSearch voices... /语音列表VoiceSelectorList /语音条目与分组的可滚动容器。PropTypeDefaultDescription...propsReact.ComponentPropstypeof CommandList-其余 props 透传给 CommandList。空态提示VoiceSelectorEmpty /当没有语音匹配搜索关键词时显示的消息。PropTypeDefaultDescriptionchildrenReactNode-要显示的消息。...propsReact.ComponentPropstypeof CommandEmpty-其余 props 透传给 CommandEmpty。示例VoiceSelectorEmptyNo voices found./VoiceSelectorEmpty语音分组VoiceSelectorGroup /将相关语音分组可带可选标题。PropTypeDefaultDescriptionheadingstring-分组标题文本。...propsReact.ComponentPropstypeof CommandGroup-其余 props 透传给 CommandGroup。语音条目VoiceSelectorItem /代表一个可选择的语音条目。PropTypeDefaultDescriptionvaluestring-该语音的唯一标识用于搜索过滤。onSelect(value: string) void-选中该语音时的回调。...propsReact.ComponentPropstypeof CommandItem-其余 props 透传给 CommandItem。示例中VoiceItem被memo包裹以避免无谓重渲染并通过useCallback缓存onSelect与onPreview回调const VoiceItem memo( ({ voice, playingVoice, loadingVoice, onSelect, onPreview }: VoiceItemProps) { const handleSelect useCallback(() onSelect(voice.id), [onSelect, voice.id]); const handlePreview useCallback(() onPreview(voice.id), [onPreview, voice.id]); return ( VoiceSelectorItem key{voice.id} onSelect{handleSelect} value{voice.id} {/* ... */} /VoiceSelectorItem ); }, ); VoiceItem.displayName VoiceItem;分组分隔线VoiceSelectorSeparator /语音分组之间的视觉分隔线。PropTypeDefaultDescription...propsReact.ComponentPropstypeof CommandSeparator-其余 props 透传给 CommandSeparator。语音名称VoiceSelectorName /以恰当样式显示语音名称。PropTypeDefaultDescriptionclassNamestring-附加 CSS 类。...propsReact.ComponentPropsspan-其余 props 透传给 span 元素。性别元数据VoiceSelectorGender /使用 Lucide 图标显示语音性别元数据支持多种性别身份及对应图标。PropTypeDefaultDescriptionvalueunknown-决定显示哪个图标的性别值。classNamestring-附加 CSS 类。childrenReactNode-用自定义内容覆盖默认图标。...propsReact.ComponentPropsspan-其余 props 透传给 span 元素。示例数据集中gender的取值为male/female字符串const voices [ { id: liam, name: Liam, gender: male, accent: american, age: 20-30, /* ... */ }, { id: alice, name: Alice, gender: female, accent: british, age: 30-40, /* ... */ }, ];口音元数据VoiceSelectorAccent /用代表不同国家/地区的旗帜 emoji 显示语音口音元数据。PropTypeDefaultDescriptionvalueunknown-决定显示哪个旗帜 emoji 的口音值支持包括 american、british 在内的 27 种口音。classNamestring-附加 CSS 类。childrenReactNode-用自定义内容覆盖旗帜 emoji。...propsReact.ComponentPropsspan-其余 props 透传给 span 元素。年龄段元数据VoiceSelectorAge /以弱化样式muted styling与等宽数字tabular numbers显示语音年龄段保证对齐一致。PropTypeDefaultDescriptionclassNamestring-附加 CSS 类。...propsReact.ComponentPropsspan-其余 props 透传给 span 元素。示例数据集中age的取值为20-30、30-40、50-60等区间字符串。语音描述VoiceSelectorDescription /以弱化样式显示语音描述。PropTypeDefaultDescriptionclassNamestring-附加 CSS 类。...propsReact.ComponentPropsspan-其余 props 透传给 span 元素。属性容器VoiceSelectorAttributes /将性别、口音、年龄等语音属性分组放在一起的容器可与VoiceSelectorBullet搭配使用实现分隔。PropTypeDefaultDescriptionclassNamestring-附加 CSS 类。...propsReact.ComponentPropsdiv-其余 props 透传给 div 元素。圆点分隔符VoiceSelectorBullet /在语音属性之间显示圆点分隔符•通过aria-hidden对屏幕阅读器隐藏。PropTypeDefaultDescriptionclassNamestring-附加 CSS 类。...propsReact.ComponentPropsspan-其余 props 透传给 span 元素。示例中的典型组合方式名称、描述、分隔符与三项元数据VoiceSelectorName{voice.name}/VoiceSelectorName VoiceSelectorDescription{voice.description}/VoiceSelectorDescription VoiceSelectorBullet / VoiceSelectorAccent value{voice.accent} / VoiceSelectorBullet / VoiceSelectorAge{voice.age}/VoiceSelectorAge VoiceSelectorBullet / VoiceSelectorGender value{voice.gender} /快捷键VoiceSelectorShortcut /显示语音条目的键盘快捷键。PropTypeDefaultDescription...propsReact.ComponentPropstypeof CommandShortcut-其余 props 透传给 CommandShortcut。试听按钮VoiceSelectorPreview /允许用户在选中前试听语音样本的按钮根据状态显示播放、暂停或加载图标。PropTypeDefaultDescriptionplayingboolean-语音是否正在播放为 true 时显示暂停图标。loadingboolean-试听是否加载中为 true 时显示加载动画并禁用按钮。onPlay() void-点击试听按钮时的回调。classNamestring-附加 CSS 类。...propsOmitReact.ComponentPropsbutton, onPlay-其余 props 透传给 button 元素。HooksuseVoiceSelector()用于访问语音选择器上下文的自定义 Hook可在嵌套于VoiceSelector内的任意组件中读取与控制语音选择状态。import { useVoiceSelector } from repo/elements/voice-selector; export default function CustomVoiceDisplay() { const { value, setValue, open, setOpen } useVoiceSelector(); return ( div pSelected voice: {value ?? None}/p button onClick{() setOpen(!open)}Toggle Dialog/button /div ); }返回值PropTypeDefaultDescriptionvaluestring \| undefined-当前选中的语音 ID。setValue(value: string \| undefined) void-更新当前选中语音 ID 的函数。openboolean-对话框当前是否打开。setOpen(open: boolean) void-控制对话框开关状态的函数。完整示例带试听的语音选择器仓库中的 voice-selector.tsx 提供了一个端到端可运行的完整示例。除组合上述部件外它还演示了两块关键工程细节1. 数据模型每条语音包含id、name、description、gender、accent、age与previewUrl七个字段。其中gender与accent的类型直接取自VoiceSelectorGender/VoiceSelectorAccent的value类型从而获得端到端类型安全const voices: { id: string; name: string; description: string; gender: ComponentPropstypeof VoiceSelectorGender[value]; accent: ComponentPropstypeof VoiceSelectorAccent[value]; age: string; previewUrl: string; }[] [ /* ... */ ];2. 试听逻辑通过useRefHTMLAudioElement | null持有单个Audio实例实现同一语音再次点击即暂停、切换语音自动停止上一个、播放结束自动复位的完整交互闭环const handlePreview useCallback( (voiceId: string) { const voice voices.find((v) v.id voiceId); if (!voice) return; // 点击正在播放的语音 - 暂停 if (playingVoice voiceId) { audioRef.current?.pause(); setPlayingVoice(null); return; } // 停止当前正在播放的音频 if (audioRef.current) { audioRef.current.pause(); audioRef.current null; } setLoadingVoice(voiceId); const audio new Audio(voice.previewUrl); audioRef.current audio; audio.addEventListener(canplaythrough, () { setLoadingVoice(null); setPlayingVoice(voiceId); audio.play(); }); audio.addEventListener(ended, () setPlayingVoice(null)); audio.addEventListener(error, () { setLoadingVoice(null); setPlayingVoice(null); }); audio.load(); }, [playingVoice], );试听状态通过playingVoice/loadingVoice两个string | null状态与条目 ID 比对驱动VoiceSelectorPreview的三态展示播放/暂停/加载并利用memouseCallback保证列表在状态切换时仅重渲染必要的条目。无障碍与可扩展性无障碍组件基于 shadcn/ui 的 Dialog/Command 构建天然具备语义化 HTML 与 ARIA 属性VoiceSelectorContent支持titleprop 向屏幕阅读器提供可访问标题VoiceSelectorBullet通过aria-hidden对辅助技术隐藏装饰性分隔符Command 组件提供完整的键盘导航支持。可扩展性所有子组件均透传底层原语的 props如React.ComponentPropstypeof Dialog、React.ComponentPropstypeof CommandItem、React.ComponentPropsspan等因此可以像使用原生元素一样附加样式与行为。这与 SKILL.md 中所有 AI Elements 组件尽量接收原始属性的扩展性设计一脉相承。受控/非受控VoiceSelector同时暴露value/defaultValue与open/defaultOpen两对受控/非受控组合可以像使用 shadcn/ui 的 Dialog 一样按需选择状态管理模式参考同目录 mic-selector.md 中提到的 Radix UIuseControllableState模式。使用建议与注意事项安装位置AI Elements 组件代码会直接落入项目源码默认/components/ai-elements/而非隐藏在库中因此你可以直接打开组件文件查看实现或按需定制这也是 SKILL.md 强调的代码即文档理念。试听资源示例中的previewUrl指向远端音频文件实际接入 TTS如 ElevenLabs 等服务时需替换为真实的音频地址并妥善处理音频加载失败error事件与卸载时的资源释放。主题与样式组件的 Tailwind 样式在安装时即已集成若出现样式丢失请先确认项目globals.css已按 shadcn/uiTailwind 4要求引入基础样式并确认tsconfig.json中配置了/*路径别名paths: { /*: [./*] }。在 ZCode 中的定位ZCode 仓库将 AI Elements 以 Skill 形式内置.agents/skills/ai-elements/references/目录存放各组件文档、scripts/目录存放对应示例脚本供 AI 编码助手在构建聊天/语音类界面时按需取用同主题的音频输入侧还有 mic-selector.md麦克风选择与 speech-input.md语音输入等参考文档可一并查阅。赞分享【免费下载链接】ZCodeZ.ais coding agent harness. Powerful, intelligent, extensible.项目地址https://gitcode.com/gh_mirrors/zco/ZCode点击查看免费下载相关推荐终极指南如何使用awesome-shadcn-ui实现高效复杂选项选择功能终极指南如何使用awesome shadcn ui实现高效复杂选项选择功能 awesome shadcn ui是一个精心策划的与shadcn/ui相关的精选资文档前端awesome-shadcn-ui中的复选框组实现多项选择功能awesome shadcn ui中的复选框组实现多项选择功能 你是否还在为实现高效的多项选择功能而烦恼用户需要快速勾选多个选项时传统单选框组合既占空间又文档前端5分钟用TqSdk抓取期货实时行情从安装到自动下单的完整实战指南5分钟用TqSdk抓取期货实时行情从安装到自动下单的完整实战指南 小李刚接手公司的期货套利研究每天的工作从打开行情软件、手动记录十几个合约的报价开始。行情跳金融科技创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考