taro4-react-table

一个基于 Taro 4 + React 的移动端 Table 组件，专门面向微信小程序场景。组件不依赖浏览器原生 table，内部基于 View 和 ScrollView 实现横向滚动、固定表头、固定左列、固定右列、选择和排序。

安装

npm install taro4-react-table

项目需要已经安装：

npm install react @tarojs/components

使用

import { View } from '@tarojs/components'
import { Table, type TableColumn } from 'taro4-react-table'
import 'taro4-react-table/dist/style.css'

interface Order {
  id: number
  no: string
  customer: string
  amount: number
  status: string
  createdAt: string
}

const columns: Array<TableColumn<Order>> = [
  {
    key: 'no',
    title: '订单号',
    dataIndex: 'no',
    width: 220,
    fixed: 'left',
    ellipsis: true
  },
  {
    key: 'customer',
    title: '客户',
    dataIndex: 'customer',
    width: 180
  },
  {
    key: 'amount',
    title: '金额',
    dataIndex: 'amount',
    width: 160,
    align: 'right',
    sortable: true,
    render: (value) => `¥${value}`
  },
  {
    key: 'status',
    title: '状态',
    dataIndex: 'status',
    width: 140
  },
  {
    key: 'createdAt',
    title: '创建时间',
    dataIndex: 'createdAt',
    width: 220
  },
  {
    key: 'action',
    title: '操作',
    width: 140,
    fixed: 'right',
    render: () => '查看'
  }
]

const dataSource: Order[] = [
  {
    id: 1,
    no: 'SO202607140001',
    customer: '上海第一门店',
    amount: 1280,
    status: '已付款',
    createdAt: '2026-07-14'
  }
]

export default function OrderPage() {
  return (
    <View>
      <Table<Order>
        rowKey="id"
        columns={columns}
        dataSource={dataSource}
        height={640}
        striped
        selection={{
          type: 'checkbox',
          onChange: (keys, rows) => {
            console.log(keys, rows)
          }
        }}
        onSortChange={(state) => {
          console.log(state)
        }}
        onRowClick={({ record }) => {
          console.log(record)
        }}
      />
    </View>
  )
}

API

TableProps

| 属性 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | columns | TableColumn<T>[] | - | 列配置 | | dataSource | T[] | - | 数据源 | | rowKey | keyof T \| (record, index) => string \| number | - | 行唯一键 | | loading | boolean | false | 加载态 | | loadingText | ReactNode | 加载中... | 加载文案 | | emptyText | ReactNode | 暂无数据 | 空状态文案 | | bordered | boolean | true | 是否显示边框 | | striped | boolean | false | 是否显示斑马纹 | | size | 'small' \| 'middle' \| 'large' | 'middle' | 表格密度 | | height | number \| string | - | 表体高度，设置后表头固定、表体纵向滚动 | | selection | TableSelection<T> | - | 行选择配置 | | sortState | TableSortState | - | 受控排序状态 | | defaultSortState | TableSortState | - | 默认排序状态 | | onSortChange | (state) => void | - | 排序变化回调 | | onRowClick | (params) => void | - | 行点击回调 | | onCellClick | (params) => void | - | 单元格点击回调 |

TableColumn

| 属性 | 类型 | 说明 | | --- | --- | --- | | key | string | 列唯一键 | | title | ReactNode | 表头内容 | | dataIndex | keyof T \| string | 字段路径，支持 user.name | | width | number \| string | 列宽，数字按 rpx 处理 | | minWidth | number \| string | 最小列宽 | | align | 'left' \| 'center' \| 'right' | 对齐方式 | | fixed | 'left' \| 'right' | 固定列方向 | | ellipsis | boolean \| { lines?: number } | 文本省略，首版按单行省略处理 | | sortable | boolean | 是否展示排序入口 | | render | (value, record, index) => ReactNode | 自定义单元格 | | headerRender | (column) => ReactNode | 自定义表头 |

TableSelection

| 属性 | 类型 | 说明 | | --- | --- | --- | | type | 'checkbox' \| 'radio' | 选择类型 | | selectedRowKeys | (string \| number)[] | 受控选中 key | | defaultSelectedRowKeys | (string \| number)[] | 默认选中 key | | columnTitle | ReactNode | 选择列表头内容，不传时 checkbox 模式展示全选 | | columnWidth | number \| string | 选择列宽度 | | fixed | 'left' \| 'right' | 选择列固定方向，默认 left | | getCheckboxProps | (record, index) => { disabled?: boolean } | 行选择禁用配置 | | onChange | (selectedRowKeys, selectedRows) => void | 选择变化回调 |

样式定制

组件使用 trt-table class 前缀，并提供 CSS 变量：

.my-table {
  --trt-table-header-bg: #f7f8fa;
  --trt-table-primary-color: #1677ff;
  --trt-table-row-height: 88rpx;
  --trt-table-cell-padding: 0 20rpx;
}

<Table className="my-table" columns={columns} dataSource={dataSource} rowKey="id" />

当前边界

• 只面向微信小程序移动端。
• 首版不支持 H5。
• 首版不包含虚拟滚动。
• 首版不支持合并单元格。
• 排序默认只维护排序状态并抛出事件，不自动改写 dataSource。