a

2026-01-06 16:39:57 +08:00
parent 7f91263205
commit 9e583c3c30
32 changed files with 2830 additions and 481 deletions
--- a/src/components/TableColumnControl/USAGE.md
+++ b/src/components/TableColumnControl/USAGE.md
@@ -0,0 +1,196 @@
+# TableColumnControl 使用指南
+
+## 两种使用方式
+
+### 方式一：自动提取（推荐）✨
+
+自动从 `el-table` 中提取列配置，无需手动配置。
+
+```vue
+<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>
+```
+
+**优点：**
+- ✅ 无需手动配置列信息
+- ✅ 自动同步表格列的变化
+- ✅ 代码更简洁
+
+### 方式二：手动配置
+
+手动传入列配置，适合需要自定义列信息的场景。
+
+```vue
+<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>
+```
+
+## 自动提取的配置选项
+
+```typescript
+interface AutoExtractOptions {
+  // 默认隐藏的列（prop 或 label）
+  defaultHidden?: string[]
+  
+  // 始终显示的列（prop 或 label）
+  alwaysShow?: string[]
+  
+  // 列配置映射（用于自定义列的显示名称等）
+  columnMap?: Record<string, Partial<ColumnConfig>>
+}
+```
+
+### 示例
+
+```vue
+<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. **性能考虑**：
+   - 自动提取会在组件挂载和表格更新时执行
+   - 对于大型表格，建议使用手动配置以获得更好的性能
+
+## 迁移指南
+
+从手动配置迁移到自动提取：
+
+**之前（手动配置）：**
+```vue
+<TableColumnControl
+  :columns="tableColumnConfig"
+  v-model="visibleTableColumns"
+  storage-key="my-table-columns"
+/>
+```
+
+**之后（自动提取）：**
+```vue
+<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` 函数（如果不再需要）
+