更新记录

1.0.0（2026-04-22） 下载此版本

根据你的要求，以下是 xq-table 组件 v1.0.0 版本的更新日志内容，可直接复制到插件根目录的 changelog.md 文件中，保持同步。

Changelog

[1.0.0] - 2026-04-22

平台兼容性

uni-app(4.13)

uni-app x(4.76)

xq-table

📦 xq-table - 多功能增强型表格组件

一个基于 uni-app 官方 uni-table 深度封装的增强型表格组件，支持自定义全选/半选样式、列显示隐藏（本地持久化）、多端固定列宽省略号、排序/筛选事件代理等特性，适用于后台管理系统数据展示。 组件已按 easycom 规范编写，导入即可自动识别，无需手动 import

✨ 核心特性

• ✅ 自定义全选复选框：支持半选（横线）、全选（对勾）、未选（空）三种状态，样式统一可控。
• ✅ 列显示/隐藏：内置齿轮按钮弹窗，用户可自由选择要显示的列，支持按 prop 禁用某些列。
• ✅ 本地存储列配置：传入 local-cloumn-keys 即可自动保存/读取用户列设置，刷新页面保持。
• ✅ 跨端省略号适配：内置 u-line-1 ~ u-line-5 样式类，nvue 与非 nvue 自动兼容。
• ✅ 事件代理机制：排序、筛选事件统一通过 execEvent 代理，支持列配置中直接声明 events 回调。
• ✅ 多选增强方法：暴露 selectionAll、toggleRowSelection、clearSelection、toggleAllSelection 等方法。
• ✅ 插槽支持：自定义列内容、操作栏等，灵活扩展。

📁 文件结构

components/xq-table/
├── index.vue          # 组件主文件
├── utils.js           # 本地存储工具函数（getStorage / setStorage）
└── README.md          # 使用文档

🚀 快速上手

1. 引入组件

<script setup>
import { tableColumns, tableRes } from './tableData.js'

const columns = ref(tableColumns)
const tableData = ref([])
</script>

<template>
  <xq-table
    v-model:columns="columns"
    :table-data="tableData"
    type="selection"
    row-key="postId"
    local-cloumn-keys="my_table_columns"
    @selection-change="ionChange"
    @sort-change="onSortChange"
  />
</template>

2. 列配置示例（tableData.js）

export const tableColumns = [
  { prop: 'postId', label: '岗位编号', width: 100, sortable: true, visible: true },
  { prop: 'postName', label: '岗位名称', minWidth: 120, visible: true },
  { prop: 'status', label: '状态', slot: 'status', visible: true, disabled: false },
  { prop: 'action', label: '操作', slot: 'action', visible: true, disabled: true }
]

📋 Props

📤 Events

🧩 Slots

使用示例：

<template>
  <xq-table v-model:columns="columns" :table-data="tableData">
    <template #status="{ row }">
      <u-tag v-if="row.status === '0'" text="启用" type="success" />
      <u-tag v-else text="禁用" type="error" />
    </template>
  </xq-table>
</template>

🛠️ 方法 (通过 ref 调用)

调用示例：

const tableRef = ref(null)
tableRef.value.selectionAll()
tableRef.value.toggleRowSelection([0]) // 切换第一行
tableRef.value.toggleRowSelection([0], true) // 强制选中第一行

💡 高级用法

列配置对象支持 events 属性，用于定义列的事件处理逻辑。 详细的列属性说明文档。

📋 xq-table 列配置属性说明

每个列对象支持以下属性，用于定义表头和数据单元格的展示及行为。

🔧 通用属性

🔀 排序属性

🔍 筛选属性

⚡ 事件属性

📝 完整列配置示例

以下可以直接在页面中书写,也可以放到统一列配置中.

列配置1

export const tableColumns = [
  {
    prop: 'postId',
    label: '岗位编号',
    visible: true,
    width: 80,
    tooltip: false,
    sortable: true,
    disabled: true, // 强制显示，不可取消
    events: {
      'sort-change': ({ column, event }) => {
        console.log('排序变化', event.order)
      }
    }
  },
  {
    prop: 'postName',
    label: '岗位名称',
    visible: true,
    minWidth: 120, // 最小宽度 120rpx
    tooltip: true
  },
  {
    prop: 'status',
    label: '状态',
    slot: 'status', // 使用插槽自定义内容
    visible: true,
    filterType: 'select', // 筛选类型为下拉
    filterData: [ // 下拉的内容
      { text: '全部', value: '' },
      { text: '启用', value: '0' },
      { text: '禁用', value: '1' }
    ],
    events: {
      'filter-change': ({ column, event }) => {
        console.log('筛选值', event.value)
      }
    }
  },
  {
    prop: 'action',
    label: '操作',
    slot: 'action',
    visible: true,
    width: 200
  }
]

列配置2

import { tableColumns } from './xxx.js'
// 定义事件处理器（只关注业务逻辑）
const eventHandlers = {
  postId: {
    'sort-change': (e) => {
      console.log('岗位编号排序', e)
      // 直接调用接口、更新 state
    },
  },
  status: {
    'filter-change': (e) => {
      console.log('岗位状态过滤', e)
      // 直接调用接口、更新 state
    },
  },
}

// 最好是做一个深拷贝, 确保不会影响其他页面的引用
const columns = ref(
  tableColumns.map(col => ({ ...col, events: eventHandlers[col.prop] || col.events || {} })),
)

📌 注意事项

• width 与 minWidth：建议至少设置一个，避免列宽被内容无限撑开导致省略号失效。
• tooltip：仅在内容溢出（设置了 u-line-1 等省略类）且 tooltip 不为 false 时生效。
• events：事件回调中可通过 emit 向父组件通信，但通常推荐在父组件监听表格的全局事件（如 @sort-change）统一处理。

2. 列显示/隐藏本地持久化

传入 local-cloumn-keys="unique_key"，用户勾选列后自动存入本地缓存，刷新页面后保留设置。

<xq-table local-cloumn-keys="user_table_columns" ... />

3. 文本溢出省略（u-line-1 ~ u-line-5）

组件内置了跨端多行省略样式类，直接在模板中使用：其实是抄的uview-pro开源项目的!!! 有兴趣的可以去看看这个不错的开源组件库text

<text class="u-line-2">
{{ longText }}
</text>

支持 1~5 行，nvue 与 vue 页面自动适配。

🎨 自定义全选样式覆盖

如需调整复选框颜色、尺寸，可覆盖以下 CSS 变量或直接修改 .checkbox-custom 样式：

.checkbox-custom {
  width: 32rpx;
  height: 32rpx;
  border: 2rpx solid #ccc;
  border-radius: 6rpx;

  &.checked,
  &.indeterminate {
    background-color: #007aff;
    border-color: #007aff;
  }
}

📱 平台兼容性

注意：在 nvue 页面中，文本省略请使用 u-line-1 ~ u-line-5 类，组件已做条件编译处理。

📦 依赖说明

本组件依赖以下 uni-ui 组件，已在 package.json 中声明，导入插件时 HBuilderX 会自动安装：

• uni-table
• uni-tr / uni-th / uni-td
• uni-icons
• uni-popup
• uni-tooltip

若未自动安装，请手动执行： 推荐直接去官网下载并安装：插件市场

npm install @dcloudio/uni-ui

📄 License

MIT

🤝 贡献与反馈

如果你在使用中遇到问题或有功能建议，欢迎在插件市场留言或提交 Issue。

文档版本：v1.0.0 最后更新：2026-04-22

这份文档涵盖了组件的所有关键功能和使用方式，你可以直接复制到项目 README.md 或插件市场描述中。

有些不懂得,可以去看看uni-table的文档 文档

插件市场地址：插件市场