Autocomplete 自动完成

搜索并从选项列表中选择，支持键盘导航和过滤。

引入

import { Autocomplete } from 'asterui'

示例

基本用法

带字符串数组选项的简单自动完成。

import { Autocomplete } from 'asterui'

function App() {
  const countries = [
    'United States',
    'United Kingdom',
    'Canada',
    'Australia',
    'Germany',
    'France',
  ]
  
  return (
      <Autocomplete
        options={countries}
        placeholder="Select a country"
      />
    )
}

export default App

对象选项

带值/标签对象选项的自动完成。

import { Autocomplete } from 'asterui'

function App() {
  const fruits = [
    { value: 'apple', label: 'Apple' },
    { value: 'banana', label: 'Banana' },
    { value: 'cherry', label: 'Cherry' },
    { value: 'orange', label: 'Orange' },
  ]
  
  return (
      <Autocomplete
        options={fruits}
        placeholder="Select a fruit"
      />
    )
}

export default App

受控模式

带状态管理的受控自动完成。

Selected: None

import { Autocomplete } from 'asterui'
import { useState } from 'react'

function App() {
  const [country, setCountry] = useState('')
  const countries = [
    'United States',
    'United Kingdom',
    'Canada',
    'Australia',
  ]
  
  return (
      <div>
        <Autocomplete
          value={country}
          onChange={setCountry}
          options={countries}
          placeholder="Select a country"
        />
        <p className="mt-2 text-sm text-base-content/70">
          Selected: {country || 'None'}
        </p>
      </div>
    )
}

export default App

允许清除

带清除按钮的自动完成。

import { Autocomplete } from 'asterui'
import { useState } from 'react'

function App() {
  const [value, setValue] = useState('Apple')
  const fruits = ['Apple', 'Banana', 'Cherry', 'Orange']
  
  return (
      <Autocomplete
        value={value}
        onChange={setValue}
        options={fruits}
        allowClear
        placeholder="Select a fruit"
      />
    )
}

export default App

不允许自定义值

仅允许从选项中选择的自动完成。

import { Autocomplete } from 'asterui'

function App() {
  const languages = [
    'JavaScript',
    'TypeScript',
    'Python',
    'Java',
    'C++',
  ]
  
  return (
      <Autocomplete
        options={languages}
        allowCustomValue={false}
        placeholder="Select a language"
      />
    )
}

export default App

自定义过滤

带自定义过滤逻辑（以...开头）的自动完成。

import { Autocomplete } from 'asterui'

function App() {
  const countries = [
    'United States',
    'United Kingdom',
    'Canada',
    'Australia',
  ]
  
  return (
      <Autocomplete
        options={countries}
        filterOption={(option, input) =>
          option.label.toLowerCase().startsWith(input.toLowerCase())
        }
        placeholder="Type to filter (starts with)"
      />
    )
}

export default App

不同尺寸

各种尺寸的自动完成。

import { Autocomplete, Space } from 'asterui'

function App() {
  const options = ['Option 1', 'Option 2', 'Option 3']
  
  return (
      <Space direction="vertical" size="sm">
        <Autocomplete size="xs" options={options} placeholder="Extra small" />
        <Autocomplete size="sm" options={options} placeholder="Small" />
        <Autocomplete size="md" options={options} placeholder="Medium" />
        <Autocomplete size="lg" options={options} placeholder="Large" />
        <Autocomplete size="xl" options={options} placeholder="Extra large" />
      </Space>
    )
}

export default App

颜色

不同的颜色变体。

import { Autocomplete, Space } from 'asterui'

function App() {
  const options = ['Option 1', 'Option 2', 'Option 3']
  
  return (
      <Space direction="vertical" size="sm">
        <Autocomplete color="primary" options={options} placeholder="Primary" />
        <Autocomplete color="secondary" options={options} placeholder="Secondary" />
        <Autocomplete color="accent" options={options} placeholder="Accent" />
        <Autocomplete color="success" options={options} placeholder="Success" />
        <Autocomplete color="warning" options={options} placeholder="Warning" />
        <Autocomplete color="error" options={options} placeholder="Error" />
      </Space>
    )
}

export default App

验证状态

用于表单反馈的带验证状态的自动完成。

This field is required

Please verify this value

import { Autocomplete, Space } from 'asterui'

function App() {
  const options = ['Option 1', 'Option 2', 'Option 3']
  
  return (
      <Space direction="vertical" size="sm">
        <div>
          <Autocomplete status="error" options={options} placeholder="Error status" />
          <p className="text-error text-sm mt-1">This field is required</p>
        </div>
        <div>
          <Autocomplete status="warning" options={options} placeholder="Warning status" />
          <p className="text-warning text-sm mt-1">Please verify this value</p>
        </div>
      </Space>
    )
}

export default App

禁用状态

禁用的自动完成。

import { Autocomplete } from 'asterui'

function App() {
  const fruits = [
    { value: 'apple', label: 'Apple' },
    { value: 'banana', label: 'Banana' },
  ]
  
  return (
      <Autocomplete
        options={fruits}
        disabled
        defaultValue="apple"
      />
    )
}

export default App

禁用选项

单个选项可以被禁用。

import { Autocomplete } from 'asterui'

function App() {
  const options = [
    { value: 'opt1', label: 'Available option' },
    { value: 'opt2', label: 'Disabled option', disabled: true },
    { value: 'opt3', label: 'Another available' },
  ]
  
  return (
      <Autocomplete
        options={options}
        placeholder="Some options are disabled"
      />
    )
}

export default App

自定义未找到内容

无结果时带自定义消息的自动完成。

import { Autocomplete } from 'asterui'

function App() {
  return (
      <Autocomplete
        options={['Apple', 'Banana', 'Cherry']}
        notFoundContent="Sorry, no matches found!"
        placeholder="Search fruits"
      />
    )
}

export default App

邮箱域名自动完成

带邮箱域名建议的实用示例。

Email: None

import { Autocomplete } from 'asterui'
import { useState } from 'react'

function App() {
  const [email, setEmail] = useState('')
  
  const domains = ['@gmail.com', '@yahoo.com', '@outlook.com', '@hotmail.com']
  
  const emailOptions = email.includes('@')
    ? domains.map(domain => email.split('@')[0] + domain)
    : domains.map(domain => email + domain)
  
  return (
      <div>
        <Autocomplete
          value={email}
          onChange={setEmail}
          options={emailOptions}
          placeholder="Enter email address"
        />
        <p className="mt-2 text-sm text-base-content/70">
          Email: {email || 'None'}
        </p>
      </div>
    )
}

export default App

在表单中

与 Form 组件集成的自动完成。

import { Autocomplete, Form, Button, Modal } from 'asterui'

function App() {
  const handleSubmit = (values: { country: string }) => {
    Modal.success({
      title: 'Form Submitted',
      content: `Country: ${values.country}`,
    })
  }
  
  return (
      <Form onFinish={handleSubmit} initialValues={{ country: 'Canada' }}>
        <Form.Item
          name="country"
          label="Country"
          required
          rules={{ required: 'Please select a country' }}
        >
          <Autocomplete
            options={['United States', 'Canada', 'United Kingdom']}
            placeholder="Select a country"
          />
        </Form.Item>
  
        <Form.Item>
          <Button htmlType="submit" color="primary">
            Submit
          </Button>
        </Form.Item>
      </Form>
    )
}

export default App

API

`Autocomplete`

属性	描述	类型	默认值
`value`	受控的值	`string`	-
`defaultValue`	默认值（非受控）	`string`	`''`
`onChange`	值改变时的回调函数	`(value: string) => void`	-
`onSelect`	选择选项时的回调函数	`(value: string, option: AutocompleteOption) => void`	-
`onSearch`	输入值改变时的回调函数（用于异步过滤）	`(value: string) => void`	-
`options`	要显示的选项数组	`string[] \| AutocompleteOption[]`	-
`placeholder`	输入占位符文本	`string`	`"Type to search..."`
`disabled`	禁用自动完成	`boolean`	`false`
`size`	输入框大小	`'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'`	`'md'`
`color`	输入框颜色变体	`'neutral' \| 'primary' \| 'secondary' \| 'accent' \| 'info' \| 'success' \| 'warning' \| 'error'`	-
`status`	验证状态（设置 aria-invalid）	`'error' \| 'warning'`	-
`allowCustomValue`	允许用户输入不在选项中的自定义值	`boolean`	`true`
`filterOption`	自定义过滤函数	`(option: AutocompleteOption, inputValue: string) => boolean`	-
`notFoundContent`	无匹配选项时显示的内容	`React.ReactNode`	`"No results found"`
`allowClear`	输入框有值时显示清除按钮	`boolean \| { clearIcon?: ReactNode }`	`false`
`onClear`	点击清除按钮时的回调函数	`() => void`	-
`open`	受控的下拉框打开状态	`boolean`	-
`defaultOpen`	默认打开状态（非受控）	`boolean`	`false`
`onOpenChange`	打开状态改变时的回调函数	`(open: boolean) => void`	-
`defaultActiveFirstOption`	过滤时默认激活第一个选项	`boolean`	`true`
`className`	额外的 CSS 类名	`string`	-
`data-testid`	用于测试的测试 ID	`string`	-

`AutocompleteOption`

属性	描述	类型	默认值
`value`	选项的值	`string`	-
`label`	选项的显示文本	`string`	-
`disabled`	选项是否被禁用	`boolean`	-
`data-testid`	用于测试的测试 ID	`string`	-

键盘导航

上 / 下 - 浏览选项
回车 - 选择高亮的选项
Esc - 关闭下拉框并失焦

无障碍

使用 role="combobox" 及适当的 ARIA 属性
下拉框使用 role="listbox" 及 role="option" 项
aria-expanded 指示下拉框打开状态
aria-activedescendant 跟踪高亮的选项
aria-selected 指示当前高亮的选项
使用 status="error" 自动设置 aria-invalid
禁用的选项使用 aria-disabled
清除按钮为屏幕阅读器提供 aria-label