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 函数（如果不再需要）