106k
New

按钮组 Button Group

PreviousNext

一个将相关按钮组合在一起并保持一致样式的容器。

Radix UIBase UI
"use client"

import * as React from "react"

安装

pnpm dlx shadcn@latest add button-group

使用

import {
  ButtonGroup,
  ButtonGroupSeparator,
  ButtonGroupText,
} from "@/components/ui/button-group"
<ButtonGroup>
  <Button>按钮 1</Button>
  <Button>按钮 2</Button>
</ButtonGroup>

可访问性

  • ButtonGroup 组件的 role 属性被设置为 group。
  • 使用 Tab 键在按钮组内导航。
  • 使用 aria-label 或 aria-labelledby 为按钮组添加标签。
<ButtonGroup aria-label="按钮组">
  <Button>按钮 1</Button>
  <Button>按钮 2</Button>
</ButtonGroup>

ButtonGroup 与 ToggleGroup

  • 当你希望将执行操作的按钮组合在一起时，使用 ButtonGroup 组件。
  • 当你希望将切换状态的按钮组合在一起时，使用 ToggleGroup 组件。

示例

方向

设置 orientation 属性以更改按钮组布局。

import { Button } from "@/components/ui/button"
import { ButtonGroup } from "@/components/ui/button-group"
import { MinusIcon, PlusIcon } from "lucide-react"

大小

通过单个按钮的 size 属性来控制按钮大小。

import { Button } from "@/components/ui/button"
import { ButtonGroup } from "@/components/ui/button-group"
import { PlusIcon } from "lucide-react"

嵌套

嵌套 <ButtonGroup> 组件以创建带有间距的按钮组。

import { Button } from "@/components/ui/button"
import { ButtonGroup } from "@/components/ui/button-group"
import { Input } from "@/components/ui/input"

分隔符

ButtonGroupSeparator 组件可在按钮组内视觉上分隔按钮。

变体为 outline 的按钮不需要分隔符，因为它们已有边框。其他变体建议使用分隔符以增强视觉层次。

import { Button } from "@/components/ui/button"
import {
  ButtonGroup,

分割按钮

通过在两个按钮之间添加 ButtonGroupSeparator 创建分割按钮组。

import { Button } from "@/components/ui/button"
import {
  ButtonGroup,

输入框

将 Input 组件与按钮组合。

import { Button } from "@/components/ui/button"
import { ButtonGroup } from "@/components/ui/button-group"
import { Input } from "@/components/ui/input"

输入组

将 InputGroup 组件包裹以创建复杂的输入布局。

"use client"

import * as React from "react"

下拉菜单

使用 DropdownMenu 组件创建分割按钮组。

"use client"

import { Button } from "@/components/ui/button"

选择框

与 Select 组件配合使用。

"use client"

import * as React from "react"

弹出框

与 Popover 组件配合使用。

import { Button } from "@/components/ui/button"
import { ButtonGroup } from "@/components/ui/button-group"
import { Field, FieldDescription, FieldLabel } from "@/components/ui/field"

API 参考

ButtonGroup

ButtonGroup 组件是一个容器，将相关按钮以统一样式组合在一起。

属性类型默认值
orientation"horizontal" | "vertical""horizontal"
<ButtonGroup>
  <Button>按钮 1</Button>
  <Button>按钮 2</Button>
</ButtonGroup>

嵌套多个按钮组以创建带间距的复杂布局。详见 嵌套 示例。

<ButtonGroup>
  <ButtonGroup />
  <ButtonGroup />
</ButtonGroup>

ButtonGroupSeparator

ButtonGroupSeparator 组件在按钮组内视觉分隔按钮。

属性类型默认值
orientation"horizontal" | "vertical""vertical"
<ButtonGroup>
  <Button>按钮 1</Button>
  <ButtonGroupSeparator />
  <Button>按钮 2</Button>
</ButtonGroup>

ButtonGroupText

使用此组件在按钮组内显示文本。

属性类型默认值
asChildbooleanfalse
<ButtonGroup>
  <ButtonGroupText>文本</ButtonGroupText>
  <Button>按钮</Button>
</ButtonGroup>

使用 asChild 属性以自定义组件形式渲染文本，例如标签。

import { ButtonGroupText } from "@/components/ui/button-group"
import { Label } from "@/components/ui/label"
 
export function ButtonGroupTextDemo() {
  return (
    <ButtonGroup>
      <ButtonGroupText asChild>
        <Label htmlFor="name">文本</Label>
      </ButtonGroupText>
      <Input placeholder="请输入内容..." id="name" />
    </ButtonGroup>
  )
}