選擇器

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。

變體和顏色的值會傳遞到 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 插槽，以控制最小寬度。

Placement

若要在顯示長選項時將 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 />