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.
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重复也不会点错。