uView Next
4.1.6

外观

Table 表格

约 2702 字大约 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>

大量数据展示

对于大量数据展示场景，推荐使用 columns 属性进行配置式列定义，可大幅提升App端的性能和用户体验。

<template>
	<un-page>
		<un-table :data="tableData1" :columns="columns"></un-table>
	</un-page>
</template>

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

const tableData1 = ref([
	{ name: '张三', age: 18, gender: 'male' ,department:'销售部',phone:'13800000000',email:'zhangsan@example.com',address:'北京市海淀区'},
	{ name: '李四', age: 22, gender: 'female' ,department:'销售部',phone:'13900000000',email:'lisi@example.com',address:'上海市浦东新区'},
	{ name: '王五', age: 30, gender: 'male' ,department:'销售部',phone:'13700000000',email:'wangwu@example.com',address:'广州市天河区'},
	{ name: '赵六', age: 25, gender: 'female' ,department:'销售部',phone:'13600000000',email:'zhaoliu@example.com',address:'南京市江宁区'}
]);
	
const columns = ref([
	{
		prop: 'name',
		title: '姓名',
		width: 100,
		align: 'center'
	},
	{
		prop: 'age',
		title: '年龄',
		width: 100,
		align: 'center'
	},
	{
		prop: 'gender',
		title: '性别',
		width: 100,
		align: 'center'
	},
	{
		prop: 'department',
		title: '部门',
		width: 100,
		align: 'center'
	},
	{
		prop: 'phone',
		title: '电话',
		width: 110,
		align: 'center'
	},
	{
		prop: 'email',
		title: '邮箱',
		width: 180,
		align: 'center'
	},
	{
		prop: 'address',
		title: '地址',
		width: 200,
		align: 'center'
	},
] as UnTableColumn[]);
</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是否开启横向滚动Booleantrue
stripe是否为斑马纹 tableBooleanfalse
showHeader是否显示表头Booleantrue
cellStyle单元格的样式String/Object-
headerCellStyle表头单元格的样式String/Object-
border表格边框
Enum
false
loading v4.1.7是否显示加载状态Booleanfalse
loadingMode v4.1.7加载状态图标类型
Enum
spinner
loadingSize v4.1.7加载图标大小string | number22
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/Number44
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                 // 原始事件对象
}

Copyright © 2026 uView Next