用户在工具栏中调整了列的显示隐藏、顺序、宽度、冻结状态后，刷新页面往往全部丢失。vxe-table 的自定义列（customConfig）支持把用户的个性化设置持久化到 IndexedDB 或 localStorage，刷新后自动恢复。本文说明启用方式、必填前提，以及 customConfig 与全局 storeOptions 的关系。
vxe-table 如何把用户自定义列设置保存到本地？
为表格设置全局唯一的 id，开启 toolbarConfig.custom: true 启用工具栏自定义按钮，并在 customConfig 中设置 storage: true 与 storeDriver: ‘indexedDB’（或 ‘localStorage’）。用户调整列后，设置自动写入本地；刷新页面时按同一个 id 读取并恢复。
- 生效前提：
- 表格 id 必须全局唯一。个性化记忆以 id 为键存储，重复 id 会导致多个表格互相覆盖配置。
- 每一列必须设置唯一的 field。包括 type: ‘seq’、type: ‘checkbox’ 等非数据列，以及分组列头的父级列，都需要一个唯一标识字段，否则该列的个性化状态无法被正确记录和恢复。
- toolbarConfig.custom: true 必须开启，用户才有入口触发自定义列操作。
- columnConfig.drag 与 columnConfig.resizable 建议同时开启，否则用户无法拖拽排序、调整列宽，可保存的内容会受限。
- 预期结果：用户通过工具栏调整列顺序、显隐、宽度、冻结后，刷新页面，表格列状态与上次一致；不同 id 的表格互不影响。
代码
下面的配置用于开启自定义列本地存储，存储方式为 IndexedDB：
<template>
<div>
<vxe-grid v-bind="gridOptions"></vxe-grid>
</div>
</template>
<script setup>
import { reactive } from 'vue'
const gridOptions = reactive({
border: true,
id: 'myCustomStorage1',
rowConfig: {
keyField: 'id'
},
toolbarConfig: {
custom: true
},
customConfig: {
storage: true,
storeDriver: 'indexedDB',
mode: 'default',
showSortPutButton: true
},
columnConfig: {
drag: true,
resizable: true
},
columns: [
{ field: 'seq', type: 'seq', width: 90 },
{ field: 'name', title: 'Name' },
{ field: 'role', title: 'role' },
{ field: 'sex', title: 'Sex' },
{ field: 'age', title: 'Age' },
{ field: 'address', title: 'address' }
],
data: [
{ id: 10001, name: 'Test1', role: 'Develop', sex: 'Man', age: 28, address: 'test abc' },
{ id: 10002, name: 'Test2', role: 'Test', sex: 'Women', age: 22, address: 'Guangzhou' },
{ id: 10003, name: 'Test3', role: 'PM', sex: 'Man', age: 32, address: 'Shanghai' },
{ id: 10004, name: 'Test4', role: 'Designer', sex: 'Women', age: 24, address: 'Shanghai' }
]
})
</script>
预期结果：打开工具栏的“自定义列”，调整列的显示、顺序、宽度、冻结状态，刷新页面后表格列状态与调整后一致。
全局配置方式
除了在单个表格的 customConfig 中配置，也可以通过 VxeUI.setConfig 全局指定默认存储方式：
import { VxeUI } from 'vxe-table'
VxeUI.setConfig({
grid: {
customConfig: {
storeDriver: 'localStorage' // 全局默认使用 localStorage
}
}
})
- 全局配置作为默认值，单表格 customConfig 中的配置优先级更高，可覆盖全局设置。
- 适合整个项目统一存储策略，避免每个表格重复写 storeDriver。
IndexedDB 与 localStorage 如何选择？
| 存储方式 | 容量 | 读写性能 | 适用场景 |
|---|---|---|---|
| localStorage | 约 5MB | 同步读写，简单直接 | 表格数量少、配置简单、需要快速读取 |
| indexedDB | 数百 MB 以上 | 异步读写，容量大 | 表格数量多、配置项复杂、或需要存储较大结构 |
- 默认推荐 indexedDB，容量更大，不会因表格数量多而触及 localStorage 上限。
- 若项目对兼容性或调试便利性有要求，localStorage 更直观，可直接在浏览器开发者工具中查看键值。
storeOptions 支持保存哪些配置？
customConfig 的本地存储能力覆盖以下个性化项：
| 可保存项 | 说明 |
|---|---|
| 列宽 | 用户拖拽调整后的列宽 |
| 列排序 | 用户拖拽调整后的列顺序 |
| 冻结列 | 用户设置的左冻结 / 右冻结 |
| 显示隐藏 | 用户勾选或取消勾选的列 |
| 聚合分组 | 分组列头的展开 / 收起与分组结构 |
| 聚合函数 | 表尾聚合相关配置 |
这些项只有在对应功能已启用时才会被记录。例如未开启 columnConfig.resizable，列宽调整不会被保存；未配置聚合相关能力，聚合项也无内容可存。
关键配置参数
| 配置项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| id | String | — | 表格唯一标识，个性化记忆的存储键，必须全局唯一 |
| toolbarConfig.custom | Boolean | false | 是否显示工具栏中的自定义列按钮 |
| customConfig.storage | Boolean | false | 是否启用本地存储，开启后个性化设置才会持久化 |
| customConfig.storeDriver | String | ‘localStorage’ | 存储方式，可选 ‘indexedDB’ / ‘localStorage’ |
| customConfig.mode | String | ‘default’ | 自定义列面板模式 |
| customConfig.showSortPutButton | Boolean | false | 是否显示置顶 / 置底排序按钮 |
| columnConfig.drag | Boolean | false | 是否允许拖拽调整列顺序 |
| columnConfig.resizable | Boolean | false | 是否允许拖拽调整列宽 |
注意事项
- id 与 field 的唯一性是成败关键
- 个性化记忆以表格 id 为存储键，以列 field 为列标识。id 重复会让多个表格共享同一份配置；field 重复或缺失会导致某些列的设置无法恢复或错位。分组列头的父级列也需要一个唯一 field，不能只给叶子列设置。
- 非数据列同样需要 field
- type: ‘seq’、type: ‘checkbox’ 等列没有业务字段，但用于个性化记忆时仍需指定唯一 field。示例中 seq 列已显式设置 field: ‘seq’。
- storage: true 是总开关
- 仅设置 storeDriver 而不开启 storage，配置不会持久化。两者需同时配置。
- 刷新后恢复依赖同一 id
- 若页面重构时修改了表格 id，用户之前的个性化设置将无法被读取，表现为“设置丢失”。发布前应确认 id 稳定不变。
- 多标签页与多用户场景
- 本地存储按浏览器与域隔离。同一浏览器不同用户、不同设备之间不会同步。若需要跨设备同步，需将个性化配置提交到后端，而非仅依赖本地存储。
- 清理策略
- 用户调整列后旧配置会保留在 IndexedDB / localStorage 中。若业务允许“恢复默认列”，需在代码中清除对应 id 的存储记录，或提供重置按钮调用相关 API。
转载自 CSDN-专业IT技术社区
原文链接：https://blog.csdn.net/honkun6/article/details/169365875
