TTable / 表格

Table for displaying structured data with rich features: sorting, filtering, pagination, row selection, expandable rows, column resizing, fixed columns, and custom cell rendering via slots. / 表格用于展示结构化数据，支持排序、筛选、分页、行选择、展开行、列宽拖拽、固定列和自定义渲染插槽。

Props / 属性

Prop	Type / 类型	Default / 默认值	Description / 说明
data	T[]	—	Data array / 数据数组
columns	TableColumn[]	—	Column config / 列配置
rowKey	string | function	—	Unique row identifier
pagination	boolean | TablePaginationConfig	—	Pagination config
rowSelection	TableRowSelection	—	Row selection config
sortBy / sortOrder	string | null	—	Controlled sort
expandable	TableExpandable	—	Expandable rows config
scroll	TableScroll	—	Scroll config (x/y)
size	'large' | 'middle' | 'small'	—	Table size
bordered	boolean	false	Show borders
striped	boolean	false	Striped rows
hover	boolean	false	Hover highlight
emptyText	string	—	Empty state text

TableColumn 接口

interface TableColumn<T = any> {
  key: string                  // 字段名
  title: string                // 表头文字
  width?: string | number      // 列宽
  align?: 'left' | 'center' | 'right'
  fixed?: 'left' | 'right'    // 固定列
  sortable?: boolean           // 启用排序
  sorter?: (a: T, b: T) => number  // 自定义排序
  filters?: TableFilterItem[]  // 筛选项
  render?: (text, record, index) => any  // 自定义渲染
  resizable?: boolean          // 列宽拖拽
}

Events / 事件

Event	Description / 说明
@page-change	Page changed
@sort-change	Sort changed
@filter-change	Filter changed
@row-click	Row clicked

Slots / 插槽

Slot	Scoped Props	Description / 说明
#cell(key)	{ row, column, index }	Custom cell render / 自定义单元格
#header	—	Custom header area
#empty	—	Custom empty state

Basic Usage / 基础用法

<script setup lang="ts">
import { TTable, type TableColumn } from '@gulcc/tabler-vue'

const columns: TableColumn[] = [
  { key: 'name', title: 'Name / 姓名', sortable: true },
  { key: 'age', title: 'Age / 年龄', align: 'right' },
  { key: 'email', title: 'Email' },
]

const data = [
  { name: 'Zhang San', age: 28, email: 'zhangsan@example.com' },
  { name: 'Li Si', age: 32, email: 'lisi@example.com' },
]
</script>

<template>
  <TTable :columns="columns" :data="data" />
</template>

Advanced Usage / 进阶场景

<script setup lang="ts">
import { TTable, type TableColumn } from '@gulcc/tabler-vue'

const columns: TableColumn[] = [
  { key: 'name', title: 'Name / 姓名', sortable: true },
  { key: 'role', title: 'Role / 角色', filters: [{ text: 'Admin', value: 'admin' }, { text: 'User', value: 'user' }] },
  { key: 'status', title: 'Status / 状态' },
]

const current = ref(1)
</script>

<template>
  <!-- Full-featured table / 完整功能表格 -->
  <TTable
    :columns="columns"
    :data="tableData"
    :pagination="{ pageSize: 10, total: 100 }"
    :row-selection="{ type: 'checkbox' }"
    :scroll="{ x: '100%' }"
    bordered
    striped
    hover
    @page-change="current = $event"
  >
    <!-- Custom cell rendering / 自定义列渲染 -->
    <template #cell(status)="{ row }">
      <TBadge :color="row.status === 'active' ? 'success' : 'secondary'">
        {{ row.status }}
      </TBadge>
    </template>
  </TTable>

  <!-- Expandable rows / 展开行 -->
  <TTable
    :columns="columns"
    :data="data"
    :expandable="{ expandedRowRender: (record) => record.detail }"
  />
</template>

Tips / 避坑指南

• rowKey is essential for selection and expand features — use a unique field like 'id' or a function (row) => row.id
• Pagination can be true (default settings) or TablePaginationConfig object for full control
• Custom cell rendering: use #cell(key) slot or the render function in TableColumn
• For column resizing, add resizable: true to the column config — shows a drag handle on the column edge
• Fixed columns (fixed: 'left' | 'right') require scroll.x to be set