Ant Design AutoComplete「查询模式确定类目」实战指南分组选项与下拉样式定制【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design导读本篇围绕 Ant Design AutoComplete 组件的经典演示「查询模式确定类目Certain Category」展开该演示是交互规范文档中自动完成查询模式Lookup Patterns在组件层面的标准实现用户输入关键词后下拉列表按Libraries / Solutions / Articles等固定类目分组展示匹配项。读完本文你将掌握 AutoComplete 分组选项optionslabeloptions嵌套结构的完整写法、下拉菜单样式定制popupClassName与配套 CSS、与不确定类目场景的取舍以及相关 API 的源码级行为。一、什么是确定类目查询模式在 Ant Design 交互规范中自动完成组件用于用户输入时下拉列表随着输入的关键词显示匹配项。根据查询结果分类的多少规范将其划分为两种类型确定类目Certain Category用户所查询的关键词只会出现在若干固定类目中例如话题问题文章3 种类目下拉列表按这些类目分组渲染不确定类目Uncertain Category用户所查询的关键词所属类目数量不确定可能 4 个、可能 5 个甚至更多下拉列表通常按匹配结果平铺渲染。本演示即前者的实现样例对应演示入口位于 certain-category.tsx其文档说明位于 certain-category.md。与它形成对照的不确定类目样例可参考 uncertain-category.tsx。提示本文所有代码路径均以仓库根目录为基准可打开对应文件直接查看完整源码。二、分组选项的数据结构options的嵌套写法确定类目的核心在于把下拉选项按类目分组。AutoComplete 直接复用了 Select 的options数据化配置协议——当某个选项对象同时包含label与options两个字段时它就是一个分组Group而不是普通选项。看演示中的完整数据定义certain-category.tsxconst renderItem (title: string, count: number) ({ value: title, label: ( Flex aligncenter justifyspace-between {title} span UserOutlined / {count} /span /Flex ), }); const options [ { label: Title titleLibraries /, options: [renderItem(AntDesign, 10000), renderItem(AntDesign UI, 10600)], }, { label: Title titleSolutions /, options: [renderItem(AntDesign UI FAQ, 60100), renderItem(AntDesign FAQ, 30010)], }, { label: Title titleArticles /, options: [renderItem(AntDesign design language, 100000)], }, ];要点拆解顶层数组的每个元素代表一个类目其中label是类目标题Group Titleoptions是该类目下的子项数组子项对象由value选中时回填/回调的取值与label下拉中渲染的内容组成label可以是任意 ReactNode因此可以像演示中那样内嵌图标与数字统计官方文档对options的说明是数据化配置选项内容相比 jsx 定义会获得更好的渲染性能类型为{ label, value }[]见 auto-complete/index.zh-CN.md这里的分组结构正是该数据协议的自然扩展。类目标题的自定义渲染演示中类目标题本身也是自定义 ReactNode由Title组件渲染certain-category.tsxconst Title: React.FCReadonly{ title?: string } (props) ( Flex aligncenter justifyspace-between {props.title} a hrefhttps://www.google.com/search?qantd target_blank relnoopener noreferrer more /a /Flex );每个类目标题右侧都有一个more跳转链接这是确定类目模式的常见产品交互类目是已知的、稳定的因此可以直接引导用户进入该分类的更多结果页。分组协议在 Select 层面的等价写法如果偏好 JSX 写法同样的分组效果可以用OptGroup实现参见 select/demo/optgroup.tsx 对应示例。OptGroup的label属性即分组标题其下通过Select.Option声明子项。AutoComplete 内部本质上是 Select 的一个无后缀图标、自由输入的变体详见本文第五节因此两种数据协议均可用options对象写法因免去 JSX 实例化开销而性能更优。三、完整的 AutoComplete 装配与下拉样式定制组件装配const App: React.FC () ( AutoComplete popupClassNamecertain-category-search-dropdown popupMatchSelectWidth{500} style{{ width: 250 }} options{options} sizelarge Input.Search sizelarge placeholderinput here / /AutoComplete );这里涉及几个与本场景强相关的 API完整 API 表见 auto-complete/index.zh-CN.md参数说明本示例取值options数据化配置选项内容分组后的选项数组popupClassName下拉菜单的 className用于精准定位样式作用域4.23.0 起替代已废弃的dropdownClassNamecertain-category-search-dropdownpopupMatchSelectWidth下拉菜单与输入框同宽。默认设置min-width当值小于选择框宽度时会被忽略false会关闭虚拟滚动500固定下拉宽度size尺寸largestyle作用于输入框容器的内联样式{ width: 250 }注意当通过children传入自定义输入组件如这里的Input.Search时组件源码会给出开发期警告——You need to control style self instead of settingsizewhen using customize input即尺寸应交给自定义输入框自身控制而不是同时给 AutoComplete 设置size见 index.tsx。因此更严谨的写法是仅在Input.Search上声明sizelarge演示中同时设置属于宽松写法实际项目建议遵循该警告收敛到一处。下拉菜单样式定制CSS 逐段解析原文档给出了配套的样式文件certain-category.md作用域全部挂在popupClassName指定的类名之下逐段含义如下/* 类目分组标题置灰加粗弱化标题、突出子项 */ .certain-category-search-dropdown .ant-select-dropdown-menu-item-group-title { color: #666; font-weight: bold; } /* 类目分组之间用细分割线隔开形成确定类目的区块感 */ .certain-category-search-dropdown .ant-select-dropdown-menu-item-group { border-bottom: 1px solid #f6f6f6; } /* 子项默认左缩进 16px与类目标题产生视觉层级 */ .certain-category-search-dropdown .ant-select-dropdown-menu-item { padding-inline-start: 16px; } /* 预留的 show-all 类用于查看全部这类居中的特殊项本例未启用 */ .certain-category-search-dropdown .ant-select-dropdown-menu-item.show-all { text-align: center; cursor: default; } /* 下拉菜单整体限高 300px超出滚动 */ .certain-category-search-dropdown .ant-select-dropdown-menu { max-height: 300px; }三个可复用的设计手法用popupClassName做样式作用域避免全局污染其他下拉若项目使用 CSS-in-JS如 antd 官方推荐的ant-design/cssinjs方案也可在dropdownRender或主题 Token 层面实现等价定制分组标题 子项缩进 分割线三个要素叠加是确定类目分组视觉的通用配方限高 内部滚动max-height保证类目较多时下拉不至于撑满视口。样式选择器中的.ant-select-dropdown-menu系列类名对应 rc-select 内部 DOM 结构antd 版本升级时若类名变更需同步调整更稳妥的方式是优先使用 antd 官方文档维护的语义化 APIpopupClassName结合组件文档推荐的 Token。四、与不确定类目模式的对比将 uncertain-category.tsx 与本文演示对比能清晰看出两种模式的分工维度确定类目本演示不确定类目选项结构固定分组label类目标题options子项平铺valuelabel数据来源静态/预定义类目稳定随onSearch动态生成如searchResult(query)模拟远程搜索交互特征类目可点击跳转更多每条结果展示命中位置与结果数如 Found xx on …关键事件侧重展示与选择依赖onSearch驱动setOptions刷新候选不确定类目演示还示范了受控options的典型写法onSearch触发时根据输入值生成候选并setOptions空输入时置空数组uncertain-category.tsx适合类目数量不可预知的搜索建议场景。五、源码级原理AutoComplete 如何驱动分组下拉AutoComplete 的入口实现揭示了它和 Select 的关系本质是 Select 的封装AutoComplete 将自身prefixCls设为 Select 的getPrefixCls(select, customizePrefixCls)并向内部 Select 透传popupClassName、dropdownStyle等属性同时强制mode{Select.SECRET_COMBOBOX_MODE_DO_NOT_USE}并设置suffixIcon{null}——这正是自由输入、不强制选择行为的来源index.tsx选项协议归一options直接透传给内部 Select分组结构labeloptions由 rc-select 的分组渲染逻辑消费而旧的dataSourceprop 会在内部被转换为Option子节点index.tsx且源码通过warning.deprecated提示请改用optionsindex.tsx分组字段可自定义Select 的fieldNames支持自定义label / value / options / groupLabel字段名groupLabel自 5.6.0 起见 select/index.en-US.mdAutoComplete 同样继承该能力当后端返回的分组字段名不是label/options时无需改写数据结构下拉样式作用域popupClassName最终作为内部 Select 下拉菜单的 className 挂载因此文档中的 CSS 全部以它为前缀书写同时 AutoComplete 还会通过useZIndex为dropdownStyle补充层级 zIndex避免弹层被遮挡index.tsx。关于筛选的默认行为AutoComplete 文档中filterOption默认值为true见 auto-complete/index.zh-CN.md即默认按输入值对选项做过滤。若希望确定类目下输入时不过滤、始终展示全部分组类似演示中数据源较短、希望看到全貌的场景可显式设置filterOption{false}或传入自定义过滤函数(inputValue, option) boolean。已知边界options 为空时受控 open 不展开组件 FAQ 明确说明AutoComplete 本质是 Input 的扩展当options为空时即便open{true}也不会显示下拉菜单以避免用户误以为组件不可操作open必须与options配合使用见 auto-complete/index.zh-CN.md。在设计确定类目的空态交互时需留意此行为例如可配合notFoundContent定制空列表提示。六、将演示改造为可运行的完整示例将上述内容整合为可直接运行的最小示例在支持 React antd 的环境下引入后挂载渲染即可import React from react; import { UserOutlined } from ant-design/icons; import { AutoComplete, Flex, Input } from antd; const renderItem (title: string, count: number) ({ value: title, label: ( Flex aligncenter justifyspace-between {title} span UserOutlined / {count} /span /Flex ), }); const options [ { label: Libraries, options: [renderItem(AntDesign, 10000), renderItem(AntDesign UI, 10600)], }, { label: Solutions, options: [renderItem(AntDesign UI FAQ, 60100), renderItem(AntDesign FAQ, 30010)], }, ]; export default () ( AutoComplete popupClassNamecertain-category-search-dropdown popupMatchSelectWidth{500} style{{ width: 250 }} options{options} Input.Search sizelarge placeholderinput here / /AutoComplete );配套 CSS 直接沿用原文档的样式块见第二节 CSS 片段即可获得分组标题加粗、分割线、子项缩进与 300px 限高的完整效果。七、深入阅读组件完整 API、方法与 FAQauto-complete/index.zh-CN.md组件源码实现auto-complete/index.tsx演示源码与样式certain-category.tsx、certain-category.md不确定类目对照演示uncertain-category.tsx交互规范「查询模式」章节reaction.zh-CN.md单元测试覆盖自定义输入、dataSource对象数组、Option兼容、popupClassName等行为auto-complete/tests/index.test.tsx【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考