UI组件前端【免费下载链接】ariakitToolkit with accessible components, styles, and examples for your next web app项目地址https://gitcode.com/gh_mirrors/ar/ariakit点击查看免费下载本文基于 Ariakit 仓库中的官方示例 examples/dialog-combobox-command-menu 展开讲解如何将 Dialog 与 Combobox 两个原语组合成一个 Raycast 风格的模态命令面板输入即搜索、打开即聚焦首个结果、鼠标悬停不丢失选中态。读完后你将掌握 Dialog/Combobox 之间的 store 同步方式disclosureprop、autoSelect、compositeElementInFocusOrder、focusOnHover/blurOnHoverEnd等关键参数的作用并能按示例 API 封装出可复用的CommandMenu组件族。示例概览与文件结构该示例模拟了 macOS Spotlight / Raycast 的交互页面上有一个Open Command Menu按钮点击后弹出一个居中模态窗口顶部是搜索输入框右侧带Esc提示按钮下方是分组列表Suggestions / Commands / Apps支持实时输入过滤输入为空时展示推荐分组输入后切换为统一的 Results 分组无匹配时显示 No results。仓库中与该示例相关的核心文件文件职责index.react.tsx页面入口管理open与searchValue两个 state用matchSorter实现搜索渲染分组与条目command-menu.tsxCommandMenu组件族的实现是本文的重点剖析对象commands.tsx演示数据应用applications、扩展extensions及命令commands列表style.css样式data-[active-item]高亮、进入动画opacity/scale、毛玻璃背景等CommandMenu组件族对外暴露的 API 结构如下原文档核心骨架之一CommandMenu CommandMenuInput / CommandMenuList CommandMenuGroup CommandMenuItem / /CommandMenuGroup /CommandMenuList /CommandMenu从源码实现看command-menu.tsx它内部实际渲染的是这样一组 Dialog Combobox 组件Dialog ComboboxProvider Combobox / DialogDismiss / ComboboxList ComboboxGroup ComboboxGroupLabel / ComboboxItem / /ComboboxGroup /ComboboxList /ComboboxProvider /Dialog两者一一对应CommandMenu渲染Dialog并创建 dialog storeCommandMenuInput渲染Combobox外加一个DialogDismiss按钮CommandMenuList/CommandMenuGroup/CommandMenuItem分别薄封装ComboboxList/ComboboxGroup含ComboboxGroupLabel/ComboboxItem只是在 props 与 className 上叠加了本例需要的固定配置。Dialog 与 Combobox 的状态同步disclosure prop命令面板的交互前提是Dialog 的可见性与 Combobox 弹层的可见性保持同频——打开对话框时输入框与结果列表同时出现按 Esc 时两者同时关闭。Ariakit 中实现这一点的官方推荐做法是通过useDialogStore钩子取得 dialog store再把它作为disclosureprop 传给ComboboxProviderconst dialog useDialogStore(); Dialog store{dialog} ComboboxProvider disclosure{dialog}command-menu.tsx 中的实际写法稍有不同它把open/onOpenChange作为受控 props 传入组件族再交给useDialogStoreexport interface CommandMenuProps extends Ariakit.DialogProps { open?: Ariakit.DialogStoreProps[open]; onOpenChange?: Ariakit.DialogStoreProps[setOpen]; onSearch?: Ariakit.ComboboxProviderProps[setInputValue]; } export const CommandMenu forwardRefHTMLDivElement, CommandMenuProps( function CommandMenu({ open, onOpenChange, onSearch, ...props }, ref) { const dialog Ariakit.useDialogStore({ open, setOpen: onOpenChange }); return ( Ariakit.Dialog ref{ref} unmountOnHide backdrop{div classNamebackdrop /} {...props} store{dialog} Ariakit.ComboboxProvider disclosure{dialog} ... {props.children} /Ariakit.ComboboxProvider /Ariakit.Dialog ); }, );从源码结构看disclosure机制的落点很清晰ComboboxStore的类型定义中把tag与disclosure从 Core 层字段里 Omit 出来、在 React 层单独处理见 combobox-store.ts而PopoverStoreCombobox 弹层能力的来源同样将disclosure提升为独立选项见 popover-store.ts。传入一个 Disclosure storedialog store 本身就是一个可切换 open 状态的 disclosure后Combobox 的打开/关闭事件即与 dialog 的 open 状态互相驱动——关闭 Dialog 时 Combobox 随之收起反之亦然无需额外写useEffect去手动对齐两个 store。CommandMenu上另外几个看似顺带的 props 也有明确意图unmountOnHide关闭后彻底卸载 DOM而不是仅隐藏保证每次打开都是全新状态backdrop{div classNamebackdrop /}自定义半透明遮罩配合 style.css 中的backdrop-filter: blur(8px)做毛玻璃resetValueOnHide关闭时清空搜索输入。从源码看它由useStoreProps应用到 store 上combobox-store.ts避免下次打开时残留上一次的查询文本。默认聚焦第一个选项autoSelectalways原文档指出Combobox 默认在列表打开时不会聚焦第一个选项。但在命令面板场景里输入框与选项列表是同时展示的为了让用户按一次 Enter 就能选中第一条结果示例在Combobox上设置了Combobox autoSelectalways /对应 CommandMenuInput 的实现export const CommandMenuInput forwardRef HTMLInputElement, CommandMenuInputProps (function CommandMenuInput(props, ref) { return ( div classNamecombobox-wrapper Ariakit.Combobox ref{ref} autoSelectalways {...props} className{clsx(combobox, props.className)} / Ariakit.DialogDismiss classNamebutton secondary escape Esc /Ariakit.DialogDismiss /div ); });注意输入框右侧那个Esc提示按钮并不是装饰——它渲染的是Ariakit.DialogDismiss点击即关闭对话框属于可访问的关闭途径之一与按 Esc 键等价同时视觉上向用户提示按 Esc 可退出。防止条目丢失焦点三个配合的 prop这是该示例最有含金量的一段技巧。原文档给出的目标是即使用户把鼠标移开、或把焦点移到输入框上当前高亮active的条目也不应丢失选中态。为此需要两个层面、共三个配置第一层compositeElementInFocusOrder{false}挂在ComboboxProvider上ComboboxProvider compositeElementInFocusOrder{false}该状态控制可聚焦的复合元素输入框等是否参与 Tab 焦点顺序。在命令面板中如果用户点击输入框或用方向键把焦点移回输入框默认的焦点管理会把 active item 的焦点带走列表高亮随之消失。从源码结构看compositeElementInFocusOrder是 composite 焦点管理层的核心开关在 composite-store.ts 与 composite.tsx 中定义与消费。设为false后输入框不再抢占复合导航焦点active item 得以保留。第二层focusOnHoverblurOnHoverEnd{false}挂在ComboboxItem上ComboboxItem focusOnHover blurOnHoverEnd{false} /对应 CommandMenuItemexport const CommandMenuItem forwardRefHTMLDivElement, CommandMenuItemProps( function CommandMenuItem(props, ref) { return ( Ariakit.ComboboxItem ref{ref} hideOnClick focusOnHover blurOnHoverEnd{false} {...props} className{clsx(list-item, props.className)} / ); }, );这两个 prop 的共同点是blurOnHoverEnd的默认值恰好是!!focusOnHover——在 composite hover 逻辑中composite-hover.tsxblurOnHoverEnd !!focusOnHover,也就是说只开focusOnHover时移入即聚焦会隐式带来移出即失焦显式写blurOnHoverEnd{false}才能打破这个联动使条目在被悬停时获得焦点、并一直保持到悬停另一条目为止不会因为鼠标滑出列表而被 blur。另外focusOnHover在ComboboxItem中还有组合语义未传时回退为selectModecombobox-item.tsx且弹层关闭时会被禁用。hideOnClick则负责点击条目即执行命令并关闭面板与DialogDismiss、Esc 一起构成三种关闭路径。Provider 上的其余关键配置CommandMenu 的ComboboxProvider还包含两处值得注意的配置Ariakit.ComboboxProvider disclosure{dialog} focusLoop{false} compositeElementInFocusOrder{false} resetValueOnHide setInputValue{(value) { startTransition(() { onSearch?.(value); }); }} focusLoop{false}禁用焦点循环。命令面板是单一输入焦点 列表高亮的模型不需要 Tab 在弹层内循环。setInputValue中用 React 18 的startTransition包裹onSearch回调输入触发的是外部 state 更新与列表重算matchSorter过滤标记为过渡更新可以让高优先级的输入本身保持流畅这正是 readme 标签中 Concurrent React 的出处。搜索与分组数据的实现示例入口 用matchSorter做模糊搜索并演示了空查询与有查询返回不同分组的模式function search(value: string): Recordstring, Command[] { if (!value) { return { Suggestions: suggestions, Commands: commands.filter((item) !suggestions.includes(item)), Apps: applications.filter((item) !suggestions.includes(item)), }; } const keys [name, title]; const results matchSorter(allItems, value, { keys }); if (!results.length) return {}; return { Results: results }; }空输入时返回三个分组Suggestions推荐项、Commands扩展命令、Apps应用并对推荐项做去重有输入时按name、title两个键做匹配排序统一收进Results分组返回空对象{}时入口组件渲染div classNameno-resultsNo results found/div空态。数据模型定义在 commands.tsxCommand含name/title/ 可选icon/ 可选extensionextensions通过flatMap摊平为commands并为每条命令附上所属扩展用于列表右侧显示 Command 来源标识与扩展标题allItems合并应用与命令suggestions则是按 name 从allItems中挑出的推荐子集。渲染侧index.react.tsx遍历Object.entries(matches)每个分组渲染一个CommandMenuGrouplabel传给ComboboxGroupLabel每条命令渲染CommandMenuItem其中图标、扩展来源、类型标签均包裹aria-hidden保证屏幕阅读器只读到title本身。样式要点style.css 体现了该示例的两个视觉特征对话框进入动画用纯 CSS 过渡实现.dialog初始opacity-0 [scale:0.97]在data-[enter]时过渡到opacity-100 [scale:1].backdrop用backdrop-filter: blur(8px)做毛玻璃淡入。这是 readme 标签 Animated / CSS transitions 的落点无需动画库。列表高亮不走:focus而是用data-[active-item]:bg-black/[7.5%]暗色下bg-white/10配合![outline:none]隐藏原生 focus 环——这与前文active item 尽量不被 blur的交互策略呼应视觉高亮跟随的是 active 状态而不是 DOM focus。小结与延伸阅读本示例的核心经验可以浓缩为四条用useDialogStore创建 store通过ComboboxProvider的disclosureprop 与 Dialog 同步开合Combobox设autoSelectalways打开即高亮首项Enter 一步选中ComboboxProvider设compositeElementInFocusOrder{false}防止输入框抢走 active item 的焦点ComboboxItem设focusOnHoverblurOnHoverEnd{false}悬停聚焦且不随鼠标移出失焦点击经hideOnClick直接关闭面板。仓库中还有几个同族示例可继续参考Tab 版命令面板 dialog-combobox-tab-command-menu、链接列表式 Combobox combobox-links、内置过滤的 Combobox combobox-filtering、Tab Combobox combobox-tabs以及更简单的 dialog-menu 与 menu-combobox。赞分享UI组件前端【免费下载链接】ariakitToolkit with accessible components, styles, and examples for your next web app项目地址https://gitcode.com/gh_mirrors/ar/ariakit点击查看免费下载相关推荐gpui-kit Command 组件实战指南构建可搜索、可虚拟化的 ⌘K 命令面板gpui kit Command 组件实战指南构建可搜索、可虚拟化的 ⌘K 命令面板 本指南以 gpui kit 组件库的 Command 命令面板为核心系桌面应用UI组件前端Ariakit Combobox 集成过滤实战用 useDeferredValue match-sorter 构建受控搜索组件Ariakit Combobox 集成过滤实战用 useDeferredValue match sorter 构建受控搜索组件 本文基于 AriakitUI组件前端ARIAKIT Combobox 搜索过滤实战用 setValue 与 startTransition 构建响应式搜索下拉ARIAKIT Combobox 搜索过滤实战用 setValue 与 startTransition 构建响应式搜索下拉 本文基于 ARIAKIT 仓库中的UI组件前端上一篇如何快速掌握Notepad--跨平台文本编辑器的完整入门指南下一篇如何用EmotiVoice打造2000种情感语音免费TTS终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考