AutoComplete 自动完成

在输入文本时提供建议，帮助快速完成填写。

基础输入

通过 options 设置建议，默认按显示文本进行不区分大小写的包含匹配。onChange 响应输入和选择，onSelect 仅响应选择建议。

交互预览输入与选择建议

输入：空 · 最近选中：无

basic.tsx

import { AutoComplete } from '@sudden3/leaf-ui';
import { useState } from 'react';

const options = [
  { value: 'Leaf Garden' },
  { value: 'Leaf Studio' },
  { value: 'Pine Forest' },
  { value: 'Archived Garden', disabled: true },
];

export function AutoCompleteBasic() {
  const [value, setValue] = useState('');
  const [selected, setSelected] = useState('');
  return (
    <div className="leaf-demo-stack">
      <AutoComplete
        aria-label="项目名称"
        placeholder="输入 Leaf 或自由填写"
        options={options}
        value={value}
        onChange={setValue}
        onSelect={setSelected}
      />
      <span className="leaf-demo-note">
        输入：{value || '空'} · 最近选中：{selected || '无'}
      </span>
      <AutoComplete aria-label="禁用建议" options={options} disabled defaultValue="Leaf Garden" />
    </div>
  );
}

动态建议

onSearch 接收用户输入。建议由你生成或从服务端获取时，可设置 filterOption={false} 直接展示传入结果。

交互预览动态邮箱建议

建议由输入动态生成，也可以直接填写完整地址。

search.tsx

import { AutoComplete, type AutoCompleteOption } from '@sudden3/leaf-ui';
import { useState } from 'react';

export function AutoCompleteSearch() {
  const [options, setOptions] = useState<AutoCompleteOption[]>([]);
  return (
    <div className="leaf-demo-stack">
      <AutoComplete
        aria-label="邮箱地址"
        placeholder="输入邮箱前缀"
        options={options}
        filterOption={false}
        onSearch={(query) => {
          const prefix = query.split('@')[0] ?? '';
          setOptions(
            prefix
              ? ['gmail.com', 'outlook.com', 'icloud.com'].map((domain) => ({
                  value: `${prefix}@${domain}`,
                }))
              : [],
          );
        }}
      />
      <span className="leaf-demo-note">建议由输入动态生成，也可以直接填写完整地址。</span>
    </div>
  );
}

异步搜索时，在应用中处理请求防抖和响应顺序，避免旧查询覆盖新结果。输入过程中允许保留自由文本。

AutoComplete API

属性	类型	默认值	说明
`options`	`readonly AutoCompleteOption[]`	必填	建议列表
`value` / `defaultValue`	`string`	`''`	受控文本 / 非受控初始文本
`onChange`	`(value: string) => void`	—	输入或选择后的文本
`onSelect`	`(value: string, option: AutoCompleteOption) => void`	—	选择建议时触发
`onSearch`	`(query: string) => void`	—	用户输入时触发，选择建议时不触发
`filterOption`	`false \| ((query: string, option: AutoCompleteOption) => boolean)`	包含匹配	`false` 关闭本地过滤；函数可定制过滤
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	输入框尺寸
`status`	`'error' \| 'warning'`	—	校验状态
`disabled` / `readOnly`	`boolean`	`false`	禁用 / 只读时不打开建议面板
`ref`	`Ref<HTMLInputElement>`	—	输入框引用

label 默认为 value；选中后输入框中的文本始终是 value。placeholder、name、required、form、maxLength、aria-* 等原生文本框属性直接透传，className / style 作用于外层容器。

类型

AutoCompleteProps 用于定义组件属性。单独组装建议列表时，可以使用 AutoCompleteOption：

import type { AutoCompleteProps, AutoCompleteOption, ControlSize, ControlStatus } from '@sudden3/leaf-ui';

const options: AutoCompleteOption[] = [
  { value: 'leaf@example.com' },
  { value: 'hello@example.com', label: '联系团队' },
];

AutoCompleteOption

属性	类型	默认值	说明
`value`	`string`	必填	唯一建议值，选择后填入输入框
`label`	`string`	`value`	建议的显示文字，也用于默认的本地过滤
`disabled`	`boolean`	`false`	禁用该建议

键盘与表单

输入框聚焦或输入时展开建议。↑ / ↓ 高亮可用选项，Enter 选择，Escape 收起，Tab 继续访问后续控件。中文输入法合成期间的 Enter 不会选择建议。没有匹配项时可以继续填写。

输入框可以直接参与 FormData、原生必填校验和表单 reset。建议面板跟随输入框宽度并继承局部主题；为输入框提供 label 或 aria-label。

#AutoComplete 自动完成

#基础输入

#动态建议

#AutoComplete API

#类型

#AutoCompleteOption