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

