切換按鈕群組

一組互斥的按鈕。

簡介

切換按鈕群組提供一種方式，透過共用一個容器，將互斥的動作更緊密地結合在一起。當給定其自身的 value 屬性時，它可以控制其子按鈕的選取狀態。

基礎

import ToggleButtonGroup from '@mui/joy/ToggleButtonGroup';

請注意，Joy UI 沒有提供切換按鈕元件，而是提供切換按鈕群組容器元件。原因是根據 WAI ARIA 模式，最好在按鈕或圖示按鈕元件上使用 aria-pressed。

也就是說，當使用切換按鈕群組元件時，請傳遞一個陣列作為值。當群組內的按鈕被按下時，切換按鈕群組元件會觸發其 onChange 屬性，並將更新後的陣列作為參數傳遞。

切換按鈕群組元件使用與按鈕群組元件相同的樣式，以確保所有 Joy UI 按鈕之間視覺上的一致性。

獨佔選擇

當提供給切換按鈕群組元件的值不是陣列時，它會在獨佔選擇模式下運作，這表示在群組內一次只能選取一個按鈕。

客製化

變體

切換按鈕群組元件支援 Joy UI 的四種全域變體：outlined（預設）、plain、soft 和 solid。

<ToggleButtonGroup
  variant={value || undefined}
  value={value}
  onChange={(event, newValue) => {
    setValue(newValue);
  }}
>
  <Button value="plain">plain</Button>
  <Button value="outlined">outlined</Button>
  <Button value="soft">soft</Button>
  <Button value="solid">solid</Button>
</ToggleButtonGroup>

<ToggleButtonGroup
  variant={value || undefined}
  value={value}
  onChange={(event, newValue) => {
    setValue(newValue);
  }}
>
  <Button value="plain">plain</Button>
  <Button value="outlined">outlined</Button>
  <Button value="soft">soft</Button>
  <Button value="solid">solid</Button>
</ToggleButtonGroup>

按下 Enter 開始編輯

尺寸

切換按鈕群組元件提供三種尺寸：sm、md（預設）和 lg。

<ToggleButtonGroup
  size={value || undefined}
  value={value}
  onChange={(event, newValue) => {
    setValue(newValue);
  }}
>
  <Button value="sm">Small</Button>
  <Button value="md">Medium</Button>
  <Button value="lg">Large</Button>
</ToggleButtonGroup>

<ToggleButtonGroup
  size={value || undefined}
  value={value}
  onChange={(event, newValue) => {
    setValue(newValue);
  }}
>
  <Button value="sm">Small</Button>
  <Button value="md">Medium</Button>
  <Button value="lg">Large</Button>
</ToggleButtonGroup>

按下 Enter 開始編輯

顏色

主題中包含的每個調色盤都可以透過 color 屬性使用。

間距

預設情況下，切換按鈕群組內的按鈕之間沒有間距。使用 spacing 屬性並設定大於 0 的值來分隔每個按鈕。

間距是使用 gap CSS 屬性套用的，其值取決於主題的 theme.spacing(<value>)。

若要建立響應式間距比例，<value> 可以是物件或陣列。

<ToggleButtonGroup spacing={{ xs: 0, md: 2, lg: 3 }}>…</ToggleButtonGroup>

常見範例

類似 Figma 的切換群組

使用 CSS 變數 --ButtonGroup-connected 來控制何時應移除中間按鈕的邊框半徑。

若要建立類似 Figma 的按鈕群組，當使用者懸停在任何按鈕上時，按鈕會連接在一起，請將 --ButtonGroup-connected 設定為 0，並在懸停時變更為 1。

無障礙設計

ARIA

切換按鈕群組元件具有 role="group"。請務必使用 aria-label="label"、aria-labelledby="id" 或 <label> 提供無障礙標籤。
對於切換按鈕，請根據按鈕狀態設定 aria-pressed="<bool>"。請務必使用 aria-label 標記圖示按鈕。

鍵盤

切換按鈕群組元件中的按鈕順序與 DOM 中的順序相同。使用 Tab 鍵來導航它們。

無樣式

使用 Base UI 切換按鈕群組以完全擁有元件的設計，而無需覆寫 Material UI 或 Joy UI 樣式。此元件的無樣式版本是高度客製化的理想選擇，且套件大小更小。

API

請參閱以下文件，以取得此處提及之元件的所有屬性和類別的完整參考。

切換按鈕群組

Playground