Table 表格

约 2583 字大约 9 分钟

2025-10-31

表格组件，用于展示大量结构化数据，支持多级表头、自定义列内容、行列样式等功能。

基本使用

通过 data 属性传入数据，配合 un-table-column 定义列：

<template>
	<un-page>
		<un-table :data="tableData">
			<un-table-column prop="name" label="姓名" height="50"></un-table-column>
			<un-table-column prop="education" label="学历" height="50"></un-table-column>
			<un-table-column prop="phone" label="电话" height="50" width="110"></un-table-column>
			<un-table-column prop="email" label="邮箱" height="50" width="180"></un-table-column>
			<un-table-column prop="address" label="地址" height="50" width="200"></un-table-column>
		</un-table>
	</un-page>
</template>

<script setup lang="uts">
import { ref } from 'vue';

// 基础表格数据
const tableData = ref([
	{
		date: '2023-01-01',
		name: '张三',
		education: '本科',
		address: '北京市海淀区',
		phone: '13800000000',
		email: 'zhangsan@example.com',
		avatar: 'https://pic.qqans.com/up/2023-6/2023615923363981.jpg'
	},
	{
		date: '2023-01-02',
		name: '李四',
		education: '硕士',
		address: '上海市浦东新区',
		phone: '13900000000',
		email: 'lisi@example.com',
		avatar: 'https://pic.qqans.com/up/2023-7/202376745468967.jpg'
	},
	{
		date: '2023-01-03',
		name: '王五',
		education: '博士',
		address: '广州市天河区',
		phone: '13700000000',
		email: 'wangwu@example.com',
		avatar: 'https://pic.qqans.com/up/2022-10/20221013923495441.jpg'
	},
	{
		date: '2023-01-04',
		name: '赵六',
		education: '硕士',
		address: '南京市江宁区',
		phone: '13600000000',
		email: 'zhaoliu@example.com',
		avatar: 'https://pic.qqans.com/up/2023-8/202381072034402.jpg'
	}
]);
</script>

斑马纹表格

通过 stripe 属性可以创建斑马纹表格：

<template>
	<un-page>
		<un-table :data="tableData" stripe>
			<un-table-column prop="name" label="姓名" height="50"></un-table-column>
			<un-table-column prop="education" label="学历" height="50"></un-table-column>
			<un-table-column prop="phone" label="电话" height="50" width="110"></un-table-column>
			<un-table-column prop="email" label="邮箱" height="50"></un-table-column>
			<un-table-column prop="address" label="地址" height="50"></un-table-column>
		</un-table>
	</un-page>
</template>

<script setup lang="uts">
import { ref } from 'vue';

// 基础表格数据
const tableData = ref([
	{
		date: '2023-01-01',
		name: '张三',
		education: '本科',
		address: '北京市海淀区',
		phone: '13800000000',
		email: 'zhangsan@example.com',
		avatar: 'https://pic.qqans.com/up/2023-6/2023615923363981.jpg'
	},
	{
		date: '2023-01-02',
		name: '李四',
		education: '硕士',
		address: '上海市浦东新区',
		phone: '13900000000',
		email: 'lisi@example.com',
		avatar: 'https://pic.qqans.com/up/2023-7/202376745468967.jpg'
	},
	{
		date: '2023-01-03',
		name: '王五',
		education: '博士',
		address: '广州市天河区',
		phone: '13700000000',
		email: 'wangwu@example.com',
		avatar: 'https://pic.qqans.com/up/2022-10/20221013923495441.jpg'
	},
	{
		date: '2023-01-04',
		name: '赵六',
		education: '硕士',
		address: '南京市江宁区',
		phone: '13600000000',
		email: 'zhaoliu@example.com',
		avatar: 'https://pic.qqans.com/up/2023-8/202381072034402.jpg'
	}
]);
</script>

边框控制

表格支持多种边框模式，通过 border 属性控制：

<template>
	<un-page>
		<!-- 水平边框 -->
		<un-table :data="tableData" border="horizontal">
			<un-table-column prop="name" label="姓名" height="50"></un-table-column>
			<un-table-column prop="education" label="学历" height="50"></un-table-column>
			<un-table-column prop="phone" label="电话" height="50" width="110"></un-table-column>
			<un-table-column prop="email" label="邮箱" height="50"></un-table-column>
			<un-table-column prop="address" label="地址" height="50"></un-table-column>
		</un-table>

		<!-- 无边框 -->
		<un-table :data="tableData" :border="false">
			<un-table-column prop="name" label="姓名" height="50"></un-table-column>
			<un-table-column prop="education" label="学历" height="50"></un-table-column>
			<un-table-column prop="phone" label="电话" height="50" width="110"></un-table-column>
			<un-table-column prop="email" label="邮箱" height="50"></un-table-column>
			<un-table-column prop="address" label="地址" height="50"></un-table-column>
		</un-table>
	</un-page>
</template>

<script setup lang="uts">
import { ref } from 'vue';

// 基础表格数据
const tableData = ref([
	{
		date: '2023-01-01',
		name: '张三',
		education: '本科',
		address: '北京市海淀区',
		phone: '13800000000',
		email: 'zhangsan@example.com',
		avatar: 'https://pic.qqans.com/up/2023-6/2023615923363981.jpg'
	},
	{
		date: '2023-01-02',
		name: '李四',
		education: '硕士',
		address: '上海市浦东新区',
		phone: '13900000000',
		email: 'lisi@example.com',
		avatar: 'https://pic.qqans.com/up/2023-7/202376745468967.jpg'
	},
	{
		date: '2023-01-03',
		name: '王五',
		education: '博士',
		address: '广州市天河区',
		phone: '13700000000',
		email: 'wangwu@example.com',
		avatar: 'https://pic.qqans.com/up/2022-10/20221013923495441.jpg'
	},
	{
		date: '2023-01-04',
		name: '赵六',
		education: '硕士',
		address: '南京市江宁区',
		phone: '13600000000',
		email: 'zhaoliu@example.com',
		avatar: 'https://pic.qqans.com/up/2023-8/202381072034402.jpg'
	}
]);
</script>

横向滚动控制

通过 scroll 属性控制表格的横向滚动：

<template>
	<un-page>
		<un-table :data="tableData" :scroll="false">
			<un-table-column prop="name" label="姓名" height="50"></un-table-column>
			<un-table-column prop="education" label="学历" height="50"></un-table-column>
			<un-table-column prop="phone" label="电话" height="50" width="110"></un-table-column>
			<un-table-column prop="email" label="邮箱" height="50"></un-table-column>
		</un-table>
	</un-page>
</template>

<script setup lang="uts">
import { ref } from 'vue';

// 基础表格数据
const tableData = ref([
	{
		date: '2023-01-01',
		name: '张三',
		education: '本科',
		address: '北京市海淀区',
		phone: '13800000000',
		email: 'zhangsan@example.com',
		avatar: 'https://pic.qqans.com/up/2023-6/2023615923363981.jpg'
	},
	{
		date: '2023-01-02',
		name: '李四',
		education: '硕士',
		address: '上海市浦东新区',
		phone: '13900000000',
		email: 'lisi@example.com',
		avatar: 'https://pic.qqans.com/up/2023-7/202376745468967.jpg'
	},
	{
		date: '2023-01-03',
		name: '王五',
		education: '博士',
		address: '广州市天河区',
		phone: '13700000000',
		email: 'wangwu@example.com',
		avatar: 'https://pic.qqans.com/up/2022-10/20221013923495441.jpg'
	},
	{
		date: '2023-01-04',
		name: '赵六',
		education: '硕士',
		address: '南京市江宁区',
		phone: '13600000000',
		email: 'zhaoliu@example.com',
		avatar: 'https://pic.qqans.com/up/2023-8/202381072034402.jpg'
	}
]);
</script>

自定义列模板

可以通过插槽自定义列的显示内容：

<template>
	<un-page>
		<un-table :data="tableData">
			<un-table-column prop="avatar" label="头像" width="100" height="50">
				<template #item="{ row }">
					<un-avatar :src="row['avatar']" size="35"></un-avatar>
				</template>
			</un-table-column>
			<un-table-column prop="name" label="姓名" width="100" height="50"></un-table-column>
			<un-table-column prop="education" label="学历" width="100" height="50">
				<template #item="{ row }">
					<un-tag :text="row['education']" size="mini"></un-tag>
				</template>
			</un-table-column>
			<un-table-column prop="address" label="地址" height="50"></un-table-column>
		</un-table>
	</un-page>
</template>

<script setup lang="uts">
import { ref } from 'vue';

// 基础表格数据
const tableData = ref([
	{
		date: '2023-01-01',
		name: '张三',
		education: '本科',
		address: '北京市海淀区',
		phone: '13800000000',
		email: 'zhangsan@example.com',
		avatar: 'https://pic.qqans.com/up/2023-6/2023615923363981.jpg'
	},
	{
		date: '2023-01-02',
		name: '李四',
		education: '硕士',
		address: '上海市浦东新区',
		phone: '13900000000',
		email: 'lisi@example.com',
		avatar: 'https://pic.qqans.com/up/2023-7/202376745468967.jpg'
	},
	{
		date: '2023-01-03',
		name: '王五',
		education: '博士',
		address: '广州市天河区',
		phone: '13700000000',
		email: 'wangwu@example.com',
		avatar: 'https://pic.qqans.com/up/2022-10/20221013923495441.jpg'
	},
	{
		date: '2023-01-04',
		name: '赵六',
		education: '硕士',
		address: '南京市江宁区',
		phone: '13600000000',
		email: 'zhaoliu@example.com',
		avatar: 'https://pic.qqans.com/up/2023-8/202381072034402.jpg'
	}
]);
</script>

多级表头

表格支持多级表头，通过嵌套 un-table-column 实现：

<template>
	<un-page>
		<un-table :data="tableData2">
			<un-table-column prop="name" label="姓名" width="120" height="50" headerAlign="center"></un-table-column>
			<un-table-column label="联系信息" headerAlign="center">
				<template #header="{ column }">
					<un-tag type="primary" :text="column.label" size="mini"></un-tag>
				</template>
				<un-table-column prop="phone" label="手机号码" height="50" headerAlign="center"></un-table-column>
				<un-table-column prop="email" label="电子邮箱" height="50" headerAlign="center"></un-table-column>
			</un-table-column>
			<un-table-column label="教育信息" headerAlign="center">
				<un-table-column prop="education.degree" label="学历" height="50">
					<template #item="{ row }">
						<un-tag type="primary" :text="row['degree']" size="mini"></un-tag>
					</template>
				</un-table-column>
				<un-table-column prop="school" label="毕业院校" height="50"></un-table-column>
			</un-table-column>
			<un-table-column prop="address" label="地址" height="50" headerAlign="center"></un-table-column>
		</un-table>
	</un-page>
</template>

<script setup lang="uts">
import { ref } from 'vue';

// 多级表头表格数据
const tableData2 = ref([
	{
		name: '张三',
		phone: '13800000000',
		email: 'zhangsan@example.com',
		degree: '本科',
		school: '北京大学',
		address: '北京市海淀区'
	},
	{
		name: '李四',
		phone: '13900000000',
		email: 'lisi@example.com',
		degree: '硕士',
		school: '清华大学',
		address: '上海市浦东新区'
	},
	{
		name: '王五',
		phone: '13700000000',
		email: 'wangwu@example.com',
		degree: '博士',
		school: '复旦大学',
		address: '广州市天河区'
	}
]);
</script>

监听事件

单元格点击事件

可以监听单元格点击事件：

<template>
	<un-page>
		<un-table :data="tableData" @cell-click="handleCellClick" @header-click="handleHeaderClick">
			<un-table-column prop="name" label="姓名" height="50"></un-table-column>
			<un-table-column prop="education" label="学历" height="50"></un-table-column>
			<un-table-column prop="phone" label="电话" height="50" width="110"></un-table-column>
			<un-table-column prop="email" label="邮箱" height="50" width="180"></un-table-column>
			<un-table-column prop="address" label="地址" height="50" width="200"></un-table-column>
		</un-table>
	</un-page>
</template>

<script setup lang="uts">
import { ref } from 'vue';

// 基础表格数据
const tableData = ref([
	{
		date: '2023-01-01',
		name: '张三',
		education: '本科',
		address: '北京市海淀区',
		phone: '13800000000',
		email: 'zhangsan@example.com',
		avatar: 'https://pic.qqans.com/up/2023-6/2023615923363981.jpg'
	},
	{
		date: '2023-01-02',
		name: '李四',
		education: '硕士',
		address: '上海市浦东新区',
		phone: '13900000000',
		email: 'lisi@example.com',
		avatar: 'https://pic.qqans.com/up/2023-7/202376745468967.jpg'
	},
	{
		date: '2023-01-03',
		name: '王五',
		education: '博士',
		address: '广州市天河区',
		phone: '13700000000',
		email: 'wangwu@example.com',
		avatar: 'https://pic.qqans.com/up/2022-10/20221013923495441.jpg'
	},
	{
		date: '2023-01-04',
		name: '赵六',
		education: '硕士',
		address: '南京市江宁区',
		phone: '13600000000',
		email: 'zhaoliu@example.com',
		avatar: 'https://pic.qqans.com/up/2023-8/202381072034402.jpg'
	}
]);

const handleCellClick = (row: UTSJSONObject) => {
	console.log('单元格点击事件', row)
}

const handleHeaderClick = (row: UTSJSONObject) => {
	console.log('表头点击事件', row)
}
</script>

API

Table Props

参数	说明	类型	默认值
data	显示的数据	Array	[]
tableLayout	表格布局方式	Enum	fixed
scroll	是否开启横向滚动	Boolean	true
stripe	是否为斑马纹 table	Boolean	false
showHeader	是否显示表头	Boolean	true
cellStyle	单元格的样式	String/Object	-
headerCellStyle	表头单元格的样式	String/Object	-
border	表格边框	Enum	false
loadingMode v4.1.7	加载状态图标类型	Enum	spinner
loadingSize v4.1.7	加载图标大小	string \| number	22
loadingIcon v4.1.7	自定义图标名称，参考 un-icon 组件, 支持图片, `mode`为`custom`时有效	string	-
loadingText v4.1.7	加载状态文本	string	加载中...
loadingColor v4.1.7	加载状态颜色	string	-

Table Events

事件名	说明	类型
cell-click	当某个单元格被点击时会触发该事件	Function
header-click	当某一列的表头被点击时会触发该事件	Function

Table-column Props

参数	说明	类型	默认值
prop	对应列内容的字段名	String	-
label	显示的标题	String	-
width	对应列的宽度	String/Number	-
height	对应列的高度	String/Number	-
minHeight	对应列的最小高度	String/Number	-
minWidth	对应列的最小宽度	String/Number	-
headerHeight	表头高度	String/Number	44
align	对齐方式	Enum	left
headerAlign	表头对齐方式	Enum	left

Table-column Slot

名称	说明	类型
header	自定义表头的内容	Object
default	自定义列的内容	Object
item	自定义列的内容	Object

数据类型


// 表格列属性类型，用于定义表格列的配置。
type UnTableColumnProps = {
    prop: string                    // 列内容的字段名
    label: string                   // 显示的标题
    width: string | number          // 列的宽度
    height: string | number         // 列的高度
    minHeight: string | number      // 列的最小高度
    minWidth: string | number       // 列的最小宽度
    headerHeight: string | number   // 表头高度
    align: 'left' | 'center' | 'right'    // 内容对齐方式
    headerAlign: 'left' | 'center' | 'right'  // 表头对齐方式
}

// 单元格点击事件回调参数类型，在 `cell-click` 事件中返回。
type UnTableCellClickEvent = {
    row: UTSJSONObject              // 当前行数据
    column: UnTableColumnProps      // 当前列配置
    event: UniEvent                 // 原始事件对象
}

// 表头点击事件回调参数类型，在 `header-click` 事件中返回。
type UnTableHeaderClickEvent = {
    column: UnTableColumnProps       // 当前列配置
    event: UniEvent                 // 原始事件对象
}

Scss 变量

变量名	默认值	说明
$un-table-border	1px solid $border-color	表格边框样式
$un-table-column-header-padding	10px	表头内边距
$un-table-column-header-min-height	44px	表头最小高度
$un-table-column-header-bg-color	$bg-color-lighter	表头背景颜色
$un-table-column-cell-padding	6px	单元格内边距
$un-table-column-cell-min-height	28px	单元格最小高度
$un-table-column-cell-bg-color	#ffffff	单元格背景颜色
$un-table-column-cell-stripe-bg-color	$bg-color-lighter	斑马纹单元格背景颜色
$un-table-column-border	1px solid $border-color	单元格边框样式

提示

组件内部默认使用 scss 变量，如需修改，请查看 scss 变量使用文档