更新记录

1.0.4（2026-09-14） 下载此版本

预览图

1.0.3（2026-09-14） 下载此版本

修改说明

1.0.2（2026-09-14） 下载此版本

修复 排序缺少图标问题 css 去除 scss

平台兼容性

uni-app(5.22)

其他

ia-table 表格组件使用说明

一个适用于 uni-app (Vue3) 高性能表格组件，支持固定列、排序、远程分页、虚拟滚动、多选勾选等能力。

功能特性

• ✅ 本地静态数据 / 远程分页数据两种数据源
• ✅ 表头点击排序（降序 → 升序 → 取消），支持多字段排序
• ✅ 固定列（首列 / 前 N 列 sticky 吸住）
• ✅ 横向 / 纵向滚动，表头与表体联动
• ✅ 滚动到底自动加载下一页（远程模式）
• ✅ 复选框多选 + 全选
• ✅ 虚拟滚动（上万行数据只渲染可视区，性能优）
• ✅ 单元格 / 表头 均可插槽自定义
• ✅ 空状态占位、加载动画
• ✅ 表头吸顶（配合页面滚动）

一、安装与引用

组件位于 src/uni_modules/ia-table/，是标准的 uni_modules 结构。

• HBuilderX 项目：直接把 uni_modules/ia-table 文件夹拷入 src/uni_modules/ 即可。
• CLI 项目：同目录结构；pages.json 的 easycom.autoscan 开启时会自动扫描 uni_modules/*/components/*/，无需注册、无需 import：

<!-- 直接使用（easycom 自动注册） -->
<ia-table :list="list" :columns="columns"></ia-table>

二、快速上手

2.1 最小示例（本地数据）

<template>
    <ia-table :list="list" :columns="columns" :height="300" border="bottom"></ia-table>
</template>

<script>
export default {
    data() {
        return {
            list: [
                { code: '000001', name: '平安银行', change: 1.22 },
                { code: '600519', name: '贵州茅台', change: 3.15 },
            ],
            columns: [
                { label: '代码', field: 'code', width: 160, fixed: true },
                { label: '名称', field: 'name', width: 200, sort: true },
                { label: '涨跌幅', field: 'change', width: 180, sort: true },
            ]
        }
    }
}
</script>

2.2 远程分页（list 传函数）

list 传入一个返回 Promise 的请求函数，组件内部用 Paginate 分页器封装：

• 首次进入、排序、滚到底部时自动请求。
• 请求参数默认带 iDisplayStart（偏移）、iDisplayLength（每页 15）、sSorts（排序串）。

<template>
    <ia-table id="remote" :list="fetchList" :columns="columns" :height="400" scroll
        :params="{ userId: 1 }" :loading-show="true"></ia-table>
</template>

<script>
export default {
    data() {
        return { columns: [{ label: '名称', field: 'name', width: 200, sort: true }] }
    },
    methods: {
        // 返回 Promise，遵守 DataTables 协议
        fetchList(params) {
            return new Promise((resolve) => {
                setTimeout(() => {
                    const start = params.iDisplayStart || 0
                    const length = params.iDisplayLength || 15
                    resolve({
                        aaData: Array.from({ length }).map((_, i) => ({ name: '项目' + (start + i + 1) })),
                        iTotalDisplayRecords: 200
                    })
                }, 500)
            })
        }
    }
}
</script>

params 会被合并进请求参数（除分页参数外），排序时还会自动带上 sSorts: "field,asc|desc"。 组件实例还暴露了 query(reload)、reload()、checkboxAll() 方法，可通过 ref 调用。

三、Props 属性

四、columns 列配置

columns = [
    {
        label: '代码',      // 表头文案
        field: 'code',      // 字段名（同时是单元格插槽名）
        width: 160,         // 列宽 rpx（必填，总宽=各列宽之和，固定列偏移依赖它）
        sort: true,         // 点击表头可排序
        fixed: true,        // 固定列（sticky 吸左）
        align: 'center',    // left | center | right
        height: 80,         // 列高 rpx（默认取 itemHeight）
        style: { color: 'red' }, // 附加该列内联样式
    }
]

📌 fixed 固定列注意：偏移 = 该列左侧所有列宽之和，因此固定列前面的列务必设置 width，否则偏移计算错误。 📌 开启 role* 无——若列定义里没有任何 width，表格总宽为 100%（列均分）。

五、事件

按 ref 调用实例方法：

this.$refs.table.query(true)      // 远程模式刷新（true=回到第一页）
this.$refs.table.reload()         // 清空并重载
this.$refs.table.checkboxAll()    // 全选/取消全选
this.$refs.table.setColumns()     // 从默认插槽的子组件收集列配置

六、插槽（Slots）

<ia-table :list="list" :columns="columns">
    <!-- 按列名自定义单元格 -->
    <template #name="{ value }">
        <text class="red">{{ value }}</text>
    </template>
    <!-- 兜底插槽：批量自定义其它列 -->
    <template #otherField="{ value, row, field, index }">
        <text>{{ value || '-' }}</text>
    </template>
    <!-- 空状态 -->
    <template #empty>
        <view class="empty">暂无数据</view>
    </template>
</ia-table>

七、高级用法

7.1 表头吸顶（页面滚动模式）

表格不设内部高度，随页面一起滚，表头滚到顶部后吸住：

<template>
    <ia-table ref="table" :list="list" :columns="columns" :uni-page-scroll="true"></ia-table>
</template>
<script>
export default {
    onPageScroll(e) {
        this.$refs.table.pageScroll(e)   // 转发滚事件给表格，超过表格顶部时吸顶
    }
}
</script>

7.2 虚拟滚动（万行数据）

<ia-table id="demo-v" :list="bigList" :columns="columns" :height="400"
    scroll :virtual="true" :item-height="80" :virtual-prefix="5" :virtual-suffix="5">
</ia-table>

• 必须传唯一 id，必须设 height（或 scroll 容器有固定高度），行高需等距。
• 开启虚拟滚动后，@changeVirtual / @change 可拿到当前真实渲染的数据切片，便于按需懒加载详情。
• ⚠️ iOS + 固定列 组合会自动退化为占位式渲染（仍保留全部节点，性能略降），这是 bug 场景兼容。

7.3 复选框多选

<ia-table :list="list" :columns="columns" checkbox
    @selectionChange="list => selected = list">
</ia-table>

八、远程分页协议说明

组件内置的 Paginate 分页器约定（兼容 DataTables 风格），通过构造函数 resKey 可自定义 key：

// 响应三种格式均可：
// ① { aaData: [...], iTotalDisplayRecords: 100 }
// ② { data: [...], total: 100 }
// ③ { data: { data: [...], total: 100 } }

九、常见问题 / 备注

1. list 是本地数组为何点击排序没反应？ 需要 sortLocal 传 true（本地排序），否则只触发 @sort 事件（给远程场景预留）。

2. 固定列偏移不对？ 固定列左侧的所有列都必须配置 width，偏移量按 width 累加计算。

3. 表头高度与视觉不符？ 样式底层表头固定 50px。若通过 headerHeight 改了值，需要同步改 ia-table.vue 中 .i-table__header { height }，否则吸顶/滚动区间计算会偏移。

4. 空状态为什么什么都不显示？ 新版本去掉了内置 ia-empty，空状态通过 #empty 插槽自定义（旧属性 defaultNot/defaultIcon 已废弃，不再生效）。

5. 组件已经修复的坑：

   • this.data → this.list（init / sortClick / scrolltolower 中误用旧属性名，导致远程模式不生效的隐患）
   • Paginate 构造参数默认解构语法兼容编译器
   • util.js 补上 default 导出（组件内部 import _ from './util'）

6. 虚拟滚动 + 固定列 在 iOS 上的表现： iOS 上该组合会降级为占位渲染，行数很多时开销仍较大；如追求极致性能建议「虚拟滚动」与「固定列」二选一。