更新记录

1.0.0（2026-10-10）

u-table 是面向 uni-app 的通用表格组件，配套 u-table-column子组件。提供多表头、固定列、列宽拖拽、树形数据、分页、排序、筛选、合计、大屏滚动、大数据虚拟滚动、单行预览、单元格类型化渲染等企业级表格能力。

平台兼容性

uni-app(5.0)

u-table 通用表格组件

跨端通用表格组件，支持 Vue2 / Vue3、H5 / Chrome、微信 / 支付宝 / 抖音小程序。

目录

• 一、组件简介
• 二、架构设计
• 三、目录结构
• 四、安装与配置
• 五、快速上手
• 六、API 参考
  • Table Props
  • Table Methods
  • Table Events
  • Table Slots
  • Column Props
  • Column type 取值
• 七、使用示例
• 八、跨端与兼容性说明
• 九、已知限制
• 十、测试清单

一、组件简介

u-table 是面向 uni-app 的通用表格组件，配套 u-table-column 子组件。提供多表头、固定列、列宽拖拽、树形数据、分页、排序、筛选、合计、单行预览、单元格类型化渲染等企业级表格能力。

设计目标：

• 跨端：H5 / Chrome、微信、支付宝、抖音小程序原生支持。
• 跨框架：Vue2 与 Vue3 双兼容，统一 Options API 风格。
• 性能：树形懒加载、防抖测量、滚动加载分页、虚拟滚动预留接口。
• 易用：JSON columns 与声明式 <u-table-column> 双写法；命名插槽灵活自定义。
• 主题：CSS 变量 + rpx/px 混排，支持深色主题与自定义样式。

优先级实现状态：

二、架构设计

2.1 分层架构

┌────────────────────────────────────────────────────┐
│                  使用层（页面/父组件）              │
│   <u-table :columns="..." :data="...">              │
│     <u-table-column field="..." title="..." />      │
│   </u-table>                                        │
└───────────────────────┬────────────────────────────┘
                        │
                        ▼
┌────────────────────────────────────────────────────┐
│             u-table.vue（主组件）                  │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────┐  │
│  │  状态层      │  │  事件层      │  │  方法层  │  │
│  │  data/props  │  │  emit/on     │  │  ref 调用│  │
│  └──────┬───────┘  └──────┬───────┘  └────┬─────┘  │
│         │                 │               │        │
│         └─────────────────┴───────────────┘        │
│                           │                        │
│   ┌───────────────────────┼────────────────────┐   │
│   │      渲染层（template + style）            │   │
│   │  表头矩阵 → 数据行 → 合计 → 分页 → 预览     │   │
│   └───────────────────────┬────────────────────┘   │
└───────────────────────────┼────────────────────────┘
                            │
                            ▼
┌────────────────────────────────────────────────────┐
│   utils.js（纯函数工具层）   types.js（类型/常量） │
│   列归一化、表头矩阵、树形扁平化、格式化、        │
│   排序、筛选、分页、CSV 导出、尺寸解析             │
└────────────────────────────────────────────────────┘

2.2 核心流程

初始化流程：

1. mounted 钩子
   │
   ├─→ rebuildColumns()
   │     ├─→ normalizeColumns(columns/childColumns)
   │     ├─→ buildHeaderMatrix()   ← 递归构建多表头矩阵 + 叶子列 + 分区
   │     └─→ computeFixedOffsets() ← 计算左右固定列偏移
   │
   ├─→ expandAll() (若 defaultExpandAll)
   │
   └─→ measureRowHeights() (防抖) ← uni.createSelectorQuery 测量行高

数据渲染流程：

props.data → processedData (本地筛选 + 排序) → flattenTree (树形扁平化)
            → slicePage (客户端分页，仅按钮分页模式) → renderRows → 渲染

拖拽流程：

表头 cell 右侧 handle → Start (mouse/touch) → Move (更新 __width)
                                                       └─→ End (重算固定列偏移 + emit)

2.3 关键设计决策

三、目录结构

本组件采用 uni_modules 标准结构，便于 easycom 自动注册：

uni_modules/u-table/
├── package.json
├── readme.md
├── changelog.md
└── components/
    ├── u-table/                   # 主组件
    │   ├── u-table.vue            # 主组件源码
    │   ├── utils.js               # 工具函数（纯函数）
    │   └── types.js               # 类型常量、默认配置
    └── u-table-column/            # 声明式列子组件（独立目录，便于 easycom）
        └── u-table-column.vue

说明：u-table-column 单独成目录是为了让 easycom 自动注册机制可在用户页面模板中直接使用 <u-table-column> 标签（默认 easycom 规则要求组件名 = 文件夹名 = 文件名）。

组件完整文档即本文件（readme.md）；版本变更见 changelog.md。

四、安装与配置

4.1 easycom 自动注册

uni_modules 下的组件默认按 easycom 自动注册，无需手动 import。在模板中直接使用即可：

<u-table :columns="columns" :data="data" />

4.2 手动注册（可选）

若需要禁用 easycom 或自定义路径，可在 pages.json 中配置：

{
    "easycom": {
        "autoscan": true,
        "custom": {
            "^u-table$": "@/uni_modules/u-table/components/u-table/u-table.vue",
            "^u-table-column$": "@/uni_modules/u-table/components/u-table-column/u-table-column.vue"
        }
    }
}

4.3 全局主题样式（可选）

可通过覆盖 CSS 变量自定义主题：

/* 全局样式中 */
page {
    --u-table-border-color: #ebeef5;
    --u-table-header-bg: #f5f7fa;
    --u-table-row-bg: #ffffff;
    --u-table-stripe-bg: #fafafa;
    --u-table-hover-bg: #f5f7fa;
    --u-table-text-color: #303133;
    --u-table-text-secondary: #909399;
    --u-table-header-text: #303133;
}

五、快速上手

5.1 最简示例

<template>
    <view class="container">
        <u-table :columns="columns" :data="data" border stripe />
    </view>
</template>

<script>
export default {
    data() {
        return {
            columns: [
                { field: 'name', title: '姓名', width: 120 },
                { field: 'age', title: '年龄', width: 100, align: 'right' },
                { field: 'gender', title: '性别', width: 100, filters: { 1: '男', 2: '女' }, filterable: true }
            ],
            data: [
                { id: 1, name: '张三', age: 28, gender: 1 },
                { id: 2, name: '李四', age: 24, gender: 2 },
                { id: 3, name: '王五', age: 32, gender: 1 }
            ]
        };
    }
};
</script>

5.2 声明式写法（u-table-column）

<u-table :data="data" border>
    <u-table-column field="name" title="姓名" :width="120" />
    <u-table-column field="age" title="年龄" :width="100" align="right" />
    <u-table-column field="gender" title="性别" :width="100" :filters="{ 1: '男', 2: '女' }" filterable />
</u-table>

六、API 参考

Table Props

Table Methods

通过 ref 调用：

Table Events

Table Slots

Column Props

columns 数组中每一项或 <u-table-column> 上可设置的属性：

filters 取值：

• 对象：{ 1: '启用', 0: '停用' }
• 数组：[{ value: 1, label: '启用' }, { value: 0, label: '停用' }]
• 也可省略 filters：当 filterable: true 且未提供 filters 时，自动从当前 data 对应 field 去重生成选项（空值显示为 column.emptyString，默认 '--'）。

远程筛选分页（onFilter）：

当列设置了 onFilter(page, callback) 时，打开筛选弹层会通过该函数远程分页拉取标签，不再本地生成。选项列表底部有"加载更多"按钮，点击追加下一页；每列独立缓存已加载进度，关闭再开不重复请求。

{
  title: '姓名', field: 'name', filterable: true,
  onFilter: (page, callback) => {
    // 一次加载 5 条，共 30 条（6 页）；hasMore 表示是否还有下一页
    const perPage = 5, total = 30;
    const start = (page - 1) * perPage;
    const names = Array.from({ length: total }, (_, i) => '远程用户' + (i + 1));
    callback(names.slice(start, start + perPage), page * perPage < total);
  }
}

• labels 可为 ['张三','李四'] 字符串数组，或 [{ value, label }] 对象数组（内部自动识别转换）。
• hasMore 为 true 时底部显示"加载更多"按钮；false 且已加载 >1 页时显示"没有更多了"。
• 筛选弹层顶部提供"全部"选框，用于一键全选 / 取消全选下方标签。

Column type 取值

列宽分配说明：autoWidth（默认 false）控制是否启用自适应列宽。开启时：设定了宽度的列使用固定宽度；未设宽度的列在容器有剩余空间时按比例铺满；当所有列都设置宽度且容器有剩余宽度时，按设置宽度比例均分填满容器。关闭时列宽仅由初始化宽度决定。checkbox / radio / index 列的列宽仅由初始化宽度决定，不参与自适应分配，但可手动拖拽调整。hidden: true 的列不参与任何列宽计算。minWidth 表头/表体同源，保证对齐。

纵向滚动条占位：H5 端在固定（height）或受限（maxHeight）高度且内容超出时出现的右侧纵向滚动条会被计入列宽分配——均分与比例铺满时从容器宽度先减去滚动条占位宽，避免自适应后列宽总和超出可视宽而额外多出一条横向滚动条。

七、使用示例

7.1 JSON columns 示例

<template>
    <u-table :columns="columns" :data="data" border stripe />
</template>

<script>
export default {
    data() {
        return {
            columns: [
                { field: 'name', title: '姓名', width: 120 },
                { field: 'age', title: '年龄', width: 100, align: 'right', sortable: true }
            ],
            data: [
                { id: 1, name: '张三', age: 28 },
                { id: 2, name: '李四', age: 24 }
            ]
        };
    }
};
</script>

7.2 u-table-column 声明式示例

<u-table :data="data" border>
    <u-table-column type="selection" :width="50" />
    <u-table-column type="index" title="#" :width="60" />
    <u-table-column field="name" title="姓名" :width="120" />
    <u-table-column field="age" title="年龄" :width="100" align="right" sortable />
</u-table>

7.3 多表头示例

<u-table :columns="columns" :data="data" border />

<script>
export default {
    data() {
        return {
            columns: [
                { field: 'name', title: '姓名', width: 120, fixed: 'left' },
                {
                    title: '基本信息',
                    children: [
                        { field: 'age', title: '年龄', width: 100 },
                        { field: 'gender', title: '性别', width: 100, filters: { 1: '男', 2: '女' }, filterable: true }
                    ]
                },
                {
                    title: '联系方式',
                    children: [
                        { field: 'phone', title: '电话', width: 150 },
                        { field: 'email', title: '邮箱', width: 200 }
                    ]
                }
            ],
            data: [
                { id: 1, name: '张三', age: 28, gender: 1, phone: '***', email: 'zhang@example.com' }
            ]
        };
    }
};
</script>

7.4 固定列示例

<u-table :columns="columns" :data="data" border height="400" />

<script>
export default {
    data() {
        return {
            columns: [
                { field: 'id', title: 'ID', width: 80, fixed: 'left' },
                { field: 'name', title: '姓名', width: 120, fixed: 'left' },
                { field: 'age', title: '年龄', width: 100 },
                { field: 'address', title: '地址', width: 300 },
                { field: 'phone', title: '电话', width: 150 },
                { field: 'email', title: '邮箱', width: 200 },
                { field: 'actions', title: '操作', width: 100, fixed: 'right', slot: 'actions' }
            ]
        };
    }
};
</script>

7.5 树形懒加载示例

<u-table
    :columns="columns"
    :data="data"
    row-key="id"
    :tree-props="{ children: 'children', hasChildren: 'hasChildren' }"
    :lazy="true"
    :load="loadChildren"
    border
/>

<script>
export default {
    data() {
        return {
            columns: [
                { field: 'name', title: '名称', width: 240 },
                { field: 'count', title: '数量', width: 120, align: 'right' }
            ],
            data: [
                { id: 1, name: '父节点 1', count: 0, hasChildren: true },
                { id: 2, name: '父节点 2', count: 0, hasChildren: true }
            ]
        };
    },
    methods: {
        // 懒加载：返回子节点数组
        loadChildren(row) {
            return new Promise((resolve) => {
                setTimeout(() => {
                    resolve([
                        { id: row.id + '_a', name: row.name + '-子A', count: 10 },
                        { id: row.id + '_b', name: row.name + '-子B', count: 20 }
                    ]);
                }, 500);
            });
        }
    }
};
</script>

7.6 分页示例

按钮分页（客户端分页）：

<u-table
    :columns="columns"
    :data="data"
    :pagination="true"
    :page-size="10"
    :pager-count="5"
    @page-change="onPageChange"
/>

<script>
export default {
    methods: {
        onPageChange({ page, pageSize }) {
            console.log('切换到第', page, '页');
        }
    }
};
</script>

远程分页：

<u-table
    :columns="columns"
    :data="remoteData"
    :pagination="true"
    :remote="true"
    :remote-pagination="true"
    :total="total"
    :page="page"
    :page-size="pageSize"
    @page-change="fetchData"
/>

滚动加载分页：

<u-table
    :columns="columns"
    :data="data"
    :pagination="true"
    pagination-mode="scroll"
    :is-show-load-more="loading"
    :is-no-more="noMore"
    @load-more="loadMore"
/>

7.7 插槽示例

<u-table :columns="columns" :data="data">
    <!-- 默认单元格插槽：插槽名等于 field -->
    <template #gender="{ row, value }">
        <text :style="{ color: value === 1 ? '#409eff' : '#f56c6c' }">
            {{ value === 1 ? '男' : '女' }}
        </text>
    </template>

    <!-- 自定义列插槽名 -->
    <template #actions="{ row }">
        <view class="row-actions">
            <text @click="onEdit(row)">编辑</text>
            <text @click="onDelete(row)">删除</text>
        </view>
    </template>

    <!-- 表头插槽 -->
    <template #header-age="{ column }">
        <view>
            <text>{{ column.title }}</text>
            <text style="font-size: 20rpx; color: #909399;">(岁)</text>
        </view>
    </template>

    <!-- 空数据自定义 -->
    <template #empty>
        <view style="padding: 60rpx; text-align: center;">
            <image src="/static/empty.png" mode="aspectFit" style="width: 200rpx; height: 200rpx;" />
            <text>暂无数据，去添加一条吧</text>
        </view>
    </template>
</u-table>

<script>
export default {
    data() {
        return {
            columns: [
                { field: 'name', title: '姓名', width: 120 },
                { field: 'gender', title: '性别', width: 100 },
                { field: 'age', title: '年龄', width: 100, headerSlot: 'header-age' },
                { field: 'actions', title: '操作', width: 160, slot: 'actions' }
            ]
        };
    }
};
</script>

小程序插槽降级：微信/支付宝/抖音小程序的动态插槽名支持有限，优先使用固定命名插槽 cellSlot（见第八节：跨端与兼容性说明）；如遇编译失败，参考该节中的降级方案。

7.8 合计示例

<u-table
    :columns="columns"
    :data="data"
    :show-summary="true"
    sum-text="总计"
    :border="true"
/>

<script>
export default {
    data() {
        return {
            columns: [
                { field: 'name', title: '商品', width: 200 },
                { field: 'price', title: '单价', width: 120, align: 'right' },
                { field: 'quantity', title: '数量', width: 100, align: 'right' },
                { field: 'total', title: '小计', width: 140, align: 'right' }
            ],
            data: [
                { id: 1, name: '苹果', price: 5, quantity: 10, total: 50 },
                { id: 2, name: '香蕉', price: 3, quantity: 8, total: 24 }
            ]
        };
    }
};
</script>

自定义合计方法：

<u-table
    :columns="columns"
    :data="data"
    :show-summary="true"
    :summary-method="summaryMethod"
/>

<script>
export default {
    methods: {
        summaryMethod({ columns, data }) {
            return columns.map((col, i) => {
                if (i === 0) return '总计';
                if (col.field === 'quantity') {
                    return '共 ' + data.reduce((a, b) => a + b.quantity, 0) + ' 件';
                }
                const sum = data.reduce((a, b) => a + Number(b[col.field] || 0), 0);
                return isNaN(sum) ? '' : '¥' + sum;
            });
        }
    }
};
</script>

7.9 单行预览示例

<u-table
    :columns="columns"
    :data="data"
    :preview="true"
    preview-title="用户详情"
    preview-width="90%"
    @preview="onPreview"
/>

<script>
export default {
    methods: {
        onPreview(row) {
            console.log('预览行：', row);
        }
    }
};
</script>

通过 preview 插槽可整体替换预览弹窗内容（未提供时使用内置字段列表渲染）：

<u-table
    :columns="columns"
    :data="data"
    :preview="true"
    preview-title="用户详情"
    @preview="onPreview"
>
    <template #preview="{ row, columns }">
        <view class="custom-preview">
            <text>{{ row.name }}</text>
            <text>{{ row.address }}</text>
        </view>
    </template>
</u-table>

7.9.1 大屏滚动示例（continuous 单页滚动 / paged 多页翻页）

开启 scrollScreen 后，仅当数据行总高度超过可视高度时才启用自动滚动/翻页；数据少则保持静态。 悬停 / 触摸滚动区域即暂停，移开 / 松开继续；上方控制条可手动播放/暂停。 注意：scrollScreen 与 virtual 互斥，开启大屏滚动会自动禁用虚拟滚动，也不会再走前端分页切片（需展示全量数据流动）。

<!-- continuous：单页自动上滚（跑马灯），每秒 40px，循环 -->
<u-table
    :columns="columns"
    :data="data"
    row-key="id"
    height="400"
    scroll-screen
    scroll-screen-mode="continuous"
    :scroll-screen-speed="40"
    border
/>

<!-- paged：多页整屏翻页，每 4000ms 翻一页，循环 -->
<u-table
    :columns="columns"
    :data="data"
    row-key="id"
    height="400"
    scroll-screen
    scroll-screen-mode="paged"
    :scroll-screen-speed="4000"
    border
/>

<!-- 关闭控制条 / 不循环（到末页停止） -->
<u-table
    :columns="columns"
    :data="data"
    row-key="id"
    height="400"
    scroll-screen
    scroll-screen-mode="continuous"
    :scroll-screen-loop="false"
    :scroll-screen-control="false"
/>

7.10 综合示例（多特性叠加）

<u-table
    ref="tableRef"
    :columns="columns"
    :data="data"
    row-key="id"
    height="600"
    border
    stripe
    :pagination="true"
    :page-size="10"
    :show-summary="true"
    :preview="true"
    :default-expand-all="false"
    :expand-keys="['1']"
    :tree-props="{ children: 'children', hasChildren: 'hasChildren' }"
    @row-click="onRowClick"
    @selection-change="ionChange"
    @sort-change="onSortChange"
    @page-change="onPageChange"
>
    <template #toolbar>
        <view class="toolbar">
            <button size="mini" @click="exportData">导出 CSV</button>
            <button size="mini" @click="reload">刷新</button>
        </view>
    </template>

    <template #status="{ row }">
        <text :style="{ color: row.status === 1 ? '#67c23a' : '#f56c6c' }">
            {{ row.status === 1 ? '启用' : '停用' }}
        </text>
    </template>

    <template #actions="{ row }">
        <text style="color: #409eff; margin-right: 20rpx;" @click.stop="onEdit(row)">编辑</text>
        <text style="color: #f56c6c;" @click.stop="onDelete(row)">删除</text>
    </template>
</u-table>

<script>
export default {
    data() {
        return {
            columns: [
                { type: 'selection', width: 50 },
                { type: 'index', title: '#', width: 60 },
                { field: 'name', title: '名称', width: 200, fixed: 'left' },
                { field: 'status', title: '状态', width: 100, slot: 'status', filters: { 1: '启用', 0: '停用' }, filterable: true },
                { field: 'createTime', title: '创建时间', width: 180, type: 'datetime', sortable: true },
                { field: 'amount', title: '金额', width: 120, align: 'right', sortable: true },
                { field: 'actions', title: '操作', width: 160, fixed: 'right', slot: 'actions' }
            ],
            data: []
        };
    },
    methods: {
        onRowClick(row) { /* ... */ },
        ionChange(rows) { /* ... */ },
        onSortChange({ field, order }) { /* ... */ },
        onPageChange({ page }) { /* ... */ },
        exportData() { this.$refs.tableRef.exportCsv('用户数据'); },
        reload() { this.$refs.tableRef.reload(); }
    }
};
</script>

八、跨端与兼容性说明

8.1 端能力矩阵

8.2 条件编译策略

8.3 动态插槽名降级方案

微信/支付宝/抖音小程序对动态插槽名（如 #<field>）支持有限，遇到编译错误时按以下顺序降级：

1. 优先（推荐）：单元格列配置 slot: true，表头列配置 headerSlot: true，组件将对应列渲染到固定命名插槽 cellSlot / headerSlot（作用域：cellSlot 为 { row, column, rowIndex, value }，headerSlot 为 { column }），可在父级模板中按 row / column 分发自定义内容；未配置对应属性的列保持默认文本渲染，不受插槽影响：

   <u-table :columns="columns" :data="data">
    <template #cellSlot="{ row, column, value }">
      <text v-if="column.field === 'status'" :style="{ color: value === 1 ? '#67c23a' : '#f56c6c' }">
        {{ value === 1 ? '启用' : '停用' }}
      </text>
    </template>
   </u-table>

   // columns 中：status、actions 两列走 cellSlot，其余列默认渲染
   columns: [
    { field: 'age', title: '年龄', align: 'right' },           // 默认文本，右对齐
    { field: 'status', title: '状态', slot: true },             // 走 cellSlot
    { field: 'actions', title: '操作', slot: true },            // 走 cellSlot
   ]

2. 其次：在 <u-table-column> 上使用 cell-slot prop 显式声明具名插槽（⚠️ 不能写成 slot，slot 是 Vue 保留属性）：

   <u-table-column field="status" title="状态" cell-slot="status" />

   列对象内部统一映射为 slot 字段（与 JSON columns 写法一致），仅组件 prop 名为 cellSlot。

3. H5/App 可使用 column.render 函数（待后续版本支持）。
4. 最后：使用 formatter 替代自定义插槽。
5. 详见已知限制。

8.4 Vue2 / Vue3 兼容

• 使用 Options API 风格，避免 Composition API 专属语法。
• 插槽访问统一：this.$scopedSlots || this.$slots。
• 生命周期兼容：同时实现 beforeDestroy（Vue2）与 beforeUnmount（Vue3）。
• $set / $delete 在 Vue3 中已废弃但 Vue2 中必需；本组件已使用并在 Vue3 中视为 no-op。

九、已知限制

十、测试清单

10.1 Vue2 测试清单

10.2 Vue3 测试清单

10.3 Chrome 测试清单

10.4 微信小程序测试清单

10.5 支付宝小程序测试清单

10.6 抖音小程序测试清单

附：版本与变更日志

参见 changelog.md。