school-developer/src/components/TableColumnControl/USAGE.md

TableColumnControl 使用指南

两种使用方式

方式一：自动提取（推荐）✨

自动从 el-table 中提取列配置，无需手动配置。

<template>
	<div>
		<!-- 列设置按钮 -->
		<TableColumnControl
			:table-ref="tableRef"
			v-model="visibleTableColumns"
			storage-key="my-table-columns"
			trigger-text="列设置"
			:auto-extract-options="{
				alwaysShow: ['name', 'action'], // 始终显示的列（prop 或 label）
				defaultHidden: ['remark'], // 默认隐藏的列
			}"
		/>

		<!-- 表格 -->
		<el-table ref="tableRef" :data="tableData">
			<el-table-column prop="name" label="姓名" width="120" />
			<el-table-column prop="age" label="年龄" width="80" />
			<el-table-column prop="email" label="邮箱" width="200" />
			<el-table-column prop="remark" label="备注" width="300" />
			<el-table-column label="操作" width="150" fixed="right">
				<template #default="scope">
					<el-button @click="handleEdit(scope.row)">编辑</el-button>
				</template>
			</el-table-column>
		</el-table>
	</div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import TableColumnControl from '/@/components/TableColumnControl/index.vue'
import type { TableInstance } from 'element-plus'

const tableRef = ref<TableInstance>()
const visibleTableColumns = ref<string[]>([])
const tableData = ref([...])
</script>

优点：

• ✅ 无需手动配置列信息
• ✅ 自动同步表格列的变化
• ✅ 代码更简洁

方式二：手动配置

手动传入列配置，适合需要自定义列信息的场景。

<template>
	<div>
		<!-- 列设置按钮 -->
		<TableColumnControl :columns="tableColumnConfig" v-model="visibleTableColumns" storage-key="my-table-columns" trigger-text="列设置" />

		<!-- 表格 -->
		<el-table :data="tableData">
			<el-table-column v-if="isColumnVisible('name')" prop="name" label="姓名" width="120" />
			<el-table-column v-if="isColumnVisible('age')" prop="age" label="年龄" width="80" />
			<!-- ... 其他列 ... -->
		</el-table>
	</div>
</template>

<script setup lang="ts">
import { ref, computed } from 'vue'
import TableColumnControl from '/@/components/TableColumnControl/index.vue'

const tableColumnConfig = [
  { prop: 'name', label: '姓名', width: 120 },
  { prop: 'age', label: '年龄', width: 80 },
  { prop: 'email', label: '邮箱', width: 200 },
  { prop: 'action', label: '操作', width: 150, fixed: 'right', alwaysShow: true }
]

const visibleTableColumns = ref<string[]>([])
const tableData = ref([...])

// 判断列是否显示
const isColumnVisible = (propOrLabel: string) => {
  const column = tableColumnConfig.find(col => (col.prop || col.label) === propOrLabel)
  if (column && (column.fixed !== undefined || column.alwaysShow)) {
    return true
  }
  return visibleTableColumns.value.includes(propOrLabel)
}
</script>

自动提取的配置选项

interface AutoExtractOptions {
	// 默认隐藏的列（prop 或 label）
	defaultHidden?: string[];

	// 始终显示的列（prop 或 label）
	alwaysShow?: string[];

	// 列配置映射（用于自定义列的显示名称等）
	columnMap?: Record<string, Partial<ColumnConfig>>;
}

示例

<TableColumnControl
	:table-ref="tableRef"
	v-model="visibleTableColumns"
	storage-key="my-table-columns"
	:auto-extract-options="{
		// 默认隐藏备注列
		defaultHidden: ['remark', 'description'],

		// 始终显示姓名和操作列
		alwaysShow: ['name', 'action'],

		// 自定义列的显示名称
		columnMap: {
			email: { label: '电子邮箱' },
			phone: { label: '联系电话' },
		},
	}"
/>

注意事项

1. 自动提取的限制：

   • 需要在表格渲染完成后才能提取列配置
   • 如果表格列是动态生成的，可能需要调用 refreshColumns() 方法

2. 固定列：

   • 使用 fixed="left" 或 fixed="right" 的列会自动标记为不可隐藏
   • 在 alwaysShow 中指定的列也会不可隐藏

3. 存储键（storageKey）：

   • 建议为每个页面使用唯一的 storageKey，避免列配置冲突
   • 格式建议：页面名称-table-columns，如 user-list-table-columns

4. 性能考虑：

   • 自动提取会在组件挂载和表格更新时执行
   • 对于大型表格，建议使用手动配置以获得更好的性能

迁移指南

从手动配置迁移到自动提取：

之前（手动配置）：

<TableColumnControl :columns="tableColumnConfig" v-model="visibleTableColumns" storage-key="my-table-columns" />

之后（自动提取）：

<TableColumnControl :table-ref="tableRef" v-model="visibleTableColumns" storage-key="my-table-columns" />

只需要：

1. 将 :columns 改为 :table-ref="tableRef"
2. 在 el-table 上添加 ref="tableRef"
3. 移除 tableColumnConfig 和 isColumnVisible 函数（如果不再需要）