Select

Select 组件用于从选项列表中收集用户提供的信息。

简介

Select 组件用于触发一个弹出窗口，其中显示 Option 组件的列表。

组件

在安装之后，您可以使用以下基本元素开始构建此组件

import Select from '@mui/joy/Select';
import Option from '@mui/joy/Option';

export default function SelectBasic() {
  return (
    <Select defaultValue="dog">
      <Option value="dog">Dog</Option>
      <Option value="cat">Cat</Option>
    </Select>
  );
}

基本用法

Select 组件类似于原生 HTML 的 <select> 和 <option> 标签。

表单提交

Select 组件支持 name 和 required 属性，这些属性将在提交表单时使用。

变体

Select 组件支持四种全局变体：outlined（默认）、plain、soft 和 solid。

variant 和 color 值会传播到 Select 的 button 和 listbox 插槽。

要自定义特定插槽的变体和颜色，请使用 slotProps

<Select
  variant="plain"
  slotProps={{
    listbox: {
      variant: 'outlined',
    },
  }}
/>

装饰器

使用 startDecorator 和/或 endDecorator 属性向 select 添加支持图标或元素。

如果您的 select 装饰器中有交互式元素，请从鼠标按下事件中调用 stopPropagation() 以防止弹出窗口打开。

<IconButton
  onMouseDown={(event) => {
    // don't open the popup when clicking on this button
    event.stopPropagation();
  }}
  onClick={() => {
    // click handler goes here
  }
>...</IconButton>

指示器

要更改默认指示器，请将 indicator 属性与任何 React 元素（包括字符串）或 null 值一起使用（以完全删除指示器）。

要将指示器应用于 select 组件的所有实例，请直接在主题中自定义 indicator 属性

import { extendTheme, CssVarsProvider } from '@mui/joy/styles';
import Select from '@mui/joy/Select';

const theme = extendTheme({
  components: {
    JoySelect: {
      defaultProps: {
        indicator: '↕',
      },
    },
  },
});

const App = () => (
  <CssVarsProvider theme={theme}>
    <Select>...options</Select>
  </CssVarsProvider>
);

多项选择

设置 multiple 属性以允许用户从列表中选择多个选项。与单选模式相反，选项弹出窗口在选择项目后不会关闭，这使用户可以继续选择更多选项。

请注意，在多选模式下，value 属性（和 defaultValue）是一个数组。

选定值的显示外观

使用 renderValue 属性自定义选定选项的显示。

表单提交

Select 组件支持 name 和 required 属性，这些属性将在提交表单时使用。

Listbox

最大高度

要更改 listbox 的最大高度，请使用 slotProps 属性来定位 listbox 插槽

<Select
  slotProps={{
    listbox: {
      sx: {
        maxHeight: '300px',
      },
    },
  }}
>
  ...
</Select>

最小宽度

默认情况下，listbox 的宽度等于 Select 的按钮或其子元素的最大内容。您可以使用 slotProps 属性定位 listbox 插槽来控制最小宽度。

放置

要在显示长选项时将 listbox 位置与 Select 对齐，请使用 slotProps 属性来定位 listbox 插槽

控制打开状态

您可以使用 listboxOpen 属性控制 select 的打开状态。或者，也可以使用 defaultListboxOpen 属性设置组件的初始（非受控）打开状态。

Option 组件

Option 组件用于 select 中的可选选项。

选定的选项继承 Select 父组件的 color，默认情况下使用 primary 调色板。但是，它不继承 Select 使用的 variant。

ListItemButton 组件与此组件非常相似，因为它们共享相同的内部样式。实际上，您可以将它们混合在一起以组成各种设计。

在下面的演示中，我们使用 ListItemDecorator 来提供头像之间的空间。我们还使用 ListDivider 作为视觉分隔符。

分组选项

要创建带有分组选项的 listbox，请使用 List 组件包装 Option，并使用 ListItem 提供关联的标签。这样，您将拥有一致的高度，并且能够利用嵌套的 CSS 变量。

可访问性

为了使 select 可访问，它应该链接到一个标签。

FormControl 自动生成一个唯一的 ID，将 select 与 FormLabel 组件链接起来

或者，您可以通过定位 button 插槽手动执行此操作

<label htmlFor="select-button" id="select-label">Label</label>
<Select
  slotProps={{
    button: {
      id: 'select-button',
      'aria-labelledby': 'select-label select-button',
    }
  }}
>
  <Option value="option1">Option I</Option>
  <Option value="option2">Option II</Option>
</Select>

常见示例

清除操作

使用 IconButton 组件作为 Select 的装饰器以添加清除操作。

在清除 select 值后，Select 会将焦点可见状态设置回 select 按钮，从而确保出色的键盘导航体验。

选定值的显示外观

当选项被选中时，select 将显示 label 属性的值。

该值可以是 string、number 或任何有效的 React 元素。

调试

要保持 listbox 打开以检查元素，请从 Chrome DevTool Rendering 选项卡启用 Emulate a focused page 选项。您还可以通过使用 命令菜单并搜索它来访问此选项。

无样式

使用 Base UI Select 完全拥有组件的设计，而无需覆盖 Material UI 或 Joy UI 样式。此组件的无样式版本是进行大量自定义和缩小捆绑包大小的理想选择。

API

请参阅下面的文档，以获取此处提及的组件的所有可用属性和类的完整参考。

• <Option />
• <Select />