Kaneo 项目 coss Autocomplete 组件实战指南自由输入与建议选择的完整实现方案【免费下载链接】app All you need. Nothing you dont. Open source project management that works for you, not against you.项目地址: https://gitcode.com/GitHub_Trending/app116/app导读coss是基于 Base UIbase-ui/react构建、采用 shadcn 风格开发体验的组件库本仓库Kaneo 开源项目管理应用在apps/web/src/components/ui/autocomplete.tsx中完整落地了 coss Autocomplete 原语。本篇指南以仓库内.agents/skills/coss/references/primitives/autocomplete.md参考文档为主线系统讲解 Autocomplete 的适用场景、安装方式、组合式 API、过滤/分组/异步搜索等实战模式并结合仓库源码剖析其底层实现与常见坑点。读完本文你将能够在项目里独立实现输入即搜索、键盘可导航的高质量建议选择器并理解其与 Select、Combobox、Command 等相邻原语的本质区别。Autocomplete 是什么自由输入与建议选择的结合体Autocomplete自动补全是搜索驱动的建议选择器核心特征是允许用户自由输入文本同时基于已知选项空间option space提供即时匹配建议并支持完整的键盘导航。在 coss 组件注册表中见 component-registry.md它被归类于Selection Input选择与输入一组与 Select、Combobox 并列原语定位输入自由度Select从预定义列表中单选无搜索只能选不能输Combobox可搜索、带过滤的选择受限于严格选项集Autocomplete自由文本 建议可以输入任意内容建议仅供参考Command可搜索的命令面板操作而非数据选择触发命令什么时候用 Autocomplete来自参考文档 When to use需要搜索驱动的建议选择器 自由输入的场景需要基于已知选项空间做辅助输入、且依赖键盘导航完成的场景。什么时候不该用 AutocompleteWhen NOT to use这一点决定了选型正确性选项完全预定义、不需要搜索 → 用Select用户必须从严格集合中选取、不允许自由文本 → 用Combobox需要的是一组操作命令而非数据选择 → 用Command。从仓库源码看这种命令语义在apps/web/src/components/ui/command.tsx中体现得很明显它内部直接复用了/components/ui/autocomplete导出的Autocomplete、AutocompleteInput、AutocompleteList、AutocompleteItem等一批组件来搭建命令面板骨架说明 Autocomplete 是比 Command 更底层的通用搜索式列表构件Command 是建立在它之上的命令化封装。安装与依赖CLI 一键安装参考文档推荐使用 shadcn CLI 直接添加 coss 组件npx shadcnlatest add coss/autocomplete该命令会从 coss 组件注册表拉取组件文件并自动完成依赖解析。coss 技能的完整安装/发现工作流见 cli.md。手动安装手动 deps若需要手动接入参考文档明确要求的核心运行时依赖只有一个npm install base-ui/react在仓库实现中可以看到该依赖的实际使用autocomplete.tsx 第一行即是import { Autocomplete as AutocompletePrimitive } from base-ui/react/autocomplete;同时仓库内的组件实现还依赖以下同级文件与图标库手动接入时需一并就位/components/ui/inputInput nativeInput承载输入框外观/components/ui/scroll-areaAutocompleteList的滚动容器/lib/cn类名合并工具lucide-reactChevronsUpDownIcon触发器图标、XIcon清除图标。规范导入Canonical imports参考文档给出的规范导入与本仓库 autocomplete.tsx 的export列表完全一致import { Autocomplete, AutocompleteCollection, AutocompleteEmpty, AutocompleteGroup, AutocompleteGroupLabel, AutocompleteInput, AutocompleteItem, AutocompleteList, AutocompletePopup, AutocompleteSeparator, AutocompleteStatus, useAutocompleteFilter, } from /components/ui/autocomplete除上述之外仓库实现还额外导出了AutocompleteClear、AutocompleteRow、AutocompleteTrigger、AutocompleteValue在自定义清除按钮、行渲染、值展示等高级场景中可用。最小可用模式Minimal pattern参考文档给出的最小完整示例const items [ { label: Apple, value: apple }, { label: Banana, value: banana }, ] Autocomplete items{items} AutocompleteInput aria-labelSearch items placeholderSearch items… / AutocompletePopup AutocompleteEmptyNo items found./AutocompleteEmpty AutocompleteList {(item) ( AutocompleteItem key{item.value} value{item} {item.label} /AutocompleteItem )} /AutocompleteList /AutocompletePopup /Autocomplete结构拆解AutocompleteRoot持有items数据源AutocompleteInput是自由输入框AutocompletePopup承载弹出层仓库实现中它由Portal Positioner Popup三段构成见 autocomplete.tsxAutocompleteList以 render-prop 形式接收(item) ...渲染列表AutocompleteEmpty提供空结果反馈。表单绑定建议参考文档明确提示——对于表单绑定的自动补全控件优先使用Field包裹使 label、必填状态required与错误输出error始终与同一控件保持关联而不是散落在表单各处。数据与渲染模型items与value的映射理解 Autocomplete 的渲染模型是正确使用的前提。从参考文档与仓库代码交叉印证可以得出Autocomplete接收items数组元素可以是字符串或对象AutocompleteItem value{item}把整条 item 作为选中值传给 Base UI 内部状态过滤匹配、键盘高亮data-highlighted与选中提交都由AutocompletePrimitivebase-ui/react/autocomplete统一管理。仓库对 Item 的样式实现autocomplete.tsx非常典型可作为视觉基准flex min-h-8 cursor-default select-none items-center rounded-sm px-2 py-1 text-base outline-none >Autocomplete items{items} AutocompleteInput aria-labelSearch frameworks placeholderSearch... showClear showTrigger startAddon{SearchIcon aria-hiddentrue /} / AutocompletePopup AutocompleteEmptyNo results found./AutocompleteEmpty AutocompleteList {(item) AutocompleteItem key{item.value} value{item}{item.label}/AutocompleteItem} /AutocompleteList /AutocompletePopup /Autocomplete仓库源码完整支持这三种能力autocomplete.tsxstartAddon渲染在输入框左侧绝对定位区域带aria-hiddentrue并自动为输入框追加ps-*内边距避免文字压到图标showTrigger渲染AutocompleteTrigger内部是ChevronsUpDownIcon下拉箭头点击可展开/收起建议列表showClear渲染AutocompleteClear内部是XIcon点击一键清空输入。仓库还支持size属性sm | default | lg | numbersm尺寸会同步收缩触发器/清除按钮的定位与内边距这对应粒子p-autocomplete-1~p-autocomplete-4中的尺寸与禁用态变体。分组列表Grouped lists当选项需要按类别组织时用AutocompleteGroupAutocompleteGroupLabelAutocompleteCollection三层结构AutocompleteList AutocompleteGroup AutocompleteGroupLabelFruits/AutocompleteGroupLabel AutocompleteCollection {(item) AutocompleteItem key{item.value} value{item}{item.label}/AutocompleteItem} /AutocompleteCollection /AutocompleteGroup /AutocompleteList仓库对这三者的实现要点autocomplete.tsxAutocompleteGroup[[rolegroup]]:mt-1.5连续分组之间自动拉开间距AutocompleteGroupLabeltext-xs小号字 text-muted-foreground弱化色明确表达分组标题语义AutocompleteCollectionBase UI 的 Collection 节点负责注册组内 item保证键盘导航方向键遍历在分组间正确流转。异步搜索Async search参考文档给出异步模式的三条关键约定filter{null}关闭内置客户端过滤完全交由服务端/自定义过滤逻辑受控绑定自行控制value/onValueChange把用户输入发送到异步查询提供itemToStringValue当items为对象时必须指定对象 → 稳定字符串的映射否则内部稳定的字符串映射会被破坏导致高亮、匹配、值比较全部失真。典型骨架如下Autocomplete items{remoteItems} filter{null} value{query} onValueChange{setQuery} itemToStringValue{(item) item.id} AutocompleteInput aria-labelAsync search placeholderType to search… / AutocompletePopup AutocompleteStatus{statusText}/AutocompleteStatus AutocompleteEmptyNo results found./AutocompleteEmpty AutocompleteList {(item) AutocompleteItem key{item.id} value{item}{item.name}/AutocompleteItem} /AutocompleteList /AutocompletePopup /Autocomplete表单集成Form integration把Autocomplete放进Field name...中配合FieldLabel/FieldError即可获得与表单状态绑定的校验输出Field nameowner ... FieldLabel负责人/FieldLabel Autocomplete items{members} ... /Autocomplete FieldError / /Field参考文档强调这样 label、必填状态与错误提示始终和同一个控件绑定避免视觉上在一个表单、语义上却脱离控件的 a11y 隐患。表单相关规则的完整说明见 rules/forms.md。更多示例索引参考文档将 15 个粒子示例按能力线做了分组可直接对照查阅粒子文件位于 coss 仓库apps/ui/registry/default/particles/p-*.tsx能力线粒子编号基线 尺寸 禁用态p-autocomplete-1~p-autocomplete-4标签 输入增强showClear/showTrigger/startAddonp-autocomplete-5、p-autocomplete-8、p-autocomplete-9、p-autocomplete-14匹配行为modeboth、autoHighlightp-autocomplete-6、p-autocomplete-7分组选项p-autocomplete-10限量结果 状态提示p-autocomplete-11异步搜索loading/error 状态p-autocomplete-12表单集成p-autocomplete-13风格变体pill 输入p-autocomplete-15过滤与状态机制useAutocompleteFilter、AutocompleteStatus的底层作用useAutocompleteFilter仓库实现将其直接映射为 Base UI 的过滤钩子autocomplete.tsxconst useAutocompleteFilter AutocompletePrimitive.useFilter;它内置了大小写不敏感匹配、mode匹配模式与autoHighlight自动高亮首个匹配项等参数对应粒子p-autocomplete-6/p-autocomplete-7的匹配行为演示。默认情况下 Autocomplete 使用该过滤钩子对items做客户端过滤异步场景中通过filter{null}关闭它把过滤职责交给服务端。AutocompleteStatusAutocompleteStatus是列表尾部/头部的小字号状态区仓库样式为px-3 py-2 font-medium text-muted-foreground text-xs见 autocomplete.tsx。在受限结果如 Showing 5 of 120和异步 loading/error 场景中它负责把非选项类的状态信息以视觉弱化、语义独立的方式呈现不会打断键盘导航流。常见坑点Common pitfalls 逐一破解参考文档列出的五个坑点结合仓库源码逐一说明规避方法漏掉AutocompleteEmpty空结果时弹出空白面板用户得不到任何反馈。务必始终保留AutocompleteEmpty节点仓库实现中它有居中对齐的 muted 样式见 autocomplete.tsx。异步/自定义流程中使用对象 item 却不提供itemToStringValue会破坏稳定的字符串映射导致匹配与值比较错乱。对象 item 场景必须显式提供该映射。把 Combobox/Select 的假设混入 Autocomplete API三者交互语义不同详见本文选型表使用前务必核对各自文档不要想当然地复用 props。输入框缺少显式标签必须通过FieldLabel或aria-label提供可访问名称。参考文档把这一点列为强制项仓库的 Command 面板内部也通过透传aria-label保证可访问性。不处理异步的竞态/错误状态loading、error以及过期响应取消stale response cancellation必须显式管理否则会出现旧请求覆盖新结果的竞态。参考文档要求结合AutocompleteStatus展示 loading/error 状态。仓库落地验证从参考文档到真实实现本文档对应的组件在仓库中的实现位于 apps/web/src/components/ui/autocomplete.tsx可以从源码直接验证上述全部行为Root 组合Autocomplete AutocompletePrimitive.Root第 9 行完整继承 Base UI 的 items/过滤/导航状态机弹出层三段式AutocompletePopup由Portal → Positioner → Popup组合Positioner支持side默认bottom、sideOffset默认 4、align默认start、anchor等定位参数且通过min-w-(--anchor-width)、max-w-(--available-width)、max-h-[min(var(--available-height),23rem)]实现跟随锚点宽度、防溢出视口的自适应约束第 77-121 行列表滚动AutocompleteList用ScrollArea包裹AutocompletePrimitive.List超长列表获得可滚动容器not-empty:scroll-py-1 not-empty:p-1保证滚动时列表项不被裁剪第 219-235 行分隔线AutocompleteSeparator提供h-px bg-border细线且last:hidden自动隐藏末尾冗余分隔线第 142-153 行。此外同目录下的 command.tsx 是 Autocomplete 原语被二次组合的实证它以base-ui/react/dialog作为命令面板外壳内部复用了Autocomplete、AutocompleteInput、AutocompleteList、AutocompleteItem、AutocompleteGroup、AutocompleteGroupLabel等组件构成可搜索命令列表。这印证了参考文档的定位——Autocomplete 是通用搜索式列表基座Command 是在其之上的命令语义封装。总结coss Autocomplete 是自由输入 建议选择场景的首选原语选型上要严格与 Select纯选择、Combobox严格集、Command命令语义区分。使用时牢记三条主线组合式 APIInput/Popup/List/Item 按文档层级组合、数据映射对象 item 必须提供itemToStringValue异步场景关闭内置过滤、状态完整性AutocompleteEmpty与AutocompleteStatus不可省略。仓库内 autocomplete.tsx 提供了完整可运行的参考实现粒子示例p-autocomplete-1~p-autocomplete-15覆盖了从尺寸变体、分组、受限结果到异步与表单集成的全部实战形态可作为后续开发的直接蓝本。【免费下载链接】app All you need. Nothing you dont. Open source project management that works for you, not against you.项目地址: https://gitcode.com/GitHub_Trending/app116/app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考