Translation in progress
This page hasn't been translated into English yet, so the content below is in Chinese. The code examples work the same way.
ButtonGroup 按钮组
把一组相关的按钮放在一起,统一设置尺寸、类型和禁用状态。
引入
import { NsButtonGroup, NsButton } from '@ns/ui'
基础用法
默认横向排列,相邻按钮合并边框,只有两端的按钮带外侧圆角。组内可以放任意变体的按钮,也可以放只有图标的按钮。
<script setup lang="ts">
import { NsButtonGroup, NsButton, NsSpace } from '@ns/ui'
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<NsButtonGroup>
<NsButton>按钮1</NsButton>
<NsButton>按钮2</NsButton>
<NsButton>按钮3</NsButton>
</NsButtonGroup>
<NsButtonGroup>
<NsButton icon="arrow-left">上一页</NsButton>
<NsButton icon="arrow-right" icon-position="right">下一页</NsButton>
</NsButtonGroup>
</NsSpace>
<NsSpace wrap>
<NsButtonGroup>
<NsButton type="primary" variant="outline">描边</NsButton>
<NsButton type="primary" variant="outline">描边</NsButton>
<NsButton type="primary" variant="outline">描边</NsButton>
</NsButtonGroup>
<NsButtonGroup>
<NsButton type="primary" plain>朴素</NsButton>
<NsButton type="primary" plain>朴素</NsButton>
<NsButton type="primary" plain>朴素</NsButton>
</NsButtonGroup>
<NsButtonGroup>
<NsButton icon="edit" aria-label="编辑" />
<NsButton icon="copy" aria-label="复制" />
<NsButton icon="share" aria-label="分享" />
<NsButton icon="trash" aria-label="删除" />
</NsButtonGroup>
</NsSpace>
</NsSpace>
</template>
尺寸
size 可选 large、default、small,统一设置组内按钮的尺寸。
<template>
<NsSpace direction="vertical" align="start">
<NsButtonGroup size="large">
<NsButton>大型(large)</NsButton>
<NsButton>按钮</NsButton>
<NsButton icon="setting" aria-label="设置" />
</NsButtonGroup>
<NsButtonGroup size="default">
<NsButton>默认(default)</NsButton>
<NsButton>按钮</NsButton>
<NsButton icon="setting" aria-label="设置" />
</NsButtonGroup>
<NsButtonGroup size="small">
<NsButton>小型(small)</NsButton>
<NsButton>按钮</NsButton>
<NsButton icon="setting" aria-label="设置" />
</NsButtonGroup>
</NsSpace>
</template>
类型
type 可选 primary、success、warning、danger、info、help,统一设置组内按钮的颜色;不能是 default,想要默认颜色就不传。同类型的实心按钮挨在一起时,中间用浅一档的颜色分隔。
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<NsButtonGroup type="primary">
<NsButton>主要</NsButton>
<NsButton>primary</NsButton>
</NsButtonGroup>
<NsButtonGroup type="success">
<NsButton>成功</NsButton>
<NsButton>success</NsButton>
</NsButtonGroup>
<NsButtonGroup type="warning">
<NsButton>警告</NsButton>
<NsButton>warning</NsButton>
</NsButtonGroup>
</NsSpace>
<NsSpace wrap>
<NsButtonGroup type="danger">
<NsButton>危险</NsButton>
<NsButton>danger</NsButton>
</NsButtonGroup>
<NsButtonGroup type="info">
<NsButton>信息</NsButton>
<NsButton>info</NsButton>
</NsButtonGroup>
<NsButtonGroup type="help">
<NsButton>帮助</NsButton>
<NsButton>help</NsButton>
</NsButtonGroup>
</NsSpace>
</NsSpace>
</template>
统一尺寸、类型和禁用
size、type、disabled 会传给组内的按钮,按钮自己写的优先。改了组的属性,组内按钮跟着变。
<template>
<NsSpace wrap>
<NsButtonGroup size="small" type="primary">
<NsButton>上一页</NsButton>
<NsButton>下一页</NsButton>
<NsButton type="danger">删除</NsButton>
</NsButtonGroup>
<NsButtonGroup disabled>
<NsButton>按钮1</NsButton>
<NsButton :disabled="false">不受组禁用影响</NsButton>
</NsButtonGroup>
</NsSpace>
</template>
切换组的尺寸和禁用,组内按钮跟着变:
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsButtonGroup, NsCheckbox, NsRadio, NsRadioGroup, NsSpace } from '@ns/ui'
import type { ButtonSize } from '@ns/ui'
const size = ref<ButtonSize>('default')
const disabled = ref(false)
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<NsRadioGroup v-model="size" type="button" size="small">
<NsRadio value="large">large</NsRadio>
<NsRadio value="default">default</NsRadio>
<NsRadio value="small">small</NsRadio>
</NsRadioGroup>
<NsCheckbox v-model="disabled">禁用整组</NsCheckbox>
</NsSpace>
<NsButtonGroup :size="size" type="primary" :disabled="disabled">
<NsButton icon="arrow-left">上一页</NsButton>
<NsButton>1</NsButton>
<NsButton>2</NsButton>
<NsButton>3</NsButton>
<NsButton icon="arrow-right" icon-position="right">下一页</NsButton>
</NsButtonGroup>
</NsSpace>
</template>
布局
layout 可选 horizontal(横向,默认)、vertical(竖向)、grid(网格)。竖向排列时只有首尾按钮带圆角;网格排列的按钮不合并边框。
<template>
<NsSpace wrap align="start" size="large">
<NsSpace direction="vertical" align="start">
<span class="row-label">horizontal</span>
<NsButtonGroup layout="horizontal">
<NsButton>按钮1</NsButton>
<NsButton>按钮2</NsButton>
<NsButton>按钮3</NsButton>
</NsButtonGroup>
</NsSpace>
<NsSpace direction="vertical" align="start">
<span class="row-label">vertical</span>
<NsButtonGroup layout="vertical">
<NsButton>按钮1</NsButton>
<NsButton>按钮2</NsButton>
<NsButton>按钮3</NsButton>
</NsButtonGroup>
</NsSpace>
<NsSpace direction="vertical" align="start">
<span class="row-label">grid</span>
<NsButtonGroup layout="grid" gap="small">
<NsButton v-for="i in 6" :key="i">按钮 {{ i }}</NsButton>
</NsButtonGroup>
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row-label {
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
竖向排列
layout="vertical" 竖向排列,只有首尾按钮带圆角。各种类型的按钮、只有图标的按钮都可以竖排。
<template>
<NsSpace wrap align="start">
<NsButtonGroup layout="vertical">
<NsButton>按钮1</NsButton>
<NsButton>按钮2</NsButton>
<NsButton>按钮3</NsButton>
</NsButtonGroup>
<NsButtonGroup layout="vertical" type="primary">
<NsButton icon="arrow-up">上移</NsButton>
<NsButton icon="arrow-down">下移</NsButton>
</NsButtonGroup>
<NsButtonGroup layout="vertical">
<NsButton icon="zoom-in" aria-label="放大" />
<NsButton icon="zoom-out" aria-label="缩小" />
<NsButton icon="fullscreen" aria-label="全屏" />
</NsButtonGroup>
</NsSpace>
</template>
网格
layout="grid" 按网格排列,grid-columns 设置列数(默认 3)。grid-direction 是填充方向:row(默认,按行填充)、column(按列填充,这时 grid-columns 变成行数)。注意看前两组按钮编号的顺序:
<template>
<NsSpace wrap align="start" size="large">
<NsSpace direction="vertical" align="start">
<span class="row-label">row,3 列</span>
<NsButtonGroup layout="grid" :grid-columns="3" gap="small">
<NsButton v-for="i in 6" :key="i">按钮 {{ i }}</NsButton>
</NsButtonGroup>
</NsSpace>
<NsSpace direction="vertical" align="start">
<span class="row-label">column,3 行</span>
<NsButtonGroup layout="grid" :grid-columns="3" grid-direction="column" gap="small">
<NsButton v-for="i in 6" :key="i">按钮 {{ i }}</NsButton>
</NsButtonGroup>
</NsSpace>
<NsSpace direction="vertical" align="start">
<span class="row-label">row,2 列</span>
<NsButtonGroup layout="grid" :grid-columns="2" gap="small" type="primary">
<NsButton v-for="i in 4" :key="i" plain>选项 {{ i }}</NsButton>
</NsButtonGroup>
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row-label {
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
间距
gap 可以是 small、medium、large(4、8、16px),也可以是数字(px)或 CSS 长度。设了间距的按钮不合并边框,各自保留圆角。
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">small</span>
<NsButtonGroup gap="small">
<NsButton>按钮1</NsButton>
<NsButton>按钮2</NsButton>
<NsButton>按钮3</NsButton>
</NsButtonGroup>
</NsSpace>
<NsSpace wrap>
<span class="row-label">medium</span>
<NsButtonGroup gap="medium">
<NsButton>按钮1</NsButton>
<NsButton>按钮2</NsButton>
<NsButton>按钮3</NsButton>
</NsButtonGroup>
</NsSpace>
<NsSpace wrap>
<span class="row-label">large</span>
<NsButtonGroup gap="large">
<NsButton>按钮1</NsButton>
<NsButton>按钮2</NsButton>
<NsButton>按钮3</NsButton>
</NsButtonGroup>
</NsSpace>
<NsSpace wrap>
<span class="row-label">12</span>
<NsButtonGroup :gap="12">
<NsButton>按钮1</NsButton>
<NsButton>按钮2</NsButton>
<NsButton>按钮3</NsButton>
</NsButtonGroup>
</NsSpace>
<NsSpace wrap>
<span class="row-label">2rem</span>
<NsButtonGroup gap="2rem">
<NsButton>按钮1</NsButton>
<NsButton>按钮2</NsButton>
<NsButton>按钮3</NsButton>
</NsButtonGroup>
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row-label {
display: inline-block;
width: 56px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
分割线
divider 在按钮之间加分割线,适合一排文字按钮。分割线长度是按钮高度的一半,随 size 变化:large 20px、default 16px、small 12px。竖向排列时分割线是横线。
<template>
<NsSpace wrap align="start" size="large">
<NsSpace direction="vertical" align="start">
<NsButtonGroup divider size="large">
<NsButton variant="text">编辑</NsButton>
<NsButton variant="text">复制</NsButton>
<NsButton variant="text">删除</NsButton>
</NsButtonGroup>
<NsButtonGroup divider>
<NsButton variant="text">编辑</NsButton>
<NsButton variant="text">复制</NsButton>
<NsButton variant="text">删除</NsButton>
</NsButtonGroup>
<NsButtonGroup divider size="small" type="primary">
<NsButton variant="text">编辑</NsButton>
<NsButton variant="text">复制</NsButton>
<NsButton variant="text" type="danger">删除</NsButton>
</NsButtonGroup>
</NsSpace>
<NsButtonGroup divider layout="vertical">
<NsButton variant="text">编辑</NsButton>
<NsButton variant="text">复制</NsButton>
<NsButton variant="text">删除</NsButton>
</NsButtonGroup>
</NsSpace>
</template>
分割线按实际渲染出来的按钮计算,v-for 渲染的按钮之间也有,v-if 为假的按钮不会多出分割线。取消勾选看看:
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsButtonGroup, NsCheckbox, NsSpace } from '@ns/ui'
const actions = ['查看', '编辑', '复制']
const showDelete = ref(true)
</script>
<template>
<NsSpace wrap>
<NsButtonGroup divider type="primary">
<NsButton v-for="action in actions" :key="action" variant="text">{{ action }}</NsButton>
<NsButton v-if="showDelete" variant="text" type="danger">删除</NsButton>
</NsButtonGroup>
<NsCheckbox v-model="showDelete">显示“删除”</NsCheckbox>
</NsSpace>
</template>
Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| size | 'large' | 'default' | 'small' | — | 组内按钮的尺寸。不写时跟随 ConfigProvider,根元素带 ns-button-group--{size} 类 |
| type | 'primary' | 'success' | 'warning' | 'danger' | 'info' | 'help' | — | 组内按钮的类型,不能是 default |
| disabled | boolean | — | 禁用组内按钮 |
| layout | 'horizontal' | 'vertical' | 'grid' | — | 布局。不传时按 vertical 取 vertical 或 horizontal |
| vertical | boolean | false | 已废弃,用 layout="vertical" 代替;同时设置时以 layout 为准 |
| gap | 'small' | 'medium' | 'large' | string | number | — | 按钮间距 |
| gridColumns | number | 3 | 网格的列数(按列填充时是行数) |
| gridDirection | 'row' | 'column' | 'row' | 网格的填充方向 |
| divider | boolean | false | 按钮之间显示分割线 |
Slots
| 插槽 | 说明 |
|---|---|
| default | 组内的按钮 |
类型
import type { ButtonGroupProps, GapSize, LayoutMode, GridDirection } from '@ns/ui'
注意事项
- 按钮自己写的
size、type、disabled优先于组的设置。 - 组的
type不能是default,想让组内按钮是默认类型就不传。 - 设了
gap、网格或分割线时,按钮不合并边框,各自保留圆角。 - 按钮组是行内元素(
inline-flex),会和前后的行内内容排在同一行。