AutoComplete#
数据录入
@rockshin/tao-ui为可自由输入的文本提供建议项、分组、键盘补全与自定义输入框。
每个示例都可以独立复制运行。带设备预览的示例可通过工具栏切换桌面与手机宽度。
尺寸支持 small、medium、large;兼容别名 middle 与 medium 使用相同尺寸。
#示例
#自由输入与建议项
输入值无需存在于选项列表中,使用 onChange 控制文本。
Type any email address
Value: empty
TSX
import { useState } from 'react';
import { AutoComplete } from '@rockshin/tao-ui';
const options = [
{ value: 'alice@example.com', label: 'Alice Chen' },
{ value: 'bob@example.com', label: 'Bob Li' },
{ value: 'design@example.com', label: 'Design team' },
];
export default function BasicAutoComplete() {
const [value, setValue] = useState('');
return (
<div>
<AutoComplete
value={value}
onChange={setValue}
options={options}
aria-label="Email"
placeholder="Type any email address"
allowClear
style={{ width: '100%' }}
/>
<p>Value: {value || 'empty'}</p>
</div>
);
}#按标签过滤
搜索可匹配展示标签或存储值。
Search Alice or Bob
TSX
import { AutoComplete } from '@rockshin/tao-ui';
const options = [
{ value: 'alice@example.com', label: 'Alice Chen' },
{ value: 'bob@example.com', label: 'Bob Li' },
{ value: 'design@example.com', label: 'Design team' },
];
export default function FilteredSuggestions() {
return (
<AutoComplete
options={options}
showSearch={{
filterOption: (text, option) =>
String(option?.label).toLowerCase().includes(text.toLowerCase()),
}}
placeholder="Search Alice or Bob"
style={{ width: '100%' }}
/>
);
}#键盘预填
方向键将当前建议项预填到输入框,Enter 确认选择。
Focus, then press ↓ and Enter
TSX
import { AutoComplete } from '@rockshin/tao-ui';
const options = [
{ value: 'alice@example.com', label: 'Alice Chen' },
{ value: 'bob@example.com', label: 'Bob Li' },
{ value: 'design@example.com', label: 'Design team' },
];
export default function KeyboardCompletion() {
return (
<AutoComplete
aria-label="Email completion"
options={options}
backfill
defaultActiveFirstOption
placeholder="Focus, then press ↓ and Enter"
style={{ width: '100%' }}
/>
);
}#复用自定义 Input
单个输入元素子节点会成为编辑控件,并保留自身前缀与外观。
@
TSX
import { AutoComplete, Input } from '@rockshin/tao-ui';
const options = [
{ value: 'alice@example.com', label: 'Alice Chen' },
{ value: 'bob@example.com', label: 'Bob Li' },
{ value: 'design@example.com', label: 'Design team' },
];
export default function CustomInput() {
return (
<AutoComplete options={options} style={{ width: '100%' }}>
<Input aria-label="Recipient" prefix="@" placeholder="Recipient" />
</AutoComplete>
);
}#分组建议
使用分组标签组织选项,并定制选项内容。
People and teams
TSX
import { AutoComplete } from '@rockshin/tao-ui';
export default function GroupedSuggestions() {
return (
<AutoComplete
options={[
{
label: 'People',
options: [
{ value: 'alice@example.com', label: 'Alice Chen' },
{ value: 'bob@example.com', label: 'Bob Li' },
],
},
{
label: 'Teams',
options: [{ value: 'design@example.com', label: 'Design team' }],
},
]}
optionRender={(option) => (
<div style={{ display: 'grid' }}>
<span>{option.label}</span>
<small style={{ opacity: 0.55 }}>{String(option.value)}</small>
</div>
)}
placeholder="People and teams"
style={{ width: '100%' }}
/>
);
}#延迟建议项
本地示例在输入后等待 400 毫秒,并取消上一次模拟请求。
Type a username
TSX
import { useEffect, useState } from 'react';
import { AutoComplete } from '@rockshin/tao-ui';
export default function DelayedSuggestions() {
const [value, setValue] = useState('');
const [options, setOptions] = useState<{ value: string }[]>([]);
useEffect(() => {
setOptions([]);
if (!value) return;
const timer = setTimeout(
() =>
setOptions(
['example.com', 'company.dev'].map((domain) => ({
value: `${value.split('@')[0]}@${domain}`,
})),
),
400,
);
return () => clearTimeout(timer);
}, [value]);
return (
<AutoComplete
value={value}
onChange={setValue}
options={options}
placeholder="Type a username"
style={{ width: '100%' }}
/>
);
}#外观与状态
size、variant、status 和 disabled 可覆盖 TaoProvider 默认值。
Small
Filled
Required
Alice Chen
TSX
import { AutoComplete } from '@rockshin/tao-ui';
const options = [
{ value: 'alice@example.com', label: 'Alice Chen' },
{ value: 'bob@example.com', label: 'Bob Li' },
{ value: 'design@example.com', label: 'Design team' },
];
export default function AutoCompleteAppearance() {
return (
<div style={{ display: 'grid', gap: 12 }}>
<AutoComplete options={options} size="small" placeholder="Small" />
<AutoComplete
options={options}
size="middle"
variant="filled"
placeholder="Filled"
/>
<AutoComplete
options={options}
variant="underlined"
status="error"
placeholder="Required"
/>
<AutoComplete
options={options}
disabled
defaultValue="alice@example.com"
/>
</div>
);
}#窄屏表单中的建议
在手机预览中输入、选择和清空;AutoComplete 在手机上保留可编辑输入框与弹层。
TSX
import { AutoComplete } from '@rockshin/tao-ui';
const options = [
{ value: 'alice@example.com', label: 'Alice Chen' },
{ value: 'bob@example.com', label: 'Bob Li' },
{ value: 'design@example.com', label: 'Design team' },
];
export default function MobileAutoComplete() {
return (
<div style={{ padding: 16 }}>
<h3>Invite a teammate</h3>
<AutoComplete
aria-label="Teammate email"
options={options}
placeholder="Email address"
allowClear
size="large"
listHeight={200}
style={{ width: '100%' }}
/>
</div>
);
}#API
#AutoComplete
| 属性 | 说明 | 类型 | 默认值 |
|---|