ActionGroup 操作按钮组
一排操作按钮,最多显示 max 个位置,放不下的收进“更多”下拉菜单。“更多”默认显示文字,用 more-display 可以显示收起的数量,或者换成图标。常用在表格的操作列:每一行传自己的 row,按行数据决定哪些操作显示、哪些禁用。
引入
import { NsActionGroup } from '@ns/ui'
import type { ActionItem } from '@ns/ui'
基础用法
actions 是操作项数组,每项至少有 key 和 label。点了某个操作时触发 action-click,参数是这个操作项和 row。
<script setup lang="ts">
import { NsActionGroup, NsMessage } from '@ns/ui'
import type { ActionItem } from '@ns/ui'
const actions: ActionItem[] = [
{ key: 'view', label: '查看', icon: 'eye' },
{ key: 'edit', label: '编辑', icon: 'edit' },
{ key: 'copy', label: '复制', icon: 'copy' },
{ key: 'delete', label: '删除', icon: 'trash', type: 'danger' }
]
const onAction = (action: ActionItem) => {
NsMessage(`点了${action.label}`)
}
</script>
<template>
<NsActionGroup :actions="actions" @action-click="onAction" />
</template>
最多显示几个
max 默认 3,“更多”也算一个位置:
- 可见的操作不超过
max个时全部直接显示,没有“更多”; - 超过时显示前
max - 1个,其余收进“更多”。所以“更多”里至少有两项,不会出现只收了一个操作的“更多”。
| 可见的操作数 | max | 直接显示 | 收进“更多” |
|---|---|---|---|
| 3 | 3 | 3 个 | - |
| 4 | 3 | 2 个 | 2 个 |
| 5 | 2 | 1 个 | 4 个 |
| 5 | 1 | - | 5 个 |
max 是小数时向下取整;小于 1(0、负数、NaN)时按 1 处理,并在控制台警告;传 Infinity 表示全部直接显示。下面每一行是同样的 5 个操作,行首是 max 的值:
<script setup lang="ts">
import { NsActionGroup, NsSpace } from '@ns/ui'
import type { ActionItem } from '@ns/ui'
const actions: ActionItem[] = [
{ key: 'view', label: '查看' },
{ key: 'edit', label: '编辑' },
{ key: 'copy', label: '复制' },
{ key: 'export', label: '导出' },
{ key: 'delete', label: '删除', type: 'danger' }
]
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace>
<span class="row-label">1</span>
<NsActionGroup :actions="actions" :max="1" />
</NsSpace>
<NsSpace>
<span class="row-label">2</span>
<NsActionGroup :actions="actions" :max="2" />
</NsSpace>
<NsSpace>
<span class="row-label">3(默认)</span>
<NsActionGroup :actions="actions" />
</NsSpace>
<NsSpace>
<span class="row-label">4</span>
<NsActionGroup :actions="actions" :max="4" />
</NsSpace>
<NsSpace>
<span class="row-label">5</span>
<NsActionGroup :actions="actions" :max="5" />
</NsSpace>
<NsSpace>
<span class="row-label">Infinity</span>
<NsActionGroup :actions="actions" :max="Infinity" />
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row-label {
display: inline-block;
width: 72px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
按行数据显示和禁用
visible、disabled 可以是布尔值,也可以是函数,函数的参数是 row。先按 visible 过滤,再按 max 计算哪些收进“更多”,隐藏的操作不占位置。
操作项写成 ActionItem<User>[] 时,回调的 row 就是 User 类型。
<script setup lang="ts">
import { NsActionGroup } from '@ns/ui'
import type { ActionItem } from '@ns/ui'
interface User {
id: number
name: string
status: 'active' | 'locked'
}
defineProps<{ user: User }>()
const actions: ActionItem<User>[] = [
{ key: 'edit', label: '编辑' },
{ key: 'lock', label: '锁定', visible: (row) => row.status === 'active' },
{ key: 'unlock', label: '解锁', visible: (row) => row.status === 'locked' },
{ key: 'delete', label: '删除', type: 'danger', disabled: (row) => row.status === 'locked' }
]
</script>
<template>
<NsActionGroup :actions="actions" :row="user" />
</template>
下面每一行是一个用户,状态不同,显示的操作也不同:正常的用户能“锁定”,锁定的用户能“解锁”、不能“删除”;“导出”对所有人隐藏(visible: false),不占位置。点“锁定”“解锁”会改这一行的状态。
<script setup lang="ts">
import { ref } from 'vue'
import { NsActionGroup, NsSpace, NsTag } from '@ns/ui'
import type { ActionItem } from '@ns/ui'
interface User {
id: number
name: string
status: 'active' | 'locked'
}
const users = ref<User[]>([
{ id: 1, name: '张三', status: 'active' },
{ id: 2, name: '李四', status: 'locked' }
])
const actions: ActionItem<User>[] = [
{ key: 'edit', label: '编辑' },
{
key: 'lock',
label: '锁定',
visible: (row) => row.status === 'active',
onClick: (row) => {
row.status = 'locked'
}
},
{
key: 'unlock',
label: '解锁',
visible: (row) => row.status === 'locked',
onClick: (row) => {
row.status = 'active'
}
},
{ key: 'export', label: '导出', visible: false },
{ key: 'delete', label: '删除', type: 'danger', disabled: (row) => row.status === 'locked' }
]
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace v-for="user in users" :key="user.id">
<span>{{ user.name }}</span>
<NsTag :type="user.status === 'active' ? 'success' : 'warning'" size="small">
{{ user.status === 'active' ? '正常' : '已锁定' }}
</NsTag>
<NsActionGroup :actions="actions" :row="user" />
</NsSpace>
</NsSpace>
</template>
放在表格里
在表格的操作列插槽里使用,传当前行的 row。表格里一般用 size="small",和表格的尺寸一致。
按钮用的是 NsButton 的 variant="link"(链接按钮)并去掉了左右内边距:没有底色和边框,悬停时只是变淡,不会和表格行的悬停底色叠在一起;文字和单元格左边对齐,按钮之间按尺寸隔开 16 / 12 / 8px。
<script setup lang="ts">
import { NsTable, NsActionGroup, NsMessage } from '@ns/ui'
import type { ActionItem, TableColumnConfig } from '@ns/ui'
const columns: TableColumnConfig[] = [
{ prop: 'name', label: '姓名' },
{ prop: 'action', label: '操作', width: 200 }
]
const data = [
{ id: 1, name: '张三' },
{ id: 2, name: '李四' }
]
const actions: ActionItem[] = [
{ key: 'view', label: '查看' },
{ key: 'edit', label: '编辑' },
{ key: 'copy', label: '复制' },
{ key: 'delete', label: '删除', type: 'danger' }
]
const onAction = (action: ActionItem, row: Record<string, unknown>) => {
NsMessage(`第 ${row.id} 行:${action.label}`)
}
</script>
<template>
<NsTable :data="data" :columns="columns" size="small">
<template #action="{ row }">
<NsActionGroup :actions="actions" :row="row" size="small" @action-click="onAction" />
</template>
</NsTable>
</template>
每个操作自己的点击回调
操作项的 onClick(row) 在 action-click 事件之后调用。两种写法可以只用一种,也可以一起用:onClick 适合每个操作各写各的逻辑,action-click 适合统一按 key 分发。
<script setup lang="ts">
import { NsActionGroup } from '@ns/ui'
import type { ActionItem } from '@ns/ui'
interface User {
id: number
name: string
}
defineProps<{ user: User }>()
const openEditor = (row: User) => console.log('编辑', row.id)
const confirmDelete = (row: User) => console.log('删除', row.id)
const actions: ActionItem<User>[] = [
{ key: 'edit', label: '编辑', onClick: (row) => openEditor(row) },
{ key: 'delete', label: '删除', type: 'danger', onClick: (row) => confirmDelete(row) }
]
</script>
<template>
<NsActionGroup :actions="actions" :row="user" />
</template>
两种一起用时的调用顺序,点一下看看:
<script setup lang="ts">
import { ref } from 'vue'
import { NsActionGroup } from '@ns/ui'
import type { ActionItem } from '@ns/ui'
interface User {
id: number
name: string
}
const user: User = { id: 7, name: '王五' }
const logs = ref<string[]>([])
const actions: ActionItem<User>[] = [
{ key: 'edit', label: '编辑', onClick: (row) => logs.value.push(`onClick:编辑 ${row.name}`) },
{
key: 'delete',
label: '删除',
type: 'danger',
onClick: (row) => logs.value.push(`onClick:删除 ${row.name}`)
}
]
const onAction = (action: ActionItem, row: User) => {
logs.value = [`action-click:${action.key},row.id = ${row.id}`]
}
</script>
<template>
<NsActionGroup :actions="actions" :row="user" @action-click="onAction" />
<p style="margin-top: 12px">{{ logs.length ? logs.join(' → ') : '还没有点击' }}</p>
</template>
按钮类型、图标和“更多”的显示
type是按钮类型,默认primary(主色文字),可以用NsButton的所有类型。收进“更多”后,只有danger会把菜单项的文字染成危险色(例如“删除”),其他类型的菜单项和普通菜单项一样。icon是图标名(只能用NsIcon认识的名字,见《图标》),显示在文字前面;收进“更多”后显示在菜单项文字前面。
<script setup lang="ts">
import { NsActionGroup } from '@ns/ui'
import type { ActionItem } from '@ns/ui'
const actions: ActionItem[] = [
{ key: 'view', label: '默认类型', icon: 'eye', type: 'default' },
{ key: 'edit', label: '主要', icon: 'edit' },
{ key: 'pass', label: '成功', icon: 'check', type: 'success' },
{ key: 'warn', label: '警告', icon: 'warning', type: 'warning' },
{ key: 'info', label: '信息', icon: 'info', type: 'info' },
{ key: 'help', label: '帮助', icon: 'help', type: 'help' },
{ key: 'copy', label: '复制', icon: 'copy', type: 'success' },
{ key: 'delete', label: '删除', icon: 'trash', type: 'danger' }
]
</script>
<template>
<NsActionGroup :actions="actions" :max="7" />
</template>
more-display 是“更多”按钮的样式,默认 text:
text:more-text的文字(默认“更多”)加向下箭头,菜单打开时箭头朝上,不显示数量。text-count:文字后面跟收起的操作数(浅色小圆角底),再加向下箭头。count:浅色底的胶囊,写着+N;悬停或菜单打开时加一圈主色边框。icon:只有一个横向省略号图标(more-horizontal),适合放在窄的表格操作列里。
N 是菜单里收起的操作数,隐藏(visible 为 false)的不算。后三种样式的无障碍名称是 more-text 加数量,如“更多 2”。英文界面写 more-text="More"。下面每一行是一种样式:
<script setup lang="ts">
import { NsActionGroup, NsSpace } from '@ns/ui'
import type { ActionItem } from '@ns/ui'
const actions: ActionItem[] = [
{ key: 'view', label: '查看', icon: 'eye' },
{ key: 'edit', label: '编辑', icon: 'edit' },
{ key: 'copy', label: '复制', icon: 'copy' },
{ key: 'delete', label: '删除', icon: 'trash', type: 'danger' }
]
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace>
<span class="row-label">text</span>
<NsActionGroup :actions="actions" more-display="text" />
</NsSpace>
<NsSpace>
<span class="row-label">text-count</span>
<NsActionGroup :actions="actions" more-display="text-count" />
</NsSpace>
<NsSpace>
<span class="row-label">count</span>
<NsActionGroup :actions="actions" more-display="count" />
</NsSpace>
<NsSpace>
<span class="row-label">icon</span>
<NsActionGroup :actions="actions" more-display="icon" />
</NsSpace>
<NsSpace>
<span class="row-label">more-text</span>
<NsActionGroup :actions="actions" more-text="More" />
<NsActionGroup :actions="actions" more-display="text-count" more-text="More" />
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row-label {
display: inline-block;
width: 80px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
触发方式
trigger 是“更多”下拉菜单的触发方式:hover(默认,悬停打开,也可以点击打开)或 click(点击打开、再点收起)。
<script setup lang="ts">
import { NsActionGroup, NsSpace } from '@ns/ui'
import type { ActionItem } from '@ns/ui'
const actions: ActionItem[] = [
{ key: 'view', label: '查看' },
{ key: 'edit', label: '编辑' },
{ key: 'copy', label: '复制' },
{ key: 'delete', label: '删除', type: 'danger' }
]
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace>
<span class="row-label">hover</span>
<NsActionGroup :actions="actions" trigger="hover" more-text="悬停打开" />
</NsSpace>
<NsSpace>
<span class="row-label">click</span>
<NsActionGroup :actions="actions" trigger="click" more-text="点击打开" />
</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>
不同尺寸
size 有 large、default、small 三种,按钮高度 40 / 32 / 24px、字号 16 / 14 / 12px、图标 18 / 16 / 14px、按钮间距 16 / 12 / 8px;“更多”下拉菜单的菜单项也跟着变(行高 40 / 约 36 / 28px,字号 16 / 14 / 12px)。不写时跟随 NsConfigProvider 的 size,都没有时是 default。
<script setup lang="ts">
import { NsActionGroup, NsSpace } from '@ns/ui'
import type { ActionItem } from '@ns/ui'
const actions: ActionItem[] = [
{ key: 'view', label: '查看', icon: 'eye' },
{ key: 'edit', label: '编辑', icon: 'edit' },
{ key: 'copy', label: '复制', icon: 'copy' },
{ key: 'delete', label: '删除', icon: 'trash', type: 'danger' }
]
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace>
<span class="row-label">large</span>
<NsActionGroup :actions="actions" size="large" />
<NsActionGroup :actions="actions" size="large" more-display="count" />
</NsSpace>
<NsSpace>
<span class="row-label">default</span>
<NsActionGroup :actions="actions" />
<NsActionGroup :actions="actions" more-display="count" />
</NsSpace>
<NsSpace>
<span class="row-label">small</span>
<NsActionGroup :actions="actions" size="small" />
<NsActionGroup :actions="actions" size="small" more-display="count" />
</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>
键盘操作
- Tab 逐个聚焦按钮(禁用的按钮跳过);回车、空格触发。
- 在“更多”上按回车、空格或向下键打开菜单,焦点移到第一个可用的菜单项;上下键移动,Home / End 到第一项 / 最后一项,回车、空格选中。
- 按 Esc 或选中一项后菜单收起,焦点回到“更多”按钮。
Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| actions | ActionItem[] | [] | 操作项,见下面的 ActionItem |
| max | number | 3 | 最多占几个位置(含“更多”)。超过时显示前 max - 1 个,其余收进“更多”;小于 1 时按 1 处理 |
| row | any | - | 当前行数据,原样传给 disabled、visible、onClick 和 action-click 事件 |
| moreText | string | '更多' | “更多”按钮的文字。moreDisplay 不是 text 时,这段文字加数量作为无障碍名称(如“更多 2”) |
| moreDisplay | 'text' | 'text-count' | 'count' | 'icon' | 'text' | “更多”按钮的样式:文字加箭头、文字加数量、+N 胶囊、省略号图标。数量不含隐藏的操作 |
| trigger | 'hover' | 'click' | 'hover' | “更多”下拉菜单的触发方式 |
| size | 'large' | 'default' | 'small' | - | 尺寸。不写时跟随 NsConfigProvider 的 size,都没有时是 'default';放在表格里一般用 small |
ActionItem
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| key | string | - | 必填,唯一标识 |
| label | string | - | 必填,按钮文字,也是按钮的可读名称 |
| icon | string | - | 图标名 |
| type | ButtonType | 'primary' | 按钮类型;收进“更多”后只有 danger 会改菜单项的文字颜色 |
| disabled | boolean | ((row) => boolean) | false | 是否禁用。禁用的操作点了不触发事件,也不调用 onClick |
| visible | boolean | ((row) => boolean) | true | 是否显示。先按它过滤,再按 max 计算 |
| onClick | (row) => void | - | 点击时调用,在 action-click 事件之后 |
Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| action-click | (action: ActionItem, row: any) | 点了直接显示的按钮或“更多”里的菜单项时触发;@actionClick 写法也能监听 |
Slots
没有插槽。按钮由 actions 生成;需要完全自定义的按钮时,直接用 NsButton、NsDropdown 组合。
方法
没有对外暴露的方法。
类型
import type {
ActionGroupProps,
ActionGroupEmits,
ActionGroupSize,
ActionGroupMoreDisplay,
ActionGroupTrigger,
ActionItem,
ActionRow
} from '@ns/ui'
type ActionGroupSize = 'large' | 'default' | 'small'
type ActionGroupMoreDisplay = 'text' | 'text-count' | 'count' | 'icon'
type ActionGroupTrigger = 'hover' | 'click'
/** 行数据,组件不读取里面的字段,所以不限制类型 */
type ActionRow = any
interface ActionItem<R = ActionRow> {
key: string
label: string
icon?: NsIconName
type?: ButtonType
disabled?: boolean | ((row: R) => boolean)
visible?: boolean | ((row: R) => boolean)
onClick?: (row: R) => void
}
interface ActionGroupProps {
actions?: ActionItem[]
max?: number
row?: ActionRow
moreText?: string
moreDisplay?: ActionGroupMoreDisplay
trigger?: ActionGroupTrigger
size?: ActionGroupSize
}
interface ActionGroupEmits {
'action-click': [action: ActionItem, row: ActionRow]
}
注意事项
max把“更多”也算一个位置:4 个操作、max为 3 时显示 2 个加“更多”,不是 3 个加“更多”。visible、disabled的函数在渲染时调用,row或actions变了会重新计算;函数里不要做耗时的事。- 收进“更多”的菜单挂在
body上,菜单的层级跟随NsConfigProvider的zIndex,放在对话框、抽屉里也不会被遮住。 - 菜单默认向下、右对齐(
bottom-end)弹出,放在表格最右边的操作列里也不会超出表格;下方放不下时自动翻到上方。 - 不跟随
NsTable的size,放在表格里时要自己写size,一般和表格一致。 key要唯一,重复时 Vue 会警告;菜单项按位置对应操作,key重复也不会点错。