React Toolbox Autocomplete 组件完全指南：源码级解析多选、过滤与主题定制

前端UI组件【免费下载链接】react-toolboxA set of React components implementing Googles Material Design specification with the power of CSS Modules项目地址https://gitcode.com/gh_mirrors/re/react-toolbox点击查看免费下载Autocomplete自动补全是 React Toolbox 组件库中一个基于 Material Design 规范实现的输入组件它提供一个带预定义标签选项的输入框聚焦时展示选项列表并随用户输入按标签实时过滤同时支持单选与多选两种模式。读完本文你将掌握 Autocomplete 的完整 API、source数据源格式、四种匹配策略、方向自适应逻辑以及基于 CSS Modules 的主题定制方法并能在自己的 React 项目中直接落地使用。组件定位与核心能力React Toolbox 的 Autocomplete 组件位于 components/autocomplete/Autocomplete.js其定位是一个带一组预定义标签值的输入字段当它获得焦点时会展示一个选项列表用户键入时列表会按标签实时过滤根据允许选中的值数量它可以是简单模式单选或多次模式多选。选项面板的展开方向向上还是向下会在打开瞬间根据组件当前在视口中的位置自动判定避免选项列表被视口边缘截断。组件对外通过react-css-themr的themr高阶组件包装主题标识符为RTAutocomplete定义于 components/identifiers.js 中的AUTOCOMPLETE常量。因此如果你需要通过 React Context 全局注入主题组件的 key 就是RTAutocomplete。快速上手一个多选示例官方文档components/autocomplete/readme.md给出的标准示例以选择国家为场景展示了多选模式下最基本的用法import Autocomplete from react-toolbox/lib/autocomplete; const source { ES-es: Spain, TH-th: Thailand, EN-gb: England, EN-en: USA }; class AutocompleteTest extends React.Component { state { countries: [ES-es, TH-th] } handleChange (value) { this.setState({countries: value}); }; render () { return ( Autocomplete directiondown selectedPositionabove labelChoose countries onChange{this.handleChange} source{source} value{this.state.countries} / ); } }这里有几个值得注意的细节source是键值对对象键如ES-es是真正被存入value的值值如Spain是展示给用户看的标签文本value是键组成的数组初始值为[ES-es, TH-th]意味着 Spain 和 Thailand 一开始就处于已选中状态组件默认是多选multiple默认true已选项会以可删除的 Chip 形式展示在输入框上方selectedPositionaboveonChange在值变化时被触发回调参数就是新的键数组使用方只需setState完成受控更新。Properties 完整参数表Autocomplete继承并透传了Input组件的全部属性。下表完整列出了其自有属性默认值与官方文档一致类型与实现细节以 components/autocomplete/Autocomplete.js 的propTypes与defaultProps为准名称类型默认值说明allowCreateBoolfalse是否允许用户用当前输入值创建新选项classNameString设置组件根元素的样式类名directionStringauto决定选项列表的展开方向可选auto、up、downdisabledBoolfalse为true时组件被禁用errorString或Node无内部 Input 元素的错误提示文本keepFocusOnChangeBoolfalse值变化后是否保持输入框聚焦labelString或Node无浮动标签元素的文本multipleBooltrue为true时可持有多个值多选onBlurFunction无组件失焦时触发onChangeFunction无组件值变化时触发onFocusFunction无组件聚焦时触发onKeyDownFunction无按下键盘键时触发onKeyUpFunction无抬起键盘键时触发onQueryChangeFunction无输入框 query 值变化时触发queryString无当source非静态、在multiple{false}搜索过程中动态变化时使用query 内容需由onQueryChange回调管理sourceObject或Array无键值对对象或数组代表全部建议项selectedPositionStringabove已选项列表相对输入框的展示位置可选above、below、noneshowSelectedWhenNotInSourceBoolfalse当value中的键不存在于source时是否仍展示已选项仅当value以 Object 形式传入时生效showSuggestionsWhenValueIsSetBoolfalse为true时选中一个值后建议列表不会被过滤直到用户修改 querysuggestionMatchStringstart建议项的匹配策略可选start、anywhere、word、disabledvalueString、Array或Object无当前选中的值或值数组除上述属性外所有额外的属性都会被透传给内部的 Input 组件见 Autocomplete.js 中{...other}的展开逻辑因此你可以直接使用hint、name等 Input 属性。这也意味着 Autocomplete 天然继承了 Input 的浮动标签、错误状态、禁用态等能力。深入源码source数据源支持的两种形态source是 Autocomplete 的核心数据源源码中的source()方法Autocomplete.js将两种输入形态统一规范化为Mapsource() { const { source: src } this.props; if (src.hasOwnProperty(length)) { return new Map(src.map(item Array.isArray(item) ? [...item] : [item, item])); } return new Map(Object.keys(src).map(key [${key}, src[key]])); }对象形态如{ES-es: Spain, ...}每个键是内部值每个值是对外展示的标签数组形态支持两种子结构元素是二元数组[key, value]如[[ES-es, Spain]]直接映射为键值对元素是普通字符串如[Spain, Thailand]则自动退化为值与标签相同[item, item]。四种匹配策略suggestionMatch过滤逻辑由matches()方法实现Autocomplete.js。在比较之前query 与候选标签都会经过normalise()Autocomplete.js处理该方法会去除重音符号如á → a、ß → S并统一转小写、去除首尾空白因此suggestionMatch的匹配是大小写不敏感、忽略重音的这对多语言数据源非常重要。suggestionMatch值匹配规则源码实现start默认query 匹配建议项的开头value.startsWith(query)anywherequery 出现在建议项的任意位置value.includes(query)wordquery 匹配建议项中某个单词的开头new RegExp(\\b${query}, g) 测试disabled禁用过滤展示全部 source 项直接返回true注意 TypeScript 声明Autocomplete.d.ts中该属性类型为disabled \| start \| anywhere \| word而运行时propTypes还额外接受了none分支从代码结构看这属于兼容性遗留使用时应以上述四种为标准。过滤的整体流程在suggestions()方法Autocomplete.js中多选模式遍历全部 source剔除已被选中的键再按 query 匹配剩余项单选模式当 query 非空且未设置显示全部建议时按匹配策略过滤否则直接展示全部 source。展开方向direction的自适应计算direction支持auto、up、down三种值默认auto。在auto模式下组件聚焦时会通过calculateDirection()Autocomplete.js动态计算展开方向calculateDirection() { if (this.props.direction auto) { const client ReactDOM.findDOMNode(this.inputNode).getBoundingClientRect(); const screen_height window.innerHeight || document.documentElement.offsetHeight; const up client.top ((screen_height / 2) client.height); return up ? up : down; } return this.props.direction; }判定规则为当输入框的顶部位置超过视口高度的一半加上输入框自身高度时说明输入框位于屏幕下半区选项列表改为向上展开up否则向下展开down。该计算只在焦点从无到有切换时触发shouldComponentUpdate中判断避免频繁重算。当展开方向为up时主题类名up会被附加到建议列表容器上Autocomplete.js配合 CSS 中的.up { bottom: 0; }实现向上对齐。键盘交互与创建新选项源码中内置了完整的键盘操作逻辑Autocomplete.js回车keyCode 13选中当前激活项或当没有激活项时若allowCreate为true则用当前 query 值创建新选项否则选中第一项下/上方向键40/38在建议项列表中循环移动激活项到头后回绕Esc27让输入框失焦退格8当showSuggestionsWhenValueIsSet为true且当前展示全部建议时会标记清空 query便于用户删除已选值。鼠标交互上每个建议项监听onMouseDown选中与onMouseOver激活高亮。多选时已选项渲染为可删除的Chip组件Autocomplete.js每个 Chip 带deletable属性点击删除会从值列表中移除对应键。受控 query配合异步数据源当multiple{false}且source是动态变化的例如每次搜索从服务端拉取候选词时需要使用query与onQueryChange对将输入框内容完全交给外部管理query 作为受控输入值传入onQueryChange在每次输入变化时回传新的 query由外部据此重新请求并更新source。从源码看componentWillReceiveProps会在单选模式下同步外部传入的queryAutocomplete.js而updateQuery在notify为真时回调onQueryChangeAutocomplete.js由此形成完整的受控闭环。主题定制Theme 表与 Input 命名空间该组件的主题类名完整定义如下官方文档 components/autocomplete/readme.md 与 Autocomplete.d.ts 一致样式实现在 theme.module.css名称说明active建议项处于激活高亮状态时使用autocomplete根元素focus输入框获得焦点时使用input用于内部Input组件suggestion每个建议项suggestions建议列表容器up建议列表向上展开时使用value单个已选项Chip的类名values已选项容器关键机制Input 主题命名空间。正如文档强调的Autocomplete 内部基于Input实现渲染时的themeNamespaceinput与theme{theme}透传见 Autocomplete.js。传入 Autocomplete 的主题对象会在input命名空间下继续传给 Input——这意味着你可以复用 Input 组件的全部主题类名但需要在前面加input前缀。例如要定制浮动标签的样式类名应为inputLabel其他诸如inputInput、inputBar、inputError等同理。这一设计使得 Autocomplete 的主题能够与 components/input/Input.js 的主题体系无缝衔接。从 theme.module.css 可以看到具体的视觉效果建议列表默认max-height: 0、visibility: hidden仅在根元素获得focus类时展开为阴影面板box-shadow: var(--zdepth-shadow-1)最大高度45vh激活项背景色为var(--autocomplete-suggestion-active-background)默认--palette-grey-200输入框右侧还有一个用 CSS 边框绘制的下拉箭头::after伪元素聚焦时通过transform过渡翻转。所有可调样式变量集中在 components/autocomplete/config.module.css包括CSS 变量默认值作用--autocomplete-overflow-max-height45vh建议列表展开后的最大高度--autocomplete-suggestion-active-backgroundvar(--palette-grey-200)激活建议项的背景色--autocomplete-suggestion-paddingvar(--unit)建议项内边距--autocomplete-suggestions-backgroundvar(--color-white)建议列表背景色--autocomplete-value-margincalc(var(--unit) * 0.25) ...已选项 Chip 的外边距--autocomplete-border-sizecalc(var(--input-field-height) / 7)输入框下拉箭头尺寸如果你是通过 Context 提供主题主题对象的键为RTAutocomplete组件同时支持通过themeprop 直接传入主题对象。组件在themr包装时启用了withRef: true见 components/autocomplete/index.js因此可通过 ref 拿到底层实例。总结React Toolbox 的 Autocomplete 是一个开箱即用的受控输入组件对象/数组双形态的source数据源、四种匹配策略、自动方向计算、键盘导航、allowCreate创建新项以及基于 Input 命名空间的完整主题体系让它在多选标签输入、异步候选搜索等场景下都足够灵活。组件源码集中在 components/autocomplete/Autocomplete.js主题样式在 theme.module.cssTypeScript 类型声明在 Autocomplete.d.ts需要扩展样式时直接参照这三个文件即可。赞分享前端UI组件【免费下载链接】react-toolboxA set of React components implementing Googles Material Design specification with the power of CSS Modules项目地址https://gitcode.com/gh_mirrors/re/react-toolbox点击查看免费下载相关推荐如何高效使用CellProfiler生物图像分析终极指南如何高效使用CellProfiler生物图像分析终极指南 生物图像分析是生命科学研究中的重要环节而CellProfiler作为一款强大的开源生物图像分析工具前端UI组件Base UI React Autocomplete 组件 API 全解析从 Root Props 到定位、过滤与无障碍实现Base UI React Autocomplete 组件 API 全解析从 Root Props 到定位、过滤与无障碍实现 本文以 Base UIbase前端UI组件react-native-paper 完全指南Material Design 3 组件库的安装、主题定制与源码级实践react native paper 完全指南Material Design 3 组件库的安装、主题定制与源码级实践 导读 本文以仓库根目录 README.前端移动开发UI组件跨平台上一篇大麦网自动化抢票脚本如何实现毫秒级响应的高效抢票方案下一篇Pyrefly v1.3.0-dev.4 发布说明解析新配置项、类型检查与语言服务器改进全解读创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考