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.
Table 表格
展示多行结构相同的数据。支持排序、多选、固定表头和固定列、树形数据(可懒加载)、展开行、合计行、合并单元格、多级表头、拖动调整列宽和超长省略,单元格内容可以用格式化函数或插槽自定义。
引入
import { NsTable } from '@ns/ui'
基础用法
data 传行数据,columns 传列配置。每一列用 prop 指定取行数据里的哪个字段,label 是表头文字。
<script setup lang="ts">
import { NsTable } from '@ns/ui'
import type { TableColumnConfig } from '@ns/ui'
const columns: TableColumnConfig[] = [
{ prop: 'id', label: 'ID', width: 80 },
{ prop: 'name', label: '姓名', width: 120 },
{ prop: 'age', label: '年龄', width: 80 },
{ prop: 'address', label: '地址' }
]
const data = [
{ id: 1, name: '张三', age: 28, address: '北京市朝阳区' },
{ id: 2, name: '李四', age: 32, address: '上海市浦东新区' },
{ id: 3, name: '王五', age: 25, address: '广州市天河区' }
]
</script>
<template>
<NsTable :data="data" :columns="columns" />
</template>
不传 columns 时,按第一行数据的字段名生成列,表头显示字段名。
<script setup lang="ts">
import { NsTable } from '@ns/ui'
const data = [
{ id: 1, name: '张三', age: 28, address: '北京市朝阳区' },
{ id: 2, name: '李四', age: 32, address: '上海市浦东新区' },
{ id: 3, name: '王五', age: 25, address: '广州市天河区' }
]
</script>
<template>
<NsTable :data="data" />
</template>
斑马纹和边框
stripe 让偶数行带底色,border 给表格和单元格加边框,两个可以同时用。下面依次是 stripe、border、stripe 加 border:
<script setup lang="ts">
import { NsSpace, NsTable } from '@ns/ui'
import type { TableColumnConfig } from '@ns/ui'
const columns: TableColumnConfig[] = [
{ prop: 'id', label: 'ID', width: 80 },
{ prop: 'name', label: '姓名', width: 120 },
{ prop: 'age', label: '年龄', width: 80 },
{ prop: 'address', label: '地址' }
]
const data = [
{ id: 1, name: '张三', age: 28, address: '北京市朝阳区' },
{ id: 2, name: '李四', age: 32, address: '上海市浦东新区' },
{ id: 3, name: '王五', age: 25, address: '广州市天河区' },
{ id: 4, name: '赵六', age: 41, address: '深圳市南山区' }
]
</script>
<template>
<NsSpace direction="vertical" fill>
<div>
<p class="demo-label">stripe</p>
<NsTable :data="data" :columns="columns" stripe />
</div>
<div>
<p class="demo-label">border</p>
<NsTable :data="data" :columns="columns" border />
</div>
<div>
<p class="demo-label">stripe + border</p>
<NsTable :data="data" :columns="columns" stripe border />
</div>
</NsSpace>
</template>
<style scoped>
.demo-label {
margin: 0 0 8px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
尺寸
size 可选 large、default、small。单元格内边距分别是 16、12、8px,字号是 14、14、12px:表格是成片的数据,large 也用 14px 字,三档主要靠内边距区分。多选列的复选框跟着表格的尺寸(方框 18、16、14px)。不写 size 时跟随 ConfigProvider,都没有时是 default。
<script setup lang="ts">
import { NsSpace, NsTable } from '@ns/ui'
import type { TableColumnConfig } from '@ns/ui'
const columns: TableColumnConfig[] = [
{ prop: 'id', label: 'ID', width: 80 },
{ prop: 'name', label: '姓名', width: 120 },
{ prop: 'age', label: '年龄', width: 80 },
{ prop: 'address', label: '地址' }
]
const data = [
{ id: 1, name: '张三', age: 28, address: '北京市朝阳区' },
{ id: 2, name: '李四', age: 32, address: '上海市浦东新区' }
]
</script>
<template>
<NsSpace direction="vertical" fill>
<div>
<p class="demo-label">large</p>
<NsTable :data="data" :columns="columns" size="large" selectable border />
</div>
<div>
<p class="demo-label">default</p>
<NsTable :data="data" :columns="columns" selectable border />
</div>
<div>
<p class="demo-label">small</p>
<NsTable :data="data" :columns="columns" size="small" selectable border />
</div>
</NsSpace>
</template>
<style scoped>
.demo-label {
margin: 0 0 8px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
列宽和对齐
列的 width 传数字时单位是 px,也可以传带单位的字符串(如 '20%')。没设宽度的列平分剩下的空间。align 可选 left(默认)、center、right,同时作用于表头和单元格。下面表头里写了每一列用的值:
<script setup lang="ts">
import { NsTable } from '@ns/ui'
import type { TableColumnConfig } from '@ns/ui'
const columns: TableColumnConfig[] = [
{ prop: 'id', label: 'ID(160px,center)', width: 160, align: 'center' },
{ prop: 'name', label: '姓名(20%,left)', width: '20%' },
{ prop: 'age', label: '年龄(200px,right)', width: 200, align: 'right' },
{ prop: 'address', label: '地址(不设宽度)' }
]
const data = [
{ id: 1, name: '张三', age: 28, address: '北京市朝阳区' },
{ id: 2, name: '李四', age: 32, address: '上海市浦东新区' }
]
</script>
<template>
<NsTable :data="data" :columns="columns" border />
</template>
排序
列上设 sortable: true 后可以点表头排序,顺序是升序、降序、取消排序,每次变化触发 sort-change。数字按大小比较,其他值转成字符串比较,空值(null、undefined)升序时排在最后(下面“入职日期”列赵六的那一行)。
default-sort 指定一开始的排序,order 可选 ascending(升序)、descending(降序)。下面第一个表格一开始按年龄降序,第二个按入职日期升序:
<script setup lang="ts">
import { ref } from 'vue'
import { NsSpace, NsTable } from '@ns/ui'
import type { TableColumnConfig, TableSortState } from '@ns/ui'
const columns: TableColumnConfig[] = [
{ prop: 'id', label: 'ID', width: 80, sortable: true },
{ prop: 'name', label: '姓名', width: 100 },
{ prop: 'age', label: '年龄', width: 100, sortable: true },
{
prop: 'joinDate',
label: '入职日期',
width: 140,
sortable: true,
formatter: (row, column, value) => (value ? String(value) : '—')
},
{ prop: 'address', label: '地址' }
]
const data = [
{ id: 1, name: '张三', age: 28, joinDate: '2021-03-15', address: '北京市朝阳区' },
{ id: 2, name: '李四', age: 32, joinDate: '2018-07-01', address: '上海市浦东新区' },
{ id: 3, name: '王五', age: 25, joinDate: '2023-11-20', address: '广州市天河区' },
{ id: 4, name: '赵六', age: 41, joinDate: null, address: '深圳市南山区' }
]
const sortText = ref('点表头排序试试')
const handleSortChange = (sortState: TableSortState) => {
sortText.value = `sort-change:prop = ${sortState.prop},order = ${sortState.order}`
}
</script>
<template>
<NsSpace direction="vertical" fill>
<NsTable
:data="data"
:columns="columns"
:default-sort="{ prop: 'age', order: 'descending' }"
@sort-change="handleSortChange"
/>
<p>{{ sortText }}</p>
<NsTable
:data="data"
:columns="columns"
:default-sort="{ prop: 'joinDate', order: 'ascending' }"
/>
</NsSpace>
</template>
自己处理排序
sortable: 'custom' 时表格只切换表头的排序状态并触发 sort-change,不改变行的顺序。适合由后端排序:在事件里重新请求数据。下面用定时器模拟请求:
<script setup lang="ts">
import { ref } from 'vue'
import { NsSpace, NsTable } from '@ns/ui'
import type { TableColumnConfig, TableSortState } from '@ns/ui'
const columns: TableColumnConfig[] = [
{ prop: 'name', label: '姓名', width: 140 },
{ prop: 'age', label: '年龄', sortable: 'custom' }
]
const source = [
{ id: 1, name: '张三', age: 28 },
{ id: 2, name: '李四', age: 32 },
{ id: 3, name: '王五', age: 25 }
]
const data = ref(source.slice())
const status = ref('')
// 模拟后端排序:0.5 秒后返回排好的数据
const handleSortChange = ({ prop, order }: TableSortState) => {
status.value = `正在请求:sort=${prop},order=${order ?? '不排序'}……`
window.setTimeout(() => {
if (prop !== 'age' || !order) {
data.value = source.slice()
} else {
const direction = order === 'ascending' ? 1 : -1
data.value = source.slice().sort((a, b) => (a.age - b.age) * direction)
}
status.value = '已按返回的顺序显示'
}, 500)
}
</script>
<template>
<NsSpace direction="vertical" fill>
<NsTable :data="data" :columns="columns" @sort-change="handleSortChange" />
<p>{{ status || '点“年龄”表头试试' }}</p>
</NsSpace>
</template>
多选
selectable 在最左边加一列复选框。表头的复选框用来全选,只选了一部分时显示成半选,选中的行带浅色底。选中的行通过 selection-change 拿到,也可以通过 ref 调用方法来改:
toggleRowSelection(row, selected?):切换一行,传了selected时直接设成选中或不选中。toggleAllSelection():已经全选时取消全选,否则全选。clearSelection():清空。
点复选框时还会触发 select(某一行变化)或 select-all(点表头的全选框)。点行默认不勾选,下面在 row-click 里调用了 toggleRowSelection,点行也能勾选。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsSpace, NsTable } from '@ns/ui'
import type { TableColumnConfig } from '@ns/ui'
const columns: TableColumnConfig[] = [
{ prop: 'id', label: 'ID', width: 80 },
{ prop: 'name', label: '姓名', width: 120 },
{ prop: 'address', label: '地址' }
]
const data = [
{ id: 1, name: '张三', address: '北京市朝阳区' },
{ id: 2, name: '李四', address: '上海市浦东新区' },
{ id: 3, name: '王五', address: '广州市天河区' }
]
const tableRef = ref<InstanceType<typeof NsTable>>()
const selectedNames = ref<string[]>([])
const lastEvent = ref('')
const handleSelectionChange = (selection: Record<string, unknown>[]) => {
selectedNames.value = selection.map((row) => String(row.name))
}
const handleSelect = (selection: Record<string, unknown>[], row: Record<string, unknown>) => {
lastEvent.value = `select:${row.name},现在选了 ${selection.length} 行`
}
const handleSelectAll = (selection: Record<string, unknown>[]) => {
lastEvent.value = `select-all:现在选了 ${selection.length} 行`
}
</script>
<template>
<NsSpace direction="vertical" fill>
<NsSpace wrap>
<NsButton size="small" @click="tableRef?.toggleRowSelection(data[0], true)">
选中第一行
</NsButton>
<NsButton size="small" @click="tableRef?.toggleRowSelection(data[1])">切换第二行</NsButton>
<NsButton size="small" @click="tableRef?.toggleAllSelection()">全选 / 取消全选</NsButton>
<NsButton size="small" @click="tableRef?.clearSelection()">清空</NsButton>
</NsSpace>
<NsTable
ref="tableRef"
:data="data"
:columns="columns"
selectable
@selection-change="handleSelectionChange"
@select="handleSelect"
@select-all="handleSelectAll"
@row-click="(row) => tableRef?.toggleRowSelection(row)"
/>
<p>已选:{{ selectedNames.join('、') || '无' }}</p>
<p v-if="lastEvent">{{ lastEvent }}</p>
</NsSpace>
</template>
行的唯一标识
表格用 row-key 区分每一行,默认取行数据的 id 字段。唯一字段不叫 id 时传字段名(上面的表格),或者传一个返回字符串的函数(下面的表格)。
<script setup lang="ts">
import { NsSpace, NsTable } from '@ns/ui'
const data = [
{ code: 'A001', name: '螺丝', stock: 1200 },
{ code: 'A002', name: '螺母', stock: 860 },
{ code: 'A003', name: '垫片', stock: 430 }
]
const getRowKey = (row: Record<string, unknown>) => `row-${row.code}`
</script>
<template>
<NsSpace direction="vertical" fill>
<NsTable :data="data" row-key="code" selectable />
<NsTable :data="data" :row-key="getRowKey" selectable />
</NsSpace>
</template>
固定表头
设了 height 或 max-height 后,内容超出时表体滚动,表头一直停在上面。height 是固定高度;max-height 在行数少时按内容高度显示。数字的单位是 px,也可以传 '50vh' 这样的字符串。
<script setup lang="ts">
import { NsSpace, NsTable } from '@ns/ui'
import type { TableColumnConfig } from '@ns/ui'
const columns: TableColumnConfig[] = [
{ prop: 'id', label: 'ID', width: 80 },
{ prop: 'name', label: '姓名', width: 120 },
{ prop: 'address', label: '地址' }
]
const surnames = ['张', '王', '李', '赵', '刘']
const givenNames = ['伟', '芳', '娜', '敏']
const districts = ['朝阳区', '海淀区', '东城区', '西城区', '丰台区']
const data = Array.from({ length: 20 }, (_, index) => ({
id: index + 1,
name: `${surnames[index % 5]}${givenNames[index % 4]}`,
address: `北京市${districts[index % 5]}`
}))
const fewRows = data.slice(0, 3)
</script>
<template>
<NsSpace direction="vertical" fill>
<div>
<p class="demo-label">:height="300"(20 行)</p>
<NsTable :data="data" :columns="columns" :height="300" border />
</div>
<div>
<p class="demo-label">:max-height="260"(20 行,超出后滚动)</p>
<NsTable :data="data" :columns="columns" :max-height="260" border />
</div>
<div>
<p class="demo-label">:max-height="260"(3 行,按内容高度)</p>
<NsTable :data="fewRows" :columns="columns" :max-height="260" border />
</div>
</NsSpace>
</template>
<style scoped>
.demo-label {
margin: 0 0 8px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
固定列
列上设 fixed: 'left' 或 fixed: 'right',横向滚动时这一列停在左边或右边。要让表格出现横向滚动,每一列都要设 width,并且宽度加起来超过表格的宽度。有左固定列并且开了 selectable 时,复选框列也跟着固定。有内容滚到固定列下面时,固定列靠里的一侧会显示一道阴影。
<script setup lang="ts">
import { NsButton, NsTable } from '@ns/ui'
import type { TableColumnConfig } from '@ns/ui'
const columns: TableColumnConfig[] = [
{ prop: 'name', label: '姓名', width: 120, fixed: 'left' },
{ prop: 'age', label: '年龄', width: 200 },
{ prop: 'phone', label: '电话', width: 300 },
{ prop: 'email', label: '邮箱', width: 300 },
{ prop: 'address', label: '地址', width: 400 },
{ prop: 'action', label: '操作', width: 120, fixed: 'right' }
]
const data = [
{
id: 1,
name: '张三',
age: 28,
phone: '13800000001',
email: 'zhangsan@example.com',
address: '北京市朝阳区'
},
{
id: 2,
name: '李四',
age: 32,
phone: '13800000002',
email: 'lisi@example.com',
address: '上海市浦东新区'
},
{
id: 3,
name: '王五',
age: 25,
phone: '13800000003',
email: 'wangwu@example.com',
address: '广州市天河区'
}
]
</script>
<template>
<div style="max-width: 800px">
<NsTable :data="data" :columns="columns" selectable border>
<template #action>
<NsButton size="small" type="primary" variant="link">编辑</NsButton>
</template>
</NsTable>
</div>
</template>
格式化单元格
列的 formatter 接收行数据、列配置和单元格的值,返回要显示的字符串。
<script setup lang="ts">
import { NsTable } from '@ns/ui'
import type { TableColumnConfig } from '@ns/ui'
const statusText: Record<string, string> = { active: '在职', leave: '休假', quit: '离职' }
const columns: TableColumnConfig[] = [
{ prop: 'name', label: '姓名', width: 120 },
{ prop: 'age', label: '年龄', width: 100, formatter: (row, column, value) => `${value} 岁` },
{
prop: 'status',
label: '状态',
width: 100,
formatter: (row, column, value) => statusText[String(value)] ?? '未知'
},
{
prop: 'salary',
label: '月薪',
align: 'right',
formatter: (row) => `¥ ${Number(row.salary).toLocaleString()}`
}
]
const data = [
{ id: 1, name: '张三', age: 28, status: 'active', salary: 12000 },
{ id: 2, name: '李四', age: 32, status: 'leave', salary: 18500 },
{ id: 3, name: '王五', age: 25, status: 'quit', salary: 9800 }
]
</script>
<template>
<NsTable :data="data" :columns="columns" />
</template>
自定义单元格
要在单元格里放标签、按钮等内容时,用和列的 prop 同名的插槽,参数是 row、column、rowIndex。写了插槽的列不再用 formatter。操作列这类不对应字段的列,prop 随便起一个不重复的名字即可。单元格里的按钮不想触发 row-click 时,点击事件加 .stop。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsMessage, NsSpace, NsTable, NsTag } from '@ns/ui'
import type { TableColumnConfig } from '@ns/ui'
const columns: TableColumnConfig[] = [
{ prop: 'name', label: '姓名', width: 140 },
{ prop: 'status', label: '状态', width: 120 },
{ prop: 'address', label: '地址' },
{ prop: 'action', label: '操作', width: 140 }
]
const source = [
{ id: 1, name: '张三', status: 'active', address: '北京市朝阳区' },
{ id: 2, name: '李四', status: 'disabled', address: '上海市浦东新区' },
{ id: 3, name: '王五', status: 'active', address: '广州市天河区' }
]
const data = ref(source.slice())
const remove = (row: Record<string, unknown>) => {
data.value = data.value.filter((item) => item.id !== row.id)
}
</script>
<template>
<NsSpace direction="vertical" fill>
<NsTable :data="data" :columns="columns">
<template #name="{ row, rowIndex }">
<strong>{{ rowIndex + 1 }}. {{ row.name }}</strong>
</template>
<template #status="{ row }">
<NsTag :type="row.status === 'active' ? 'success' : 'danger'" size="small">
{{ row.status === 'active' ? '启用' : '停用' }}
</NsTag>
</template>
<template #action="{ row }">
<NsSpace :size="4">
<NsButton
size="small"
type="primary"
variant="link"
@click.stop="NsMessage.info(`查看${row.name}`)"
>
查看
</NsButton>
<NsButton size="small" type="danger" variant="link" @click.stop="remove(row)">
删除
</NsButton>
</NsSpace>
</template>
</NsTable>
<NsSpace wrap>
<NsButton
size="small"
:disabled="data.length === source.length"
@click="data = source.slice()"
>
恢复删除的行
</NsButton>
</NsSpace>
</NsSpace>
</template>
空数据
data 是空数组时显示 empty-text,默认是“暂无数据”。要放图片或按钮时用 empty 插槽,例如放一个 NsEmpty。
<script setup lang="ts">
import { NsButton, NsEmpty, NsSpace, NsTable } from '@ns/ui'
import type { TableColumnConfig } from '@ns/ui'
const columns: TableColumnConfig[] = [
{ prop: 'id', label: 'ID', width: 80 },
{ prop: 'name', label: '姓名', width: 120 },
{ prop: 'age', label: '年龄', width: 80 },
{ prop: 'address', label: '地址' }
]
</script>
<template>
<NsSpace direction="vertical" fill>
<NsTable :data="[]" :columns="columns" />
<NsTable :data="[]" :columns="columns" empty-text="没有符合条件的记录" />
<NsTable :data="[]" :columns="columns">
<template #empty>
<NsEmpty description="还没有员工,先去新建一个">
<NsButton type="primary" icon="plus">新建员工</NsButton>
</NsEmpty>
</template>
</NsTable>
</NsSpace>
</template>
隐藏表头
show-header 设为 false 后不渲染表头。
<script setup lang="ts">
import { NsTable } from '@ns/ui'
import type { TableColumnConfig } from '@ns/ui'
const columns: TableColumnConfig[] = [
{ prop: 'id', label: 'ID', width: 80 },
{ prop: 'name', label: '姓名', width: 120 },
{ prop: 'age', label: '年龄', width: 80 },
{ prop: 'address', label: '地址' }
]
const data = [
{ id: 1, name: '张三', age: 28, address: '北京市朝阳区' },
{ id: 2, name: '李四', age: 32, address: '上海市浦东新区' },
{ id: 3, name: '王五', age: 25, address: '广州市天河区' }
]
</script>
<template>
<NsTable :data="data" :columns="columns" :show-header="false" border />
</template>
自定义类名
row-class-name、cell-class-name、header-cell-class-name 可以传字符串,也可以传函数按行、按列返回类名。列配置里的 className 会同时加到这一列的表头和单元格上。组件的样式带 scoped,自己的类要写在全局样式里,或者在 scoped 样式里用 :deep()。
下面 60 岁及以上的行标红(row-class-name),年龄不到 30 的单元格标绿(cell-class-name),可排序列的表头用主色(header-cell-class-name),“年龄”列整列加粗(className):
<script setup lang="ts">
import { NsTable } from '@ns/ui'
import type { TableColumnConfig } from '@ns/ui'
const columns: TableColumnConfig[] = [
{ prop: 'name', label: '姓名', width: 140 },
{ prop: 'age', label: '年龄', width: 120, sortable: true, className: 'col-age' },
{ prop: 'address', label: '地址' }
]
const data = [
{ id: 1, name: '张三', age: 28, address: '北京市朝阳区' },
{ id: 2, name: '李四', age: 62, address: '上海市浦东新区' },
{ id: 3, name: '王五', age: 45, address: '广州市天河区' }
]
const rowClassName = (row: Record<string, unknown>) =>
Number(row.age) >= 60 ? 'row-warning' : ''
const cellClassName = (row: Record<string, unknown>, column: TableColumnConfig) =>
column.prop === 'age' && Number(row.age) < 30 ? 'cell-young' : ''
const headerCellClassName = (column: TableColumnConfig) =>
column.sortable ? 'header-sortable' : ''
</script>
<template>
<NsTable
:data="data"
:columns="columns"
:row-class-name="rowClassName"
:cell-class-name="cellClassName"
:header-cell-class-name="headerCellClassName"
/>
</template>
<style scoped>
:deep(.row-warning) {
color: var(--ns-color-danger);
}
:deep(.cell-young) {
color: var(--ns-color-success);
}
:deep(th.header-sortable) {
color: var(--ns-color-primary);
}
:deep(.col-age) {
font-weight: 600;
}
</style>
点击事件
点单元格时先触发 cell-click,再触发 row-click。点复选框那一列不触发这两个事件。
<script setup lang="ts">
import { ref } from 'vue'
import { NsSpace, NsTable } from '@ns/ui'
import type { TableColumnConfig } from '@ns/ui'
const columns: TableColumnConfig[] = [
{ prop: 'name', label: '姓名', width: 140 },
{ prop: 'address', label: '地址' }
]
const data = [
{ id: 1, name: '张三', address: '北京市朝阳区' },
{ id: 2, name: '李四', address: '上海市浦东新区' }
]
const cellText = ref('')
const rowText = ref('')
const handleCellClick = (
row: Record<string, unknown>,
column: TableColumnConfig,
cell: HTMLTableCellElement
) => {
cellText.value = `cell-click:${column.label}列,单元格内容“${cell.textContent?.trim()}”`
}
const handleRowClick = (row: Record<string, unknown>, column: TableColumnConfig | undefined) => {
rowText.value = `row-click:${row.name}这一行,点在“${column?.label}”列`
}
</script>
<template>
<NsSpace direction="vertical" fill>
<NsTable
:data="data"
:columns="columns"
selectable
@row-click="handleRowClick"
@cell-click="handleCellClick"
/>
<p>{{ cellText || '点单元格试试(点复选框不触发)' }}</p>
<p v-if="rowText">{{ rowText }}</p>
</NsSpace>
</template>
树形数据
行数据里有 children 数组时按树形显示:第一列带缩进和展开按钮,点按钮展开或收起子行,每次变化触发 expand-change。树形数据要求每一行(包括子行)都有唯一的 row-key。
default-expand-all 一开始展开所有层级。也可以通过 ref 调用 expandAll()、collapseAll() 一次展开或收起全部,toggleRowExpansion(row, expanded?) 切换某一行。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsSpace, NsTable } from '@ns/ui'
import type { TableColumnConfig } from '@ns/ui'
const columns: TableColumnConfig[] = [
{ prop: 'name', label: '部门', width: 220 },
{ prop: 'leader', label: '负责人', width: 120 },
{ prop: 'count', label: '人数', width: 100, align: 'right', sortable: true },
{ prop: 'phone', label: '电话' }
]
const data = [
{
id: 1,
name: '总经办',
leader: '张伟',
count: 6,
phone: '010-80001000',
children: [
{
id: 11,
name: '行政部',
leader: '王芳',
count: 12,
phone: '010-80001100',
children: [
{ id: 111, name: '前台', leader: '李娜', count: 3, phone: '010-80001101' },
{ id: 112, name: '后勤组', leader: '赵敏', count: 5, phone: '010-80001102' }
]
},
{ id: 12, name: '财务部', leader: '刘静', count: 8, phone: '010-80001200' }
]
},
{
id: 2,
name: '研发中心',
leader: '陈强',
count: 46,
phone: '010-80002000',
children: [
{ id: 21, name: '前端组', leader: '杨洋', count: 15, phone: '010-80002100' },
{ id: 22, name: '后端组', leader: '黄磊', count: 21, phone: '010-80002200' }
]
},
{ id: 3, name: '市场部', leader: '周杰', count: 18, phone: '010-80003000' }
]
const tableRef = ref<InstanceType<typeof NsTable>>()
const lastEvent = ref('')
const handleExpandChange = (
row: Record<string, unknown>,
expanded: boolean,
expandedRows: Record<string, unknown>[]
) => {
lastEvent.value = `expand-change:${expanded ? '展开' : '收起'}了“${row.name}”,现在展开着 ${expandedRows.length} 行`
}
</script>
<template>
<NsSpace direction="vertical" fill>
<NsSpace wrap>
<NsButton size="small" @click="tableRef?.expandAll()">展开全部</NsButton>
<NsButton size="small" @click="tableRef?.collapseAll()">收起全部</NsButton>
<NsButton size="small" @click="tableRef?.toggleRowExpansion(data[1])"
>切换“研发中心”</NsButton
>
</NsSpace>
<NsTable
ref="tableRef"
:data="data"
:columns="columns"
default-expand-all
border
@expand-change="handleExpandChange"
/>
<p>{{ lastEvent || '点部门名称前面的箭头试试' }}</p>
</NsSpace>
</template>
子行数组的字段不叫 children 时,用 tree-props 指定字段名。default-expanded-keys 传一组 row-key,一开始只展开这些行;indent 是每一级缩进的宽度,默认 16px。下面子行放在 cities 字段里,一开始只展开“华东区”,每级缩进 32px:
<script setup lang="ts">
import { NsTable } from '@ns/ui'
import type { TableColumnConfig } from '@ns/ui'
const columns: TableColumnConfig[] = [
{ prop: 'name', label: '地区', width: 220 },
{ prop: 'stores', label: '门店数', width: 100, align: 'right' },
{ prop: 'manager', label: '区域经理' }
]
const data = [
{
code: 'EC',
name: '华东区',
stores: 128,
manager: '王芳',
cities: [
{ code: 'SH', name: '上海', stores: 56, manager: '李娜' },
{ code: 'HZ', name: '杭州', stores: 41, manager: '赵敏' },
{ code: 'NJ', name: '南京', stores: 31, manager: '孙磊' }
]
},
{
code: 'SC',
name: '华南区',
stores: 97,
manager: '陈强',
cities: [
{ code: 'GZ', name: '广州', stores: 52, manager: '杨洋' },
{ code: 'SZ', name: '深圳', stores: 45, manager: '黄磊' }
]
}
]
</script>
<template>
<NsTable
:data="data"
:columns="columns"
row-key="code"
:tree-props="{ children: 'cities' }"
:default-expanded-keys="['EC']"
:indent="32"
/>
</template>
懒加载子行
子行要展开时才去请求的,在行上标记 hasChildren: true(字段名可以用 tree-props 改),再传 load 函数。第一次展开时表格调用 load(row, resolve),加载期间箭头换成加载图标;取到子行后调用 resolve(children),也可以让 load 直接返回 Promise。加载过的行再收起、展开不会重新请求;返回空数组时这一行不再显示箭头;Promise 被拒绝时结束加载、保持收起,再点一次会重新请求。
下面用定时器模拟请求,“西北区”没有下级城市:
<script setup lang="ts">
import { NsTable } from '@ns/ui'
import type { TableColumnConfig } from '@ns/ui'
const columns: TableColumnConfig[] = [
{ prop: 'name', label: '地区', width: 220 },
{ prop: 'code', label: '编码', width: 120 },
{ prop: 'manager', label: '负责人' }
]
const data = [
{ code: 'EC', name: '华东区', manager: '王芳', hasChildren: true },
{ code: 'SC', name: '华南区', manager: '陈强', hasChildren: true },
{ code: 'NW', name: '西北区', manager: '周杰', hasChildren: true }
]
const cities: Record<string, Record<string, unknown>[]> = {
EC: [
{ code: 'SH', name: '上海', manager: '李娜', hasChildren: true },
{ code: 'HZ', name: '杭州', manager: '赵敏' }
],
SH: [
{ code: 'SH-PD', name: '浦东新区', manager: '孙磊' },
{ code: 'SH-XH', name: '徐汇区', manager: '刘静' }
],
SC: [
{ code: 'GZ', name: '广州', manager: '杨洋' },
{ code: 'SZ', name: '深圳', manager: '黄磊' }
]
}
// 模拟接口:0.8 秒后返回下级地区
const load = (row: Record<string, unknown>) =>
new Promise<Record<string, unknown>[]>((resolve) => {
window.setTimeout(() => resolve(cities[String(row.code)] ?? []), 800)
})
</script>
<template>
<NsTable :data="data" :columns="columns" row-key="code" :load="load" />
</template>
展开行
expandable 在左边加一列展开按钮,点开后在这一行下面显示 expand 插槽的内容,插槽参数是 row 和 rowIndex。展开、收起时触发 expand-change,参数是这一行、是否展开和展开着的全部行。通过 ref 调用 toggleRowExpansion(row, expanded?) 切换某一行,expandAll()、collapseAll() 展开或收起全部。点展开列不触发 row-click。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsSpace, NsTable } from '@ns/ui'
import type { TableColumnConfig } from '@ns/ui'
const columns: TableColumnConfig[] = [
{ prop: 'orderNo', label: '订单号', width: 180 },
{ prop: 'customer', label: '客户', width: 120 },
{ prop: 'amount', label: '金额(元)', width: 120, align: 'right' },
{ prop: 'createdAt', label: '下单时间' }
]
const data = [
{
id: 1,
orderNo: 'DD202611150001',
customer: '张伟',
amount: 2580,
createdAt: '2026-11-15 09:12',
receiver: '张伟',
phone: '13800001111',
address: '北京市朝阳区建国路 88 号',
goods: '办公椅 × 2、升降桌 × 1'
},
{
id: 2,
orderNo: 'DD202611150002',
customer: '王芳',
amount: 399,
createdAt: '2026-11-15 10:40',
receiver: '王芳',
phone: '13900002222',
address: '上海市浦东新区世纪大道 100 号',
goods: '台灯 × 1'
},
{
id: 3,
orderNo: 'DD202611160003',
customer: '李娜',
amount: 1260,
createdAt: '2026-11-16 14:05',
receiver: '刘静',
phone: '13700003333',
address: '广州市天河区天河路 385 号',
goods: '文件柜 × 3'
}
]
const tableRef = ref<InstanceType<typeof NsTable>>()
const lastEvent = ref('')
const handleExpandChange = (
row: Record<string, unknown>,
expanded: boolean,
expandedRows: Record<string, unknown>[]
) => {
lastEvent.value = `expand-change:${expanded ? '展开' : '收起'}了 ${row.orderNo},现在展开着 ${expandedRows.length} 行`
}
</script>
<template>
<NsSpace direction="vertical" fill>
<NsSpace wrap>
<NsButton size="small" @click="tableRef?.toggleRowExpansion(data[0])">切换第一行</NsButton>
<NsButton size="small" @click="tableRef?.expandAll()">展开全部</NsButton>
<NsButton size="small" @click="tableRef?.collapseAll()">收起全部</NsButton>
</NsSpace>
<NsTable
ref="tableRef"
:data="data"
:columns="columns"
expandable
@expand-change="handleExpandChange"
>
<template #expand="{ row }">
<dl class="order-detail">
<dt>收货人</dt>
<dd>{{ row.receiver }}({{ row.phone }})</dd>
<dt>收货地址</dt>
<dd>{{ row.address }}</dd>
<dt>商品</dt>
<dd>{{ row.goods }}</dd>
</dl>
</template>
</NsTable>
<p>{{ lastEvent || '点左边的箭头展开订单详情' }}</p>
</NsSpace>
</template>
<style scoped>
.order-detail {
display: grid;
grid-template-columns: 80px 1fr;
gap: 8px;
margin: 0;
}
.order-detail dt {
color: var(--ns-text-color-secondary);
}
.order-detail dd {
margin: 0;
}
</style>
手风琴和默认展开
accordion 让展开行同时只展开一行,展开另一行时前一行自动收起。default-expanded-keys 传一组 row-key,一开始展开这些行;default-expand-all 一开始展开全部。下面一开始展开第二行:
<script setup lang="ts">
import { NsTable } from '@ns/ui'
import type { TableColumnConfig } from '@ns/ui'
const columns: TableColumnConfig[] = [
{ prop: 'name', label: '姓名', width: 120 },
{ prop: 'dept', label: '部门', width: 140 },
{ prop: 'position', label: '职位' }
]
const data = [
{
id: 1,
name: '张伟',
dept: '研发中心',
position: '前端工程师',
intro: '负责管理后台的页面开发。'
},
{ id: 2, name: '王芳', dept: '财务部', position: '会计', intro: '负责应收应付和月度结账。' },
{
id: 3,
name: '李娜',
dept: '市场部',
position: '市场专员',
intro: '负责线上活动的策划和执行。'
}
]
</script>
<template>
<NsTable :data="data" :columns="columns" expandable accordion :default-expanded-keys="[2]">
<template #expand="{ row }">
<p class="intro">{{ row.name }}:{{ row.intro }}</p>
</template>
</NsTable>
</template>
<style scoped>
.intro {
margin: 0;
color: var(--ns-text-color-secondary);
}
</style>
合计行
show-summary 在表尾加一行合计:第一列显示 summary-text(默认“合计”),其余列把数字类型的值加起来,没有数字的列留空。只合计第一层的行,树形数据的子行不算在里面。设了 height 或 max-height 时合计行和表头一样固定在可视区域里。
<script setup lang="ts">
import { NsTable } from '@ns/ui'
import type { TableColumnConfig } from '@ns/ui'
const columns: TableColumnConfig[] = [
{ prop: 'store', label: '门店', width: 140 },
{ prop: 'city', label: '城市', width: 100 },
{ prop: 'orders', label: '订单数', align: 'right' },
{ prop: 'amount', label: '销售额(元)', align: 'right' }
]
const data = [
{ id: 1, store: '朝阳大悦城店', city: '北京', orders: 1286, amount: 358620.5 },
{ id: 2, store: '陆家嘴店', city: '上海', orders: 1032, amount: 296410.25 },
{ id: 3, store: '天河城店', city: '广州', orders: 874, amount: 213980 },
{ id: 4, store: '万象天地店', city: '深圳', orders: 951, amount: 247300.75 }
]
</script>
<template>
<NsTable :data="data" :columns="columns" show-summary border />
</template>
summary-method 自定义每一列的内容:参数是 { columns, data }(数据列和第一层的行数据),返回和 columns 一一对应的数组,null、undefined 显示成空。下面合计行的文字改成“本月合计”,销售额加上千分位,城市列显示门店数:
<script setup lang="ts">
import { NsTable } from '@ns/ui'
import type { TableColumnConfig, TableSummaryMethodParams } from '@ns/ui'
const columns: TableColumnConfig[] = [
{ prop: 'store', label: '门店', width: 140 },
{ prop: 'city', label: '城市', width: 120 },
{ prop: 'orders', label: '订单数', align: 'right' },
{
prop: 'amount',
label: '销售额(元)',
align: 'right',
formatter: (row, column, value) => Number(value).toLocaleString()
}
]
const data = [
{ id: 1, store: '朝阳大悦城店', city: '北京', orders: 1286, amount: 358620.5 },
{ id: 2, store: '陆家嘴店', city: '上海', orders: 1032, amount: 296410.25 },
{ id: 3, store: '天河城店', city: '广州', orders: 874, amount: 213980 }
]
const summaryMethod = ({ columns, data }: TableSummaryMethodParams) =>
columns.map((column, index) => {
if (index === 0) return '本月合计'
if (column.prop === 'city') return `${data.length} 家门店`
const total = data.reduce((sum, row) => sum + Number(row[column.prop]), 0)
return column.prop === 'amount' ? `¥ ${total.toLocaleString()}` : total
})
</script>
<template>
<NsTable :data="data" :columns="columns" show-summary :summary-method="summaryMethod" />
</template>
合并单元格
span-method 按行、列决定每个单元格占几行几列。参数是 { row, column, rowIndex, columnIndex }:rowIndex 是排序、展开后看得见的行里的序号,columnIndex 是数据列的序号(不算复选框列、展开列),都从 0 开始。返回 [rowspan, colspan] 或 { rowspan, colspan },不返回时是 1 行 1 列;被合并掉的单元格要返回 [0, 0],这样的单元格不渲染。
下面把同一天的“日期”合并成一格(按数据算出每一天从哪一行开始、有几行);11 月 20 日休息,这一行从“班次”到“联系电话”合并成一格:
<script setup lang="ts">
import { NsTable } from '@ns/ui'
import type { TableColumnConfig, TableSpanMethodParams } from '@ns/ui'
const columns: TableColumnConfig[] = [
{ prop: 'date', label: '日期', width: 140, align: 'center' },
{ prop: 'shift', label: '班次', width: 120 },
{ prop: 'staff', label: '值班人', width: 120 },
{ prop: 'phone', label: '联系电话' }
]
const data = [
{ id: 1, date: '11 月 18 日', shift: '早班', staff: '张伟', phone: '13800001111' },
{ id: 2, date: '11 月 18 日', shift: '中班', staff: '王芳', phone: '13900002222' },
{ id: 3, date: '11 月 18 日', shift: '晚班', staff: '李娜', phone: '13700003333' },
{ id: 4, date: '11 月 19 日', shift: '早班', staff: '赵敏', phone: '13600004444' },
{ id: 5, date: '11 月 19 日', shift: '晚班', staff: '刘静', phone: '13500005555' },
{ id: 6, date: '11 月 20 日', shift: '休息日,不排班', staff: '', phone: '' }
]
// 每一行的“日期”占几行:同一天的第一行占这一天的行数,后面几行是 0(被合并掉)
const dateRowspans = data.map((row, index) => {
if (index > 0 && data[index - 1].date === row.date) return 0
let count = 1
while (data[index + count]?.date === row.date) count++
return count
})
const spanMethod = ({ row, rowIndex, columnIndex }: TableSpanMethodParams) => {
if (columnIndex === 0) {
const rowspan = dateRowspans[rowIndex]
return [rowspan, rowspan > 0 ? 1 : 0] as [number, number]
}
// 休息日:“班次”占 3 列,后面两列被合并掉
if (row.staff === '') {
return columnIndex === 1 ? { rowspan: 1, colspan: 3 } : { rowspan: 0, colspan: 0 }
}
}
</script>
<template>
<NsTable :data="data" :columns="columns" :span-method="spanMethod" border />
</template>
多级表头
列配置里写 children 就成了分组列,表头按层级自动算出每个单元格横跨几行几列。分组列只是表头上的一格,不对应数据:它的 prop 只用来区分列,起一个不重复的名字即可;表体、插槽、formatter、排序都按最下面一层的列(叶子列)来。分组单元格没写 align 时居中。
分组列设 fixed 时,它下面的列都跟着固定。下面“姓名”所在的分组固定在左边,“操作”固定在右边,“年龄”可以排序:
<script setup lang="ts">
import { NsButton, NsTable } from '@ns/ui'
import type { TableColumnConfig } from '@ns/ui'
const columns: TableColumnConfig[] = [
{
prop: 'person',
label: '员工',
fixed: 'left',
children: [
{ prop: 'name', label: '姓名', width: 100 },
{ prop: 'age', label: '年龄', width: 90, align: 'right', sortable: true }
]
},
{
prop: 'job',
label: '岗位信息',
children: [
{ prop: 'dept', label: '部门', width: 140 },
{ prop: 'position', label: '职位', width: 140 }
]
},
{
prop: 'contact',
label: '联系方式',
children: [
{ prop: 'phone', label: '电话', width: 160 },
{
prop: 'address',
label: '地址',
children: [
{ prop: 'city', label: '城市', width: 100 },
{ prop: 'street', label: '详细地址', width: 260 }
]
}
]
},
{ prop: 'action', label: '操作', width: 100, fixed: 'right' }
]
const data = [
{
id: 1,
name: '张伟',
age: 32,
dept: '研发中心',
position: '前端工程师',
phone: '13800001111',
city: '北京',
street: '朝阳区建国路 88 号'
},
{
id: 2,
name: '王芳',
age: 28,
dept: '财务部',
position: '会计',
phone: '13900002222',
city: '上海',
street: '浦东新区世纪大道 100 号'
},
{
id: 3,
name: '李娜',
age: 35,
dept: '市场部',
position: '市场经理',
phone: '13700003333',
city: '广州',
street: '天河区天河路 385 号'
}
]
</script>
<template>
<div style="max-width: 800px">
<NsTable :data="data" :columns="columns" border>
<template #action>
<NsButton size="small" type="primary" variant="link">编辑</NsButton>
</template>
</NsTable>
</div>
</template>
拖动调整列宽
带边框(border)时,鼠标移到表头单元格的右边缘会出现一条主色的线,按住拖动可以改这一列的宽度,松开后触发 column-resize,参数是列配置、新宽度和原来的宽度(px)。把手也能用 Tab 聚焦,按左、右方向键每次调整 10px。拖分组表头的右边缘调的是它最右边的那一列。
列配置里 resizable: false 的列不能拖动,minWidth 是拖动时的最小宽度(默认 40px)。建议留一列不设宽度:表格总是撑满容器,其他列都设了宽度时,多出来或不够的宽度会按比例分到每一列,拖动的列不会正好跟着鼠标走。下面“操作”列不能拖,“姓名”列最窄 80px,“地址”列不设宽度:
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsSpace, NsTable } from '@ns/ui'
import type { TableColumnConfig } from '@ns/ui'
const columns: TableColumnConfig[] = [
{ prop: 'name', label: '姓名', width: 120, minWidth: 80 },
{ prop: 'phone', label: '电话', width: 160 },
{ prop: 'address', label: '地址' },
{ prop: 'action', label: '操作', width: 100, resizable: false }
]
const data = [
{ id: 1, name: '张伟', phone: '13800001111', address: '北京市朝阳区建国路 88 号' },
{ id: 2, name: '王芳', phone: '13900002222', address: '上海市浦东新区世纪大道 100 号' },
{ id: 3, name: '李娜', phone: '13700003333', address: '广州市天河区天河路 385 号' }
]
const resizeText = ref('')
const handleColumnResize = (column: TableColumnConfig, width: number, oldWidth: number) => {
resizeText.value = `column-resize:“${column.label}”从 ${oldWidth}px 调到了 ${width}px`
}
</script>
<template>
<NsSpace direction="vertical" fill>
<NsTable :data="data" :columns="columns" border @column-resize="handleColumnResize">
<template #action>
<NsButton size="small" type="primary" variant="link">编辑</NsButton>
</template>
</NsTable>
<p>{{ resizeText || '拖动表头单元格之间的分隔线试试' }}</p>
</NsSpace>
</template>
超长省略
默认单元格内容放不下时换行。列上设 showOverflowTooltip: true 后,这一列只显示一行、放不下的部分显示省略号,鼠标移上去用提示显示完整内容(放得下时不提示)。表格上设 show-overflow-tooltip 对所有列生效,列上写 showOverflowTooltip: false 可以单独关掉。写了插槽的列也能省略,提示里显示插槽的文字。
下面第一张表只有“地址”列省略;第二张表所有列都省略,但“备注”列关掉了,照常换行:
<script setup lang="ts">
import { NsSpace, NsTable } from '@ns/ui'
import type { TableColumnConfig } from '@ns/ui'
const columns: TableColumnConfig[] = [
{ prop: 'name', label: '客户', width: 160 },
{ prop: 'address', label: '地址', width: 240, showOverflowTooltip: true },
{ prop: 'remark', label: '备注' }
]
const tableColumns: TableColumnConfig[] = [
{ prop: 'name', label: '客户', width: 160 },
{ prop: 'address', label: '地址', width: 240 },
{ prop: 'remark', label: '备注', showOverflowTooltip: false }
]
const data = [
{
id: 1,
name: '北京星辰科技有限公司',
address: '北京市朝阳区建国路 88 号现代城 SOHO 写字楼 B 座 2201 室',
remark: '每月 5 日前开具上月发票,邮寄到财务部王芳收。'
},
{
id: 2,
name: '上海浦江国际贸易有限责任公司',
address: '上海市浦东新区世纪大道 100 号',
remark: '只接受对公转账。'
},
{
id: 3,
name: '广州云帆物流',
address: '广州市天河区天河路 385 号太古汇一座 32 楼',
remark: '收货时间:工作日 9:00—18:00,周末不收货,请提前电话联系仓库。'
}
]
</script>
<template>
<NsSpace direction="vertical" fill>
<NsTable :data="data" :columns="columns" border />
<NsTable :data="data" :columns="tableColumns" show-overflow-tooltip border />
</NsSpace>
</template>
配合分页
表格本身不分页。把当前页的数据算出来传给 data,分页用 NsPagination。
<script setup lang="ts">
import { computed, ref } from 'vue'
import { NsPagination, NsSpace, NsTable } from '@ns/ui'
import type { TableColumnConfig } from '@ns/ui'
const columns: TableColumnConfig[] = [
{ prop: 'id', label: 'ID', width: 80 },
{ prop: 'name', label: '姓名', width: 120 },
{ prop: 'address', label: '地址' }
]
const surnames = ['张', '王', '李', '赵', '刘', '陈']
const givenNames = ['伟', '芳', '娜', '敏', '静']
const cities = ['北京市', '上海市', '广州市', '深圳市', '杭州市']
const all = Array.from({ length: 30 }, (_, index) => ({
id: index + 1,
name: `${surnames[index % 6]}${givenNames[index % 5]}`,
address: cities[index % 5]
}))
const currentPage = ref(1)
const pageSize = ref(10)
const pageData = computed(() => {
const start = (currentPage.value - 1) * pageSize.value
return all.slice(start, start + pageSize.value)
})
</script>
<template>
<NsSpace direction="vertical" fill>
<NsTable :data="pageData" :columns="columns" stripe />
<NsPagination
v-model:current-page="currentPage"
v-model:page-size="pageSize"
:total="all.length"
layout="total, sizes, prev, pager, next"
/>
</NsSpace>
</template>
Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| data | Record<string, unknown>[] | [] | 行数据 |
| columns | TableColumnConfig[] | - | 列配置。不传或传空数组时按第一行数据的字段名生成列 |
| stripe | boolean | false | 是否显示斑马纹 |
| border | boolean | false | 是否显示外边框和单元格之间的竖线。带边框时可以拖动表头调整列宽 |
| size | 'large' | 'default' | 'small' | - | 尺寸:单元格内边距 16 / 12 / 8px,字号 14 / 14 / 12px。不写时跟随 ConfigProvider,都没有时是 'default' |
| height | string | number | - | 表格高度,超出时表体滚动、表头固定。数字的单位是 px |
| maxHeight | string | number | - | 表格最大高度,超出后才滚动。数字的单位是 px |
| rowKey | string | ((row: Record<string, unknown>) => string) | 'id' | 行的唯一标识:字段名,或者返回标识的函数 |
| emptyText | string | '暂无数据' | 没有数据时显示的文字 |
| selectable | boolean | false | 是否在最左边显示复选框列 |
| defaultSort | { prop: string; order: 'ascending' | 'descending' } | - | 一开始的排序,只在创建时读取一次 |
| showHeader | boolean | true | 是否显示表头 |
| rowClassName | string | ((row: Record<string, unknown>, rowIndex: number) => string) | - | 行的类名 |
| cellClassName | string | ((row: Record<string, unknown>, column: TableColumnConfig, rowIndex: number) => string) | - | 单元格的类名 |
| headerCellClassName | string | ((column: TableColumnConfig) => string) | - | 表头单元格的类名。多级表头的分组单元格也会调用 |
| treeProps | TableTreeProps | - | 树形数据的字段名,默认 { children: 'children', hasChildren: 'hasChildren' } |
| indent | number | 16 | 树形数据每一级缩进的宽度(px) |
| load | TableLoadMethod | - | 懒加载子行。hasChildren 为真、还没有子行的行显示展开按钮,第一次展开时调用 |
| defaultExpandAll | boolean | false | 一开始展开所有树形节点和展开行,只在创建时读取一次(数据晚到也生效)。懒加载的行不会因此自动加载 |
| defaultExpandedKeys | (string | number)[] | - | 一开始展开的行(rowKey 的值),树形节点和展开行都适用,只在创建时读取一次 |
| expandable | boolean | false | 是否在左边显示展开列(在复选框列后面),点开后在这一行下面显示 expand 插槽 |
| accordion | boolean | false | 展开行同时只展开一行 |
| showSummary | boolean | false | 是否在表尾显示合计行 |
| summaryText | string | '合计' | 合计行第一列的文字 |
| summaryMethod | TableSummaryMethod | - | 自定义合计行每一列的内容。不传时把每一列数字类型的值加起来 |
| spanMethod | TableSpanMethod | - | 合并单元格:按行、列返回 [rowspan, colspan] 或 { rowspan, colspan },返回 0 的单元格不渲染 |
| showOverflowTooltip | boolean | false | 所有列的单元格只显示一行,放不下时显示省略号、鼠标移上去显示完整内容。列上的 showOverflowTooltip 优先于这里的设置 |
列配置 TableColumnConfig
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| prop | string | - | 必填。取行数据里的哪个字段,同时是这一列的插槽名。同一个表格里不能重复 |
| label | string | - | 必填。表头文字,超出列宽时显示省略号 |
| width | string | number | - | 列宽,数字的单位是 px。不设时平分剩下的空间 |
| align | 'left' | 'center' | 'right' | 'left' | 表头和单元格的对齐方式。多级表头的分组单元格不写时居中 |
| sortable | boolean | 'custom' | false | true 由表格排序;'custom' 只触发 sort-change,顺序由使用方处理。分组列设了不生效 |
| fixed | 'left' | 'right' | - | 横向滚动时固定在左边或右边。设在分组列上时,下面的列都跟着固定 |
| className | string | - | 加到这一列表头和单元格上的类名 |
| formatter | (row: Record<string, unknown>, column: TableColumnConfig, cellValue: unknown) => string | - | 返回单元格要显示的文字。这一列写了插槽时不生效 |
| children | TableColumnConfig[] | - | 下级列,用来做多级表头。有下级列的列只是表头上的分组,不对应数据 |
| resizable | boolean | true | 带边框时能不能拖动调整这一列的宽度 |
| minWidth | number | 40 | 拖动调整列宽时的最小宽度(px)。只限制拖动,不影响列宽的分配 |
| showOverflowTooltip | boolean | - | 单元格只显示一行,放不下时显示省略号,鼠标移上去显示完整内容。不写时跟随表格上的同名属性 |
Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| select | (selection: Record<string, unknown>[], row: Record<string, unknown>) | 某一行的选中状态变化时触发(点复选框或调用 toggleRowSelection)。selection 是变化后选中的全部行,row 是这一行 |
| select-all | (selection: Record<string, unknown>[]) | 点表头的全选框或调用 toggleAllSelection 时触发 |
| selection-change | (selection: Record<string, unknown>[]) | 选中的行有变化时触发,包括数据变化后选中的行被移除的情况 |
| sort-change | (sortState: TableSortState) | 点表头改变排序时触发。取消排序时 order 是 null |
| row-click | (row: Record<string, unknown>, column: TableColumnConfig | undefined, event: MouseEvent) | 点击某一行时触发,column 是点到的那一列。点复选框列、展开列和树形数据的展开按钮不触发 |
| cell-click | (row: Record<string, unknown>, column: TableColumnConfig, cell: HTMLTableCellElement, event: MouseEvent) | 点击单元格时触发,cell 是这个单元格的 <td> 元素。点复选框列、展开列不触发 |
| expand-change | (row: Record<string, unknown>, expanded: boolean, expandedRows: Record<string, unknown>[]) | 展开行或树形节点展开、收起时触发。expandedRows 是变化后展开着的全部行。expandAll、collapseAll 不触发 |
| column-resize | (column: TableColumnConfig, width: number, oldWidth: number) | 拖动或用方向键调整列宽后触发,宽度的单位是 px。拖动时松开鼠标才触发 |
Slots
| 插槽 | 作用域参数 | 说明 |
|---|---|---|
列的 prop | { row: Record<string, unknown>, column: TableColumnConfig, rowIndex: number } | 自定义这一列单元格的内容,插槽名就是列配置里的 prop。rowIndex 是排序、展开后看得见的行里的行号,从 0 开始 |
| expand | { row: Record<string, unknown>, rowIndex: number } | 展开行的内容,开了 expandable 才显示 |
| empty | - | 没有数据时显示的内容,写了以后不再显示 emptyText |
方法
通过组件的 ref 调用。
| 方法 | 参数 | 返回值 | 说明 |
|---|---|---|---|
| toggleRowSelection | (row: Record<string, unknown>, selected?: boolean) | void | 切换某一行的选中状态。传了 selected 时直接设成选中或不选中 |
| toggleAllSelection | - | void | 已经全选时取消全选,否则全选(树形数据包括收起着的子行)。没有数据时不做任何事 |
| clearSelection | - | void | 清空选中的行 |
| toggleRowExpansion | (row: Record<string, unknown>, expanded?: boolean) | void | 切换某一行的展开状态,传了 expanded 时直接设成展开或收起。开了 expandable 时切换展开行,否则切换树形节点(懒加载的行会先加载) |
| expandAll | - | void | 展开所有树形节点和展开行。不加载懒加载的行;开了 accordion 时不展开展开行 |
| collapseAll | - | void | 收起所有树形节点和展开行 |
ref 上还有两个只读用的状态:selection(当前选中的行)和 sortState(当前的排序状态)。
类型
import type {
TableColumnConfig,
TableSortState,
TableSize,
TableAlign,
TableProps,
TableTreeProps,
TableLoadMethod,
TableSummaryMethod,
TableSummaryMethodParams,
TableSpanMethod,
TableSpanMethodParams
} from '@ns/ui'
type TableSize = 'large' | 'default' | 'small'
type TableAlign = 'left' | 'center' | 'right'
interface TableColumnConfig {
prop: string
label: string
width?: string | number
align?: TableAlign
sortable?: boolean | 'custom'
fixed?: 'left' | 'right'
className?: string
formatter?: (
row: Record<string, unknown>,
column: TableColumnConfig,
cellValue: unknown
) => string
children?: TableColumnConfig[]
resizable?: boolean
minWidth?: number
showOverflowTooltip?: boolean
}
interface TableSortState {
prop: string
order: 'ascending' | 'descending' | null
}
interface TableTreeProps {
children?: string
hasChildren?: string
}
type TableLoadMethod = (
row: Record<string, unknown>,
resolve: (children: Record<string, unknown>[]) => void
) => void | Promise<Record<string, unknown>[] | void>
interface TableSummaryMethodParams {
columns: TableColumnConfig[]
data: Record<string, unknown>[]
}
type TableSummaryMethod = (
params: TableSummaryMethodParams
) => (string | number | null | undefined)[]
interface TableSpanMethodParams {
row: Record<string, unknown>
column: TableColumnConfig
rowIndex: number
columnIndex: number
}
type TableSpanMethod = (
params: TableSpanMethodParams
) => [number, number] | { rowspan: number; colspan: number } | void
另外还导出了 TableEmits、TableContext 和注入用的 TABLE_INJECTION_KEY,自己写和表格配合的子组件时才用得到。
注意事项
- 行数据的类型是
Record<string, unknown>。用interface声明的行类型没有索引签名,传给data时类型检查会报错,改用type声明,或者直接用对象字面量。插槽里row的字段类型是unknown,要按具体类型使用时自己转换(如String(row.name)、Number(row.age))。 - 行数据里取不到
rowKey对应的值时(没有这个字段,或值是null、undefined、空字符串),表格会给这一行生成一个内部标识,显示和勾选都正常。但这个标识跟着行对象走:重新请求数据后行对象换了,已勾选的行就对不上了。需要在数据刷新后保留勾选时,要保证每行有唯一的rowKey。 - 数据变化后,不在新数据里的选中行会被自动移除,并触发
selection-change;还在的行按rowKey对应到新数据里的对象。所以翻页后上一页的勾选不会保留。 - 排序不会修改
data,表格内部排的是一份拷贝。defaultSort只是初始值,之后改它不会重新排序。 - 字符串列用
localeCompare比较,中文的先后顺序取决于浏览器的语言环境,不一定是拼音顺序。对顺序有要求时用sortable: 'custom'自己排。 - 表格用的是固定布局:列宽只看
width,不会被内容撑宽。单元格里的内容放不下时自动换行(开了showOverflowTooltip的列显示省略号),表头文字放不下时显示省略号。 - 固定列要配合横向滚动才看得出效果:所有列都设了
width、宽度之和超过表格宽度时才会出现横向滚动条。固定列自己必须设width。 - 开了
selectable时鼠标移到行上显示手型,但点行不会勾选,勾选只能点复选框。想要点行勾选,可以在row-click里调用toggleRowSelection(row)。 - 列配置里
prop相同的两列会被当成同一列渲染,操作列这类自定义列也要起不重复的prop。多级表头的分组列也要有不重复的prop。 - 树形数据:只要第一层有一行带子行,第一列就为所有行留出箭头的位置。每一行(包括子行)都要有唯一的
rowKey,展开状态、勾选、懒加载回来的子行都按它记录。父行和子行的勾选互相独立,勾父行不会自动勾子行。排序时每一层的子行各自排序。 - 懒加载回来的子行由表格保存,
data刷新后同一个rowKey的行还会显示之前加载的子行,不会重新请求。 - 树形数据和展开行同时用时,
toggleRowExpansion只切换展开行,树形节点只能点箭头展开。 - 合并单元格时,
rowIndex按看得见的行算:树形节点展开、收起,排序以后都会变,spanMethod要按传进来的行号和行数据算。跨行合并的单元格不要跨过展开行。 - 多级表头建议配合
border使用,分组的范围看得更清楚。要固定一组列时把fixed写在分组列上;只固定分组里的一部分列时,分组单元格本身不固定。 - 拖动调整的列宽保存在表格里(按列的
prop),换了columns以后同一个prop的列还用拖过的宽度;表格卸载后就没有了,要记住列宽时在column-resize里自己保存,下次写进列配置的width。 - 超长省略的提示整张表只有一个,滚动表格、数据变化时自动收起。
优化点
- [x] 支持树形表格、懒加载子行
- [x] 支持多级表头、合并单元格
- [x] 支持行展开/折叠
- [x] 支持合计行、拖动调整列宽、超长省略提示
- [ ] 支持加载状态(
loading) - [ ] 支持列筛选
- [ ] 支持自定义表头内容的插槽
- [ ] 支持禁用某些行的勾选、点击行勾选
- [ ] 支持虚拟滚动优化大数据渲染
- [ ] 支持列拖拽排序
- [ ] 树形数据支持父子行勾选联动
- [ ] 支持部分行不能展开(展开行)