按鈕群組

按鈕群組將一組相關的按鈕組合在一起。

簡介

按鈕群組元件將一組具有相似或相關功能的按鈕組合在一起。

<ButtonGroup>
  <Button />
  ...
  <IconButton />
</ButtonGroup>

基本用法

按鈕群組元件可以包裝 Button 和 IconButton。

<ButtonGroup aria-label="outlined primary button group">
  <Button>One</Button>
  <Button>Two</Button>
  <Button>Three</Button>
  <IconButton>
    <Settings />
  </IconButton>
</ButtonGroup>

<ButtonGroup aria-label="outlined primary button group">
  <Button>One</Button>
  <Button>Two</Button>
  <Button>Three</Button>
  <IconButton>
    <Settings />
  </IconButton>
</ButtonGroup>

按下 Enter 鍵開始編輯

客製化

變體

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

variant 屬性會傳遞給按鈕，而不是按鈕群組本身。

尺寸

按鈕群組元件提供三種尺寸：sm、md (預設) 和 lg。

<ButtonGroup size="sm" aria-label="outlined button group">
  <Button>One</Button>
  <Button>Two</Button>
  <Button>Three</Button>
</ButtonGroup>
<ButtonGroup aria-label="plain button group">
  <Button>One</Button>
  <Button>Two</Button>
  <Button>Three</Button>
</ButtonGroup>
<ButtonGroup size="lg" aria-label="soft button group">
  <Button>One</Button>
  <Button>Two</Button>
  <Button>Three</Button>
</ButtonGroup>

<ButtonGroup size="sm" aria-label="outlined button group">
  <Button>One</Button>
  <Button>Two</Button>
  <Button>Three</Button>
</ButtonGroup>
<ButtonGroup aria-label="plain button group">
  <Button>One</Button>
  <Button>Two</Button>
  <Button>Three</Button>
</ButtonGroup>
<ButtonGroup size="lg" aria-label="soft button group">
  <Button>One</Button>
  <Button>Two</Button>
  <Button>Three</Button>
</ButtonGroup>

按下 Enter 鍵開始編輯

顏色

主題中包含的每個調色盤都可以透過 color 屬性使用。試著搭配不同的顏色和不同的變體。

停用

使用 disabled 屬性來停用所有按鈕。請注意，如果您直接在按鈕上明確指定 disabled 屬性，它將會覆寫按鈕群組中使用的屬性。

<ButtonGroup disabled aria-label="disabled button group">
  <Button>One</Button>
  <Button>Two</Button>
  <Button>Three</Button>
  <IconButton disabled={false}>
    <Settings />
  </IconButton>
</ButtonGroup>

<ButtonGroup disabled aria-label="disabled button group">
  <Button>One</Button>
  <Button>Two</Button>
  <Button>Three</Button>
  <IconButton disabled={false}>
    <Settings />
  </IconButton>
</ButtonGroup>

按下 Enter 鍵開始編輯

間距

使用 spacing 屬性來控制按鈕之間的間隙。如果 spacing 設定為 0 (預設)，則會調整按鈕的半徑以形成連續的表面。

<ButtonGroup spacing="0.5rem" aria-label="spacing button group">
  <Button>One</Button>
  <Button disabled>Two</Button>
  <Button>Three</Button>
  <IconButton>
    <Settings />
  </IconButton>
</ButtonGroup>

<ButtonGroup spacing="0.5rem" aria-label="spacing button group">
  <Button>One</Button>
  <Button disabled>Two</Button>
  <Button>Three</Button>
  <IconButton>
    <Settings />
  </IconButton>
</ButtonGroup>

按下 Enter 鍵開始編輯

值的類型可以是

string：任何有效的 CSS 長度單位，例如 px、rem、em 等。
number：將由 theme.spacing 函數計算。
array：基於主題中定義的斷點的響應式值。
object：鍵必須是主題中定義的斷點之一 (預設值為 "xs" | "sm" | "md" | "lg" | "xl")，而值是 string 或 number 類型的間距。

<ButtonGroup spacing={{ xs: 0, sm: 1, md: '2rem' }}>...</ButtonGroup>

垂直群組

可以使用 orientation="vertical" 屬性垂直顯示按鈕群組元件。請注意，此屬性對 IconButton 元件沒有影響。

延展按鈕

使用 buttonFlex 屬性使按鈕填滿按鈕群組元件的可用空間。

最小寬度

對於大型容器，透過為 buttonFlex 屬性提供有效的 CSS flex 值來控制按鈕的預設寬度。

標題

Lorem Ipsum 僅為印刷和排版行業的示範文字。

分割按鈕

按鈕群組元件也可以用於建立分割按鈕。下拉選單可以變更按鈕動作 (如本範例所示)，或用於立即觸發相關動作。

分隔線顏色

當按鈕群組的變體不是 outlined 時，會在按鈕之間建立分隔線。若要控制分隔線的顏色，請透過 sx 屬性覆寫 CSS 變數 --ButtonGroup-separatorColor。

hsl(0 100% 50%)

按鈕群組元件支援包裝按鈕的任意子元件，同時保持相同的外觀。

<ButtonGroup variant="soft" aria-label="tooltip button group">
  <Tooltip arrow title="Go to profile">
    <Button startDecorator={<Person />}>Hover me</Button>
  </Tooltip>
  <Tooltip arrow title="Open settings">
    <span>
      <IconButton disabled>
        <Settings />
      </IconButton>
    </span>
  </Tooltip>
  <Tooltip arrow title="Go to profile">
    <Button endDecorator={<Person />}>Hover me</Button>
  </Tooltip>
</ButtonGroup>

<ButtonGroup variant="soft" aria-label="tooltip button group">
  <Tooltip arrow title="Go to profile">
    <Button startDecorator={<Person />}>Hover me</Button>
  </Tooltip>
  <Tooltip arrow title="Open settings">
    <span>
      <IconButton disabled>
        <Settings />
      </IconButton>
    </span>
  </Tooltip>
  <Tooltip arrow title="Go to profile">
    <Button endDecorator={<Person />}>Hover me</Button>
  </Tooltip>
</ButtonGroup>

按下 Enter 鍵開始編輯

常見範例

膠囊按鈕群組

使用 CSS 變數 --ButtonGroup-radius 來控制開始和結束按鈕的半徑。

<ButtonGroup
  aria-label="radius button group"
  sx={{ '--ButtonGroup-radius': '40px' }}
>
  <Button>One</Button>
  <Button>Two</Button>
  <Button>Three</Button>
  <IconButton>
    <Settings />
  </IconButton>
</ButtonGroup>

<ButtonGroup
  aria-label="radius button group"
  sx={{ '--ButtonGroup-radius': '40px' }}
>
  <Button>One</Button>
  <Button>Two</Button>
  <Button>Three</Button>
  <IconButton>
    <Settings />
  </IconButton>
</ButtonGroup>

按下 Enter 鍵開始編輯

自訂分隔線

此範例使用 Divider 元件在按鈕之間建立自訂分隔線。然後使用任意值設定 CSS 變數 --ButtonGroup-separatorColor，以移除預設分隔線。

API

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

按鈕群組

簡介

Playground

基本用法

客製化

變體

尺寸

顏色

停用

間距

垂直群組

延展按鈕

最小寬度

分割按鈕

分隔線顏色

與工具提示一起使用

常見範例

膠囊按鈕群組

自訂分隔線

API