自动补全输入框

根据输入内容提供对应的输入建议。

基础用法

Autocomplete 组件提供输入建议。

fetch-suggestions 属性是返回建议输入的方法。在此示例中， querySearch(queryString, cb) 方法通过 cb(data) 给 Autocomplete 组件返回建议。

list suggestions when activated

list suggestions on input

export function AutocompleteBasic() {
  const [state1, setState1] = useState<string | number>("");
  const [state2, setState2] = useState<string | number>("");

  return (
    <div style={demoFlex}>
      <div style={demoBlock}>
        <div style={demoTitle}>list suggestions when activated</div>
        <ElAutocomplete
          value={state1}
          onChange={setState1}
          fetchSuggestions={querySearch}
          clearable
          placeholder="Please Input"
          style={{ width: 200 }}
          onSelect={handleSelect}
        />
      </div>
      <div style={demoBlock}>
        <div style={demoTitle}>list suggestions on input</div>
        <ElAutocomplete
          value={state2}
          onChange={setState2}
          fetchSuggestions={querySearch}
          triggerOnFocus={false}
          clearable
          placeholder="Please Input"
          style={{ width: 200 }}
          onSelect={handleSelect}
        />
      </div>
    </div>
  );
}

自定义模板

自定义如何显示输入建议。

使用 scoped slot 自定义输入建议。在这个范围中，你可以使用 item 键来访问当前输入建议对象。

export function AutocompleteTemplate() {
  const [state, setState] = useState<string | number>("");

  return (
    <ElAutocomplete
      value={state}
      onChange={setState}
      fetchSuggestions={querySearch}
      popperClass="my-autocomplete"
      placeholder="Please input"
      onSelect={handleSelect}
      suffix={
        <ElIcon className="el-input__icon" onClick={() => console.log("click")}>
          <Edit />
        </ElIcon>
      }
      renderItem={(item) => {
        const link = item as LinkItem;
        return (
          <>
            <div className="value">{link.value}</div>
            <span className="link">{link.link}</span>
          </>
        );
      }}
    />
  );
}

远程搜索

从服务端搜索数据。

export function AutocompleteRemoteSearch() {
  const [state, setState] = useState<string | number>("");
  const querySearchAsync = useQuerySearchAsync(1000);

  return (
    <ElAutocomplete
      value={state}
      onChange={setState}
      fetchSuggestions={querySearchAsync}
      placeholder="Please input"
      onSelect={handleSelect}
    />
  );
}

自定义加载 2.5.0

修改加载区域内容

loading icon1

loading icon2

export function AutocompleteCustomLoading() {
  const [state1, setState1] = useState<string | number>("");
  const [state2, setState2] = useState<string | number>("");
  const querySearchAsync = useQuerySearchAsync(2000);

  return (
    <div style={demoFlex}>
      <div style={demoBlock}>
        <div style={demoTitle}>loading icon1</div>
        <ElAutocomplete
          value={state1}
          onChange={setState1}
          fetchSuggestions={querySearchAsync}
          placeholder="Please input"
          style={{ width: 200 }}
          onSelect={handleSelect}
          loading={<LoadingRing />}
        />
      </div>
      <div style={demoBlock}>
        <div style={demoTitle}>loading icon2</div>
        <ElAutocomplete
          value={state2}
          onChange={setState2}
          fetchSuggestions={querySearchAsync}
          placeholder="Please input"
          style={{ width: 200 }}
          onSelect={handleSelect}
          loading={<LoadingDots />}
        />
      </div>
    </div>
  );
}

自定义头部与底部 2.10.6

你可以通过插槽来自定义下拉菜单的头部和底部。

使用插槽自定义内容。

Custom header content

Custom footer content

export function AutocompleteCustomHeaderFooter() {
  const [headerState, setHeaderState] = useState<string | number>("");
  const [footerState, setFooterState] = useState<string | number>("");
  const footerRef = useRef<AutocompleteExpose>(null);
  const querySearchAsync = useQuerySearchAsync(1000);

  return (
    <div style={{ display: "flex" }}>
      <div style={{ flex: 1, textAlign: "center" }}>
        <p style={{ margin: "0 0 16px" }}>Custom header content</p>
        <ElAutocomplete
          value={headerState}
          onChange={setHeaderState}
          fetchSuggestions={querySearchAsync}
          placeholder="Please input"
          style={{ width: "50%" }}
          onSelect={handleSelect}
          header="header content"
        />
      </div>
      <div
        style={{
          flex: 1,
          textAlign: "center",
          borderLeft: "1px solid var(--el-border-color)",
        }}
      >
        <p style={{ margin: "0 0 16px" }}>Custom footer content</p>
        <ElAutocomplete
          ref={footerRef}
          value={footerState}
          onChange={setFooterState}
          fetchSuggestions={querySearchAsync}
          placeholder="Please input"
          style={{ width: "50%" }}
          onSelect={handleSelect}
          footer={
            <ElButton
              link
              size="small"
              onClick={() => {
                setFooterState("");
                footerRef.current?.getData();
              }}
            >
              Clear
            </ElButton>
          }
        />
      </div>
    </div>
  );
}

Autocomplete API

Autocomplete Attributes

属性名	说明	类型	默认值
value	绑定值	`string` / `number`	''
placeholder	占位文本	`string`	—
clearable	是否可清空	`boolean`	false
disabled	是否禁用	`boolean`	false
read-only	原生 readonly	`boolean`	false
size	尺寸	`enum`	—
name	同原生 input 的 name	`string`	—
aria-label	原生 aria-label	`string`	—
value-key	显示与回填用的字段名	`string`	value
debounce	输入防抖延迟（毫秒）	`number`	300
placement	下拉方位	`enum`	bottom-start
fetch-suggestions	拉取建议，返回数组或调用 cb	`array` / `Function`	—
trigger-on-focus	聚焦时是否拉取建议	`boolean`	true
select-when-unmatched	无匹配时回车是否派发 select	`boolean`	false
hide-loading	远程搜索是否隐藏 loading 图标	`boolean`	false
popper-class	下拉附加类名	`string`	''
popper-style	下拉附加样式	`string` / `object`	—
popper-options	popper.js 配置	`object`	{}
show-arrow	下拉是否显示箭头	`boolean`	true
teleported	下拉是否挂在 body 上	`boolean`	true
append-to	下拉的挂载目标（选择器或元素）	`string` / `HTMLElement`	—
highlight-first-item	是否默认高亮第一条	`boolean`	false
fit-input-width	下拉宽度是否与输入框一致	`boolean`	false
loop-navigation	键盘导航是否回绕	`boolean`	true
prefix / suffix / prepend / append	Input 前后缀内容	`ReactNode`	—

Autocomplete Events

事件名	说明	参数
onChange	输入值变化	`Function`
onValueChange	失焦或回车时触发	`Function`
onSelect	点击某条建议	`Function`
onFocus	输入框聚焦	`Function`
onBlur	输入框失焦	`Function`
onClear	点击清空图标	`Function`

Autocomplete Slots

插槽名	说明	React 对应
default	自定义建议项	`renderItem(item)`
header	下拉顶部内容	`header`
footer	下拉底部内容	`footer`
loading	覆盖加载内容	`loading`
prefix / suffix / prepend / append	Input 前后缀	同名 prop

Autocomplete Exposes

通过 ref 拿到实例，暴露 focus / blur / close / handleSelect / handleKeyEnter / highlight / getData，以及只读的 activated、 loading、highlightedIndex、suggestions（官方是 Ref，这里用 getter 暴露当前值）。官方 inputRef / popperRef 对应为 input（原生 input 元素）与 popper（浮层容器元素）。