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