自动补全

从给定选项中搜索并选择，区分输入文字与选中值。

本指南覆盖默认 Emotion 环境的 Material UI Core；扩展包与额外示例按清单单独标注。

使用场景与业务边界

远程查询、分页和创建由宿主负责；freeSolo 可能返回字符串而不是选项对象。

原生组成与范围

TextField, Popper, Autocomplete

保持 Material UI 原生组合与类型，不替换为 JGuang／Base UI／Radix 同名 API。示例条目不是额外组件。

原生安装与初始化

npm install @mui/material@9.4.0 @emotion/react@11.14.0 @emotion/styled@11.14.1

采用原生 npm 包与 Emotion，不提供虚构的 JGuang UI Registry 地址。将示例放在原生 ThemeProvider 内，按项目选择 CssBaseline 或 ScopedCssBaseline。先检查 React、现有 Provider、锁文件与 SSR 配置；不要覆盖用户文件或忽略 peer 冲突。本批实际验收 React 19.2.8；React 18 及以下须匹配 react-is。完整初始化规则见随附的双语 setup 文档。

关键原生参数

仅解释本指南选出的关键参数，不是平铺的通用 API。原生继承来源、slot 结构、可空值与泛型仍按固定源码保留。

可运行原生示例

下列机器键只选择示例入口，不会作为通用 variant 属性传入每个组件。原生示例 JSX 与数据保持上游原文；JGuang 编写的验收示例明确标注。

• 组合框 · ComboBox · 上游原生示例
• 参数演示 · Playground · 上游原生示例
• 国家选择 · CountrySelect · 上游原生示例
• 受控状态区分 · ControllableStates · 上游原生示例
• 搜索输入 · FreeSolo · 上游原生示例
• 创建选项 · FreeSoloCreateOption · 上游原生示例
• 创建选项 · FreeSoloCreateOptionDialog · 上游原生示例
• 分组 · Grouped · 上游原生示例
• 分组 · RenderGroup · 上游原生示例
• 禁用选项 · DisabledOptions · 上游原生示例
• 原生自动补全 Hook · UseAutocomplete · 上游原生示例
• 自定义 Hook 用法 · CustomizedHook · 上游原生示例
• 打开时加载 · Asynchronous · 上游原生示例
• 单值展示 · CustomSingleValueRendering · 上游原生示例
• 多个选中值 · Tags · 上游原生示例
• 固定选项 · FixedTags · 上游原生示例
• 选择指示 · CheckboxesTags · 上游原生示例
• 限制可见标签数 · LimitTags · 上游原生示例
• 多个尺寸 · Sizes · 上游原生示例
• 自定义输入 · CustomInputAutocomplete · 上游原生示例
• 全局定制选项 · GloballyCustomizedOptions · 上游原生示例
• GitHub 风格选择器 · GitHubLabel · 上游原生示例
• 输入提示 · AutocompleteHint · 上游原生示例
• 返回值说明 · Filter · 上游原生示例

尚未支持的额外示例

这些条目仍保留在上游清单中，不静默跳过，也不展示为已完成预览。需要补充依赖／框架验收后再纳入可运行列表。

• Google 地图地点扩展 · GoogleMaps: autosuggest-highlight/parse
• 无限加载扩展 · InfiniteLoading: @tanstack/react-query, @tanstack/react-virtual
• 高亮匹配扩展 · Highlights: autosuggest-highlight/parse, autosuggest-highlight/match
• 虚拟化扩展 · Virtualize: react-window

真实使用示例

固定版本的未修改原生示例；复制时同时保留所需的局部辅助文件。

import TextField from '@mui/material/TextField';
import Autocomplete from '@mui/material/Autocomplete';
import top100Films from './top100Films';

export default function ComboBox() {
  return (
    <Autocomplete
      disablePortal
      options={top100Films}
      sx={{ width: 300 }}
      renderInput={(params) => <TextField {...params} label="Movie" />}
    />
  );
}

示例依赖边界

@mui/material/TextField, @mui/material/Autocomplete, react, @mui/material/Stack, @mui/material/Box, @mui/material/Dialog, @mui/material/DialogTitle, @mui/material/DialogContent, @mui/material/DialogContentText, @mui/material/DialogActions, @mui/material/Button, @mui/system, @mui/material/useAutocomplete, @mui/icons-material/Check, @mui/icons-material/Close, @mui/material/styles, @mui/material/CircularProgress, @mui/material/Chip, @mui/icons-material/CheckBoxOutlineBlank, @mui/icons-material/CheckBox, @mui/material/Popper, @mui/material/ClickAwayListener, @mui/icons-material/Settings, @mui/icons-material/Done, @mui/material/ButtonBase, @mui/material/InputBase, @mui/material/Typography

直接导入 Icons／System／Utils 的示例需要匹配 9.4.0 包。局部数据与辅助文件属于示例闭包，不是额外组件。远程图片和模拟操作不提供后端。

固定上游 API 元数据参考

以下表格保留上游元数据，不是重新推断的通用类型体系。条件泛型、继承属性与回调细节以以下源码声明为准。主题默认配置可能覆盖元数据默认值。

TextField

import TextField from '@mui/material/TextField';
import { TextField } from '@mui/material';

原生继承: FormControl. 父级与 DOM 属性未被伪造为本组件新属性。

Popper

import Popper from '@mui/material/Popper';
import { Popper } from '@mui/material';

Autocomplete

import Autocomplete from '@mui/material/Autocomplete';
import { Autocomplete } from '@mui/material';

原生源码声明

声明与 import 从固定源码提取，不平铺联合类型或外部继承。英文注释／类型属于原始源码参考，不代表上游正文已全文翻译。共享类型仍位于原生包中。

vendor/src/TextField/TextField.d.ts

import * as React from 'react';

import { SxProps } from '@mui/system';

import { OverridableStringUnion } from '@mui/types';

import { Theme } from '../styles';

import { InternalStandardProps as StandardProps } from '../internal';

import { FormControlProps } from '../FormControl';

import { FormHelperTextProps } from '../FormHelperText';

import { InputBaseProps } from '../InputBase';

import { InputProps as StandardInputProps } from '../Input';

import { FilledInputProps } from '../FilledInput';

import { OutlinedInputProps } from '../OutlinedInput';

import { InputLabelProps } from '../InputLabel';

import { SelectProps } from '../Select';

import { TextFieldClasses } from './textFieldClasses';

import { CreateSlotsAndSlotProps, SlotProps } from '../utils/types';

export interface TextFieldPropsColorOverrides {}

export interface TextFieldPropsSizeOverrides {}

export interface TextFieldSlots {
  /**
   * The component that renders the root.
   * @default FormControl
   */
  root: React.ElementType;
  /**
   * The component that renders the input.
   * @default OutlinedInput
   */
  input: React.ElementType;
  /**
   * The component that renders the input's label.
   * @default InputLabel
   */
  inputLabel: React.ElementType;
  /**
   * The html input element.
   * @default 'input'
   */
  htmlInput: React.ElementType;
  /**
   * The component that renders the helper text.
   * @default FormHelperText
   */
  formHelperText: React.ElementType;
  /**
   * The component that renders the select.
   * @default Select
   */
  select: React.ElementType;
}

export interface TextFieldRootSlotPropsOverrides {}

export interface TextFieldInputSlotPropsOverrides {}

export interface TextFieldInputLabelSlotPropsOverrides {}

export interface TextFieldFormHelperTextSlotPropsOverrides {}

export interface TextFieldSelectSlotPropsOverrides {}

export type TextFieldSlotsAndSlotProps<InputPropsType> = CreateSlotsAndSlotProps<
  TextFieldSlots,
  {
    /**
     * Props forwarded to the root slot.
     * By default, the available props are based on the [FormControl](https://mui.com/material-ui/api/form-control/#props) component.
     */
    root: SlotProps<
      React.ElementType<FormControlProps>,
      TextFieldRootSlotPropsOverrides,
      TextFieldOwnerState
    >;
    /**
     * Props forwarded to the input slot.
     * By default, the available props are based on the [Input](https://mui.com/material-ui/api/input/#props) component.
     */
    input: SlotProps<
      React.ElementType<InputPropsType>,
      TextFieldInputSlotPropsOverrides,
      TextFieldOwnerState
    >;
    /**
     * Props forwarded to the input label slot.
     * By default, the available props are based on the [InputLabel](https://mui.com/material-ui/api/input-label/#props) component.
     */
    inputLabel: SlotProps<
      React.ElementType<InputLabelProps>,
      TextFieldInputLabelSlotPropsOverrides,
      TextFieldOwnerState
    >;
    /**
     * Props forwarded to the html input slot.
     * By default, the available props are based on the html input element.
     */
    htmlInput: SlotProps<React.ElementType<InputBaseProps['inputProps']>, {}, TextFieldOwnerState>;
    /**
     * Props forwarded to the form helper text slot.
     * By default, the available props are based on the [FormHelperText](https://mui.com/material-ui/api/form-helper-text/#props) component.
     */
    formHelperText: SlotProps<
      React.ElementType<FormHelperTextProps>,
      TextFieldFormHelperTextSlotPropsOverrides,
      TextFieldOwnerState
    >;
    /**
     * Props forwarded to the select slot.
     * By default, the available props are based on the [Select](https://mui.com/material-ui/api/select/#props) component.
     */
    select: SlotProps<
      React.ElementType<SelectProps>,
      TextFieldSelectSlotPropsOverrides,
      TextFieldOwnerState
    >;
  }
>;

export interface BaseTextFieldProps extends StandardProps<
  FormControlProps,
  // event handlers are declared on derived interfaces
  'onChange' | 'onBlur' | 'onFocus' | 'defaultValue'
> {
  /**
   * This prop helps users to fill forms faster, especially on mobile devices.
   * The name can be confusing, as it's more like an autofill.
   * You can learn more about it [following the specification](https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#autofill).
   */
  autoComplete?: string | undefined;
  /**
   * If `true`, the `input` element is focused during the first mount.
   * @default false
   */
  autoFocus?: boolean | undefined;
  /**
   * @ignore
   */
  children?: FormControlProps['children'] | undefined;
  /**
   * Override or extend the styles applied to the component.
   */
  classes?: Partial<TextFieldClasses> | undefined;
  /**
   * The color of the component.
   * It supports both default and custom theme colors, which can be added as shown in the
   * [palette customization guide](https://mui.com/material-ui/customization/palette/#custom-colors).
   * @default 'primary'
   */
  color?:
    | OverridableStringUnion<
        'primary' | 'secondary' | 'error' | 'info' | 'success' | 'warning',
        TextFieldPropsColorOverrides
      >
    | undefined;
  /**
   * The default value. Use when the component is not controlled.
   */
  defaultValue?: unknown;
  /**
   * If `true`, the component is disabled.
   * @default false
   */
  disabled?: boolean | undefined;
  /**
   * If `true`, the label is displayed in an error state.
   * @default false
   */
  error?: boolean | undefined;
  /**
   * If `true`, the input will take up the full width of its container.
   * @default false
   */
  fullWidth?: boolean | undefined;
  /**
   * The helper text content.
   */
  helperText?: React.ReactNode;
  /**
   * The id of the `input` element.
   * Use this prop to make `label` and `helperText` accessible for screen readers.
   */
  id?: string | undefined;
  /**
   * Pass a ref to the `input` element.
   */
  inputRef?: React.Ref<any> | undefined;
  /**
   * The label content.
   */
  label?: React.ReactNode;
  /**
   * If `true`, a `textarea` element is rendered instead of an input.
   * @default false
   */
  multiline?: boolean | undefined;
  /**
   * Name attribute of the `input` element.
   */
  name?: string | undefined;
  onBlur?: InputBaseProps['onBlur'] | undefined;
  onFocus?: StandardInputProps['onFocus'] | undefined;
  /**
   * The short hint displayed in the `input` before the user enters a value.
   */
  placeholder?: string | undefined;
  /**
   * If `true`, the label is displayed as required and the `input` element is required.
   * @default false
   */
  required?: boolean | undefined;
  /**
   * Number of rows to display when multiline option is set to true.
   */
  rows?: string | number | undefined;
  /**
   * Maximum number of rows to display when multiline option is set to true.
   */
  maxRows?: string | number | undefined;
  /**
   * Minimum number of rows to display when multiline option is set to true.
   */
  minRows?: string | number | undefined;
  /**
   * Render a [`Select`](https://mui.com/material-ui/api/select/) element while passing the Input element to `Select` as `input` parameter.
   * If this option is set you must pass the options of the select as children.
   * @default false
   */
  select?: boolean | undefined;
  /**
   * The size of the component.
   * @default 'medium'
   */
  size?: OverridableStringUnion<'small' | 'medium', TextFieldPropsSizeOverrides> | undefined;
  /**
   * The system prop that allows defining system overrides as well as additional CSS styles.
   */
  sx?: SxProps<Theme> | undefined;
  /**
   * Type of the `input` element. It should be [a valid HTML5 input type](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#input_types).
   */
  type?: React.InputHTMLAttributes<unknown>['type'] | undefined;
  /**
   * The value of the `input` element, required for a controlled component.
   */
  value?: unknown;
}

export interface StandardTextFieldProps
  extends BaseTextFieldProps, TextFieldSlotsAndSlotProps<StandardInputProps> {
  /**
   * Callback fired when the value is changed.
   *
   * @param {object} event The event source of the callback.
   * You can pull out the new value by accessing `event.target.value` (string).
   */
  onChange?: StandardInputProps['onChange'] | undefined;
  /**
   * The variant to use.
   * @default 'outlined'
   */
  variant?: 'standard' | undefined;
}

export interface FilledTextFieldProps
  extends BaseTextFieldProps, TextFieldSlotsAndSlotProps<FilledInputProps> {
  /**
   * Callback fired when the value is changed.
   *
   * @param {object} event The event source of the callback.
   * You can pull out the new value by accessing `event.target.value` (string).
   */
  onChange?: FilledInputProps['onChange'] | undefined;
  /**
   * The variant to use.
   * @default 'outlined'
   */
  variant: 'filled';
}

export interface OutlinedTextFieldProps
  extends BaseTextFieldProps, TextFieldSlotsAndSlotProps<OutlinedInputProps> {
  /**
   * Callback fired when the value is changed.
   *
   * @param {object} event The event source of the callback.
   * You can pull out the new value by accessing `event.target.value` (string).
   */
  onChange?: OutlinedInputProps['onChange'] | undefined;
  /**
   * The variant to use.
   * @default 'outlined'
   */
  variant: 'outlined';
}

export type TextFieldVariants = 'outlined' | 'standard' | 'filled';

export type TextFieldProps<Variant extends TextFieldVariants = TextFieldVariants> =
  Variant extends 'filled'
    ? FilledTextFieldProps
    : Variant extends 'standard'
      ? StandardTextFieldProps
      : OutlinedTextFieldProps;

export type TextFieldOwnerState = BaseTextFieldProps;

export default function TextField<Variant extends TextFieldVariants>(
  props: {
    /**
     * The variant to use.
     * @default 'outlined'
     */
    variant?: Variant | undefined;
  } & Omit<TextFieldProps, 'variant'>,
): React.JSX.Element;

vendor/src/Popper/Popper.tsx

import { SxProps } from '@mui/system';

import { useRtl } from '@mui/system/RtlProvider';

import refType from '@mui/utils/refType';

import HTMLElementType from '@mui/utils/HTMLElementType';

import PropTypes from 'prop-types';

import * as React from 'react';

import BasePopper from './BasePopper';

import { PopperProps as BasePopperProps } from './BasePopper.types';

import { Theme } from '../styles';

import { styled } from '../zero-styled';

import { useDefaultProps } from '../DefaultPropsProvider';

export interface PopperProps extends Omit<BasePopperProps, 'direction'> {
  /**
   * The component used for the root node.
   * Either a string to use a HTML element or a component.
   */
  component?: React.ElementType | undefined;
  /**
   * The system prop that allows defining system overrides as well as additional CSS styles.
   */
  sx?: SxProps<Theme> | undefined;
}

vendor/src/Autocomplete/Autocomplete.d.ts

import * as React from 'react';

import { SxProps } from '@mui/system';

import { OverridableStringUnion } from '@mui/types';

import { Theme } from '../styles';

import { InternalStandardProps as StandardProps } from '../internal';

import { IconButtonProps } from '../IconButton';

import { ChipProps, ChipTypeMap } from '../Chip';

import { PaperProps } from '../Paper';

import { PopperProps } from '../Popper';

import useAutocomplete, {
  AutocompleteChangeDetails,
  AutocompleteChangeReason,
  AutocompleteCloseReason,
  AutocompleteInputChangeReason,
  AutocompleteValue,
  createFilterOptions,
  UseAutocompleteProps,
  AutocompleteFreeSoloValueMapping,
  AutocompleteValueOrFreeSoloValueMapping,
} from '../useAutocomplete';

import { AutocompleteClasses } from './autocompleteClasses';

import { CreateSlotsAndSlotProps, SlotProps } from '../utils/types';

export interface AutocompletePaperSlotPropsOverrides {}

export interface AutocompletePopperSlotPropsOverrides {}

export interface AutocompleteStatusSlotPropsOverrides {}

export type AutocompleteOwnerState<
  Value,
  Multiple extends boolean | undefined,
  DisableClearable extends boolean | undefined,
  FreeSolo extends boolean | undefined,
  ChipComponent extends React.ElementType = ChipTypeMap['defaultComponent'],
> = AutocompleteProps<Value, Multiple, DisableClearable, FreeSolo, ChipComponent> & {
  disablePortal: boolean;
  expanded: boolean;
  focused: boolean;
  fullWidth: boolean;
  getOptionLabel: (option: AutocompleteValueOrFreeSoloValueMapping<Value, FreeSolo>) => string;
  hasClearIcon: boolean;
  hasPopupIcon: boolean;
  inputFocused: boolean;
  popupOpen: boolean;
  size: OverridableStringUnion<'small' | 'medium', AutocompletePropsSizeOverrides>;
};

export type AutocompleteRenderGetTagProps = ({ index }: { index: number }) => {
  key: number;
  className: string;
  disabled: boolean;
  'data-tag-index': number;
  tabIndex: -1;
  onDelete: (event: any) => void;
};

export type AutocompleteRenderValueGetItemProps<Multiple extends boolean | undefined> =
  Multiple extends true
    ? (args: { index: number }) => {
        key: number;
        className: string;
        disabled: boolean;
        'data-item-index': number;
        tabIndex: -1;
        onDelete: (event: any) => void;
      }
    : (args?: { index?: number | undefined }) => {
        className: string;
        disabled: boolean;
        'data-item-index': number;
        tabIndex: -1;
        onDelete: (event: any) => void;
      };

export type AutocompleteRenderValue<Value, Multiple, FreeSolo> = Multiple extends true
  ? Array<Value | AutocompleteFreeSoloValueMapping<FreeSolo>>
  : NonNullable<Value | AutocompleteFreeSoloValueMapping<FreeSolo>>;

export interface AutocompleteRenderOptionState {
  inputValue: string;
  index: number;
  selected: boolean;
}

export interface AutocompleteRenderGroupParams {
  key: number;
  group: string;
  children?: React.ReactNode;
}

export interface AutocompleteRenderInputParams {
  id: string;
  disabled: boolean;
  fullWidth: boolean;
  size: 'small' | undefined;
  slotProps: {
    inputLabel: ReturnType<ReturnType<typeof useAutocomplete>['getInputLabelProps']>;
    input: {
      ref: React.Ref<any>;
      className: string;
      startAdornment: React.ReactNode;
      endAdornment: React.ReactNode;
      onMouseDown: React.MouseEventHandler;
    };
    htmlInput: ReturnType<ReturnType<typeof useAutocomplete>['getInputProps']>;
  };
}

export interface AutocompletePropsSizeOverrides {}

export interface AutocompleteSlots {
  /**
   * The component that renders the root.
   * @default 'div'
   */
  root: React.ElementType;
  /**
   * The component used to render the clear indicator element.
   * @default IconButton
   */
  clearIndicator: React.JSXElementConstructor<IconButtonProps>;
  /**
   * The component used to render the popup indicator element.
   * @default IconButton
   */
  popupIndicator: React.JSXElementConstructor<IconButtonProps>;
  /**
   * The component used to render the listbox.
   * @default 'ul'
   */
  listbox: React.JSXElementConstructor<React.HTMLAttributes<HTMLElement>>;
  /**
   * The component used to render the status message container.
   * @default 'div'
   */
  status: React.ElementType;
  /**
   * The component used to render the body of the popup.
   * @default Paper
   */
  paper: React.JSXElementConstructor<PaperProps & AutocompletePaperSlotPropsOverrides>;
  /**
   * The component used to position the popup.
   * @default Popper
   */
  popper: React.JSXElementConstructor<PopperProps & AutocompletePopperSlotPropsOverrides>;
}

export type AutocompleteSlotsAndSlotProps<
  Value,
  Multiple extends boolean | undefined,
  DisableClearable extends boolean | undefined,
  FreeSolo extends boolean | undefined,
  ChipComponent extends React.ElementType = ChipTypeMap['defaultComponent'],
> = CreateSlotsAndSlotProps<
  AutocompleteSlots,
  {
    root: SlotProps<
      'div',
      {},
      AutocompleteOwnerState<Value, Multiple, DisableClearable, FreeSolo, ChipComponent>
    >;
    chip: SlotProps<
      React.ElementType<Partial<ChipProps<ChipComponent>>>,
      {},
      AutocompleteOwnerState<Value, Multiple, DisableClearable, FreeSolo, ChipComponent>
    >;
    clearIndicator: SlotProps<
      React.ElementType<Partial<IconButtonProps>>,
      {},
      AutocompleteOwnerState<Value, Multiple, DisableClearable, FreeSolo, ChipComponent>
    >;
    /**
     * Props applied to the Listbox element.
     */
    listbox: SlotProps<
      React.ElementType<
        ReturnType<ReturnType<typeof useAutocomplete>['getListboxProps']> & {
          sx?: SxProps<Theme> | undefined;
          ref?: React.Ref<Element> | undefined;
        }
      >,
      {},
      AutocompleteOwnerState<Value, Multiple, DisableClearable, FreeSolo, ChipComponent>
    >;
    status: SlotProps<
      'div',
      AutocompleteStatusSlotPropsOverrides,
      AutocompleteOwnerState<Value, Multiple, DisableClearable, FreeSolo, ChipComponent>
    >;
    paper: SlotProps<
      React.ElementType<Partial<PaperProps>>,
      AutocompletePaperSlotPropsOverrides,
      AutocompleteOwnerState<Value, Multiple, DisableClearable, FreeSolo, ChipComponent>
    >;
    popper: SlotProps<
      React.ElementType<Partial<PopperProps>>,
      AutocompletePopperSlotPropsOverrides,
      AutocompleteOwnerState<Value, Multiple, DisableClearable, FreeSolo, ChipComponent>
    >;
    popupIndicator: SlotProps<
      React.ElementType<Partial<IconButtonProps>>,
      {},
      AutocompleteOwnerState<Value, Multiple, DisableClearable, FreeSolo, ChipComponent>
    >;
  }
>;

export interface AutocompleteProps<
  Value,
  Multiple extends boolean | undefined,
  DisableClearable extends boolean | undefined,
  FreeSolo extends boolean | undefined,
  ChipComponent extends React.ElementType = ChipTypeMap['defaultComponent'],
>
  extends
    UseAutocompleteProps<Value, Multiple, DisableClearable, FreeSolo>,
    StandardProps<React.HTMLAttributes<HTMLDivElement>, 'defaultValue' | 'onChange' | 'children'>,
    AutocompleteSlotsAndSlotProps<Value, Multiple, DisableClearable, FreeSolo, ChipComponent> {
  /**
   * Override or extend the styles applied to the component.
   */
  classes?: Partial<AutocompleteClasses> | undefined;
  /**
   * The icon to display in place of the default clear icon.
   * @default <ClearIcon fontSize="small" />
   */
  clearIcon?: React.ReactNode;
  /**
   * Override the default text for the *clear* icon button.
   *
   * For localization purposes, you can use the provided [translations](https://mui.com/material-ui/guides/localization/).
   * @default 'Clear'
   */
  clearText?: string | undefined;
  /**
   * Override the default text for the *close popup* icon button.
   *
   * For localization purposes, you can use the provided [translations](https://mui.com/material-ui/guides/localization/).
   * @default 'Close'
   */
  closeText?: string | undefined;
  /**
   * If `true`, the component is disabled.
   * @default false
   */
  disabled?: boolean | undefined;
  /**
   * If `true`, the `Popper` content will be under the DOM hierarchy of the parent component.
   * @default false
   */
  disablePortal?: boolean | undefined;
  /**
   * Force the visibility display of the popup icon.
   * @default 'auto'
   */
  forcePopupIcon?: true | false | 'auto' | undefined;
  /**
   * If `true`, the input takes up the full width of its container.
   *
   * `Autocomplete` treats `undefined` and `false` differently.
   * If `undefined`, the inner input takes up the full width of its container.
   * If `false`, the inner input is restricted to its intrinsic width.
   * @default false
   */
  fullWidth?: boolean | undefined;
  /**
   * The label to display when the tags are truncated (`limitTags`).
   *
   * @param {number} more The number of truncated tags.
   * @returns {ReactNode}
   * @default (more) => `+${more}`
   */
  getLimitTagsText?: ((more: number) => React.ReactNode) | undefined;
  /**
   * If `true`, the component is in a loading state.
   * This shows the `loadingText` in place of suggestions (only if there are no suggestions to show, for example `options` are empty).
   * @default false
   */
  loading?: boolean | undefined;
  /**
   * Text to display when in a loading state.
   *
   * For localization purposes, you can use the provided [translations](https://mui.com/material-ui/guides/localization/).
   * @default 'Loading…'
   */
  loadingText?: React.ReactNode;
  /**
   * The maximum number of tags that will be visible when not focused.
   * Set `-1` to disable the limit.
   * @default -1
   */
  limitTags?: number | undefined;
  /**
   * Text to display when there are no options.
   *
   * For localization purposes, you can use the provided [translations](https://mui.com/material-ui/guides/localization/).
   * @default 'No options'
   */
  noOptionsText?: React.ReactNode;
  onKeyDown?:
    | ((
        event: React.KeyboardEvent<HTMLDivElement> & { defaultMuiPrevented?: boolean | undefined },
      ) => void)
    | undefined;
  /**
   * Override the default text for the *open popup* icon button.
   *
   * For localization purposes, you can use the provided [translations](https://mui.com/material-ui/guides/localization/).
   * @default 'Open'
   */
  openText?: string | undefined;
  /**
   * The icon to display in place of the default popup icon.
   * @default <ArrowDropDownIcon />
   */
  popupIcon?: React.ReactNode;
  /**
   * If `true`, the component becomes readonly. It is also supported for multiple tags where the tag cannot be deleted.
   * @default false
   */
  readOnly?: boolean | undefined;
  /**
   * Render the group.
   *
   * @param {AutocompleteRenderGroupParams} params The group to render.
   * @returns {ReactNode}
   */
  renderGroup?: ((params: AutocompleteRenderGroupParams) => React.ReactNode) | undefined;
  /**
   * Render the input.
   *
   * **Note:** The `renderInput` prop must return a `TextField` component or a compatible custom component
   * that correctly forwards `InputProps.ref` and spreads `inputProps`. This ensures proper integration
   * with the Autocomplete's internal logic (e.g., focus management and keyboard navigation).
   *
   * Avoid using components like `DatePicker` or `Select` directly, as they may not forward the required props,
   * leading to runtime errors or unexpected behavior.
   *
   * @param {object} params
   * @returns {ReactNode}
   */
  renderInput: (params: AutocompleteRenderInputParams) => React.ReactNode;
  /**
   * Render the option, use `getOptionLabel` by default.
   *
   * @param {object} props The props to apply on the li element.
   * @param {Value} option The option to render.
   * @param {object} state The state of each option.
   * @param {object} ownerState The state of the Autocomplete component.
   * @returns {ReactNode}
   */
  renderOption?:
    | ((
        props: React.HTMLAttributes<HTMLLIElement> & { key: React.Key },
        option: Value,
        state: AutocompleteRenderOptionState,
        ownerState: AutocompleteOwnerState<
          Value,
          Multiple,
          DisableClearable,
          FreeSolo,
          ChipComponent
        >,
      ) => React.ReactNode)
    | undefined;
  /**
   * Renders the selected value(s) as rich content in the input for both single and multiple selections.
   *
   * @param {AutocompleteRenderValue<Value, Multiple, FreeSolo>} value The `value` provided to the component.
   * @param {function} getItemProps The value item props.
   * @param {object} ownerState The state of the Autocomplete component.
   * @returns {ReactNode}
   */
  renderValue?:
    | ((
        value: AutocompleteRenderValue<Value, Multiple, FreeSolo>,
        getItemProps: AutocompleteRenderValueGetItemProps<Multiple>,
        ownerState: AutocompleteOwnerState<
          Value,
          Multiple,
          DisableClearable,
          FreeSolo,
          ChipComponent
        >,
      ) => React.ReactNode)
    | undefined;
  /**
   * The size of the component.
   * @default 'medium'
   */
  size?: OverridableStringUnion<'small' | 'medium', AutocompletePropsSizeOverrides> | undefined;
  /**
   * The system prop that allows defining system overrides as well as additional CSS styles.
   */
  sx?: SxProps<Theme> | undefined;
}

export default function Autocomplete<
  Value,
  Multiple extends boolean | undefined = false,
  DisableClearable extends boolean | undefined = false,
  FreeSolo extends boolean | undefined = false,
  ChipComponent extends React.ElementType = ChipTypeMap['defaultComponent'],
>(
  props: AutocompleteProps<Value, Multiple, DisableClearable, FreeSolo, ChipComponent>,
): React.JSX.Element;

安装后验收

执行严格类型检查、生产构建和实际交互。检查键盘标签／焦点、原生支持的禁用／错误／只读语义、深浅色、窄屏和减少动画。按真实宿主数据检查回调，不把复制提示词当作安装完成。初始化工具还需检查服务端 HTML 与无告警水合。

来源与许可

https://github.com/mui/material-ui/tree/809a7717b4c050ba3f69b75300689f07c050a16e

MIT · @mui/material@9.4.0. 保留上游原始内容与许可证。上游完整原文保留于 vendor/docs，不标为全文中文化。