Table 表格

面向业务列表的数据表格，支持排序、选择、滚动和自定义单元格。

命令行安装

npx @loongship-kit/ui add table

组件结构

角色	组件	职责	使用条件
根组件	Table	数据、排序、选择、滚动和状态管理	必需
数据列	TableColumn	声明字段、表头、格式化和选择列	数据驱动模式必需
表格分区	TableHeader、TableBody、TableFooter	组织原生语义表格分区	组合式模式按需
行与单元格	TableRow、TableHead、TableCell	构成原生语义表格的行和单元格	组合式模式按需
辅助内容	TableCaption	提供原生表格标题或说明	组合式模式按需

基础用法

查看代码

<script setup lang="ts">
import { Table, TableColumn } from '@/components/loongship/table'

const rows = [
  { id: 1, name: 'EVER GIVEN', status: '航行中', destination: 'CNSHA', speed: 12.4 },
  { id: 2, name: 'MSC OSCAR', status: '靠泊', destination: 'SGSIN', speed: 0 },
  { id: 3, name: 'OOCL HONG KONG', status: '锚泊', destination: 'NLRTM', speed: 0.2 }
]
</script>

<template>
  <Table :data="rows" row-key="id" stripe>
    <TableColumn prop="name" label="船名" min-width="180" />
    <TableColumn prop="status" label="状态" width="120" />
    <TableColumn prop="destination" label="目的港" width="120" />
    <TableColumn
      prop="speed"
      label="航速"
      width="100"
      align="right"
      :formatter="(_row, _column, value) => `${value} kn`"
    />
  </Table>
</template>

选择与排序

已选择 0 艘船

查看代码

<script setup lang="ts">
import { ref } from 'vue'
import { Table, TableColumn } from '@/components/loongship/table'

const selectedCount = ref(0)
const rows = [
  { id: 1, name: 'EVER GIVEN', destination: 'CNSHA', speed: 12.4 },
  { id: 2, name: 'MSC OSCAR', destination: 'SGSIN', speed: 0 }
]
</script>

<template>
  <div style="display: grid; gap: var(--ls-space-2)">
    <span style="color: var(--ls-color-text-secondary); font-size: var(--ls-font-size-sm)">
      已选择 {{ selectedCount }} 艘船
    </span>
    <Table
      :data="rows"
      row-key="id"
      border
      highlight-current-row
      @selection-change="selectedCount = $event.length"
    >
      <TableColumn type="selection" width="48" />
      <TableColumn prop="name" label="船名" min-width="180" sortable />
      <TableColumn prop="destination" label="目的港" width="120" sortable="custom" />
      <TableColumn prop="speed" label="航速" width="100" align="right" sortable />
    </Table>
  </div>
</template>

自定义单元格与空状态

没有符合条件的船舶

查看代码

<script setup lang="ts">
import { Table, TableColumn } from '@/components/loongship/table'
</script>

<template>
  <Table :data="[]" empty-text="没有符合条件的船舶">
    <TableColumn prop="name" label="船名" min-width="180">
      <template #default="{ row }"
        ><strong>{{ row.name }}</strong></template
      >
    </TableColumn>
    <template #empty><span>没有符合条件的船舶</span></template>
  </Table>
</template>

API

Table（主组件）

属性

属性	类型	默认值	说明
data	TableRowData[]	-	传入后启用数据驱动模式
rowKey	string | ((row) => string | number)	-	行唯一键，保留选择状态时必填
height	string | number	-	表格固定高度
maxHeight	string | number	-	表格最大高度
stripe	boolean	false	显示斑马纹
border	boolean	false	显示纵向边框
size	'large' | 'default' | 'small'	'default'	表格尺寸
fit	boolean	true	表格宽度是否撑满容器
showHeader	boolean	true	是否显示表头
highlightCurrentRow	boolean	false	点击后高亮当前行
currentRowKey	string | number	-	当前行键
emptyText	string	'暂无数据'	空状态文本
defaultSort	{ prop: string; order?: SortOrder }	-	默认排序
showOverflowTooltip	boolean	false	所有普通列溢出时显示原生提示
scrollbarAlwaysOn	boolean	false	始终挂载纵向滚动条
tableLayout	'fixed' | 'auto'	'fixed'	原生 table-layout
loading	boolean	false	显示加载遮罩
selectOnIndeterminate	boolean	true	半选时点击全选框是否转为全选
rowClassName	string | ((scope) => string)	-	行类名
rowStyle	CSSProperties | ((scope) => CSSProperties)	-	行样式
cellClassName	string | ((scope) => string)	-	单元格类名
cellStyle	CSSProperties | ((scope) => CSSProperties)	-	单元格样式

事件

事件	参数	说明
select	(selection, row)	用户切换一行的选择状态
select-all	(selection)	用户点击全选框
selection-change	(selection)	选择结果变化
current-change	(currentRow, oldCurrentRow)	当前行变化
row-click	(row, column, event)	点击行
row-dblclick	(row, column, event)	双击行
cell-click	(row, column, cell, event)	点击单元格
sort-change	({ column, prop, order })	排序条件变化

插槽

插槽	参数	说明
default	—	数据驱动模式放置 TableColumn；组合式模式放置分区
empty	—	自定义空状态

方法

方法	参数	说明
clearSelection	()	清空选择
getSelectionRows	()	获取已选择行
toggleRowSelection	(row, selected?, ignoreSelectable?)	切换指定行选择状态
toggleAllSelection	()	切换全选状态
setCurrentRow	(row?)	设置当前行
clearSort	()	清空排序
sort	(prop, order)	设置排序

子组件

TableColumn — 数据列

属性

属性	类型	默认值	说明
type	'default' | 'selection' | 'index'	'default'	列类型
prop	string	-	字段路径，支持点号路径
label	string	-	表头文本
width	string | number	-	固定宽度
minWidth	string | number	-	最小宽度
align	'left' | 'center' | 'right'	'left'	单元格对齐
headerAlign	'left' | 'center' | 'right'	-	表头对齐
sortable	boolean | 'custom'	false	本地排序或仅触发远程排序事件
sortMethod	(a, b) => number	-	本地排序比较函数
sortBy	string | string[] | ((row, index) => unknown)	-	本地排序取值规则
sortOrders	SortOrder[]	-	排序状态轮转顺序
formatter	(row, column, value, index) => unknown	-	单元格格式化函数
showOverflowTooltip	boolean	false	此列溢出时显示原生提示
selectable	(row, index) => boolean	-	选择列的行可选判断
reserveSelection	boolean	false	数据更新后按 rowKey 保留选择
index	number | ((index) => number | string)	-	索引列起始值或格式化函数

插槽

插槽	参数	说明
default	{ row, column, $index }	自定义单元格
header	{ column, $index }	自定义表头

TableHeader / TableBody / TableFooter — 组合式分区

属性

属性	类型	默认值	说明
class	ClassValue	-	语义元素自定义类名

插槽

插槽	参数	说明
default	—	放置 TableRow

TableRow / TableHead / TableCell — 组合式行与单元格

属性

属性	类型	默认值	说明
class	ClassValue	-	语义元素自定义类名

插槽

插槽	参数	说明
default	—	表格内容

TableCaption — 组合式标题

属性

属性	类型	默认值	说明
class	ClassValue	-	标题自定义类名

插槽

插槽	参数	说明
default	—	标题内容