# TableColumnControl 表格列控制组件

一个**完全通用**的表格列控制组件，支持列的显示/隐藏控制和拖拽排序，配置会自动保存到 localStorage，并在页面重新加载时自动恢复。

## ✨ 功能特性

- ✅ **列的显示/隐藏控制**：用户可以自定义显示哪些列
- ✅ **列的拖拽排序**：用户可以自定义列的显示顺序
- ✅ **自动保存和恢复**：配置自动保存到 localStorage，基于路由自动生成存储 key
- ✅ **两种使用方式**：支持自动提取或手动配置
- ✅ **完全通用**：可以在任何页面使用，无需额外配置
- ✅ **固定列保护**：固定列（fixed）和始终显示的列（alwaysShow）自动不可隐藏

## 🚀 快速开始（3 步集成）

### 步骤 1: 引入组件

```vue
<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>();
</script>
```

### 步骤 2: 添加列设置按钮

```vue
<template>
	<right-toolbar>
		<TableColumnControl :table-ref="tableRef" trigger-circle>
			<template #trigger>
				<el-tooltip content="列设置" placement="top">
					<el-button circle style="margin-left: 0;">
						<el-icon><Menu /></el-icon>
					</el-button>
				</el-tooltip>
			</template>
		</TableColumnControl>
	</right-toolbar>

	<el-table ref="tableRef" :data="tableData">
		<el-table-column prop="name" label="姓名" />
		<el-table-column prop="age" label="年龄" />
		<el-table-column label="操作" fixed="right" />
	</el-table>
</template>
```

### 步骤 3: 完成！

就这么简单！组件会自动：

- ✅ 从表格中提取列配置
- ✅ 根据当前路由自动生成存储 key
- ✅ 保存和恢复用户的列设置

> 📖 更多使用方式请查看 [快速开始指南](./QUICK_START.md)

## 使用方法

### 基础用法

```vue
<template>
	<div>
		<!-- 表格列控制按钮 -->
		<TableColumnControl :columns="tableColumns" v-model="visibleColumns" @change="handleColumnChange" />

		<!-- 表格 -->
		<el-table :data="tableData">
			<el-table-column v-for="col in visibleTableColumns" :key="col.prop" :prop="col.prop" :label="col.label" :width="col.width" />
		</el-table>
	</div>
</template>

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

const tableColumns = [
	{ prop: 'name', label: '姓名', width: 120 },
	{ prop: 'age', label: '年龄', width: 80 },
	{ prop: 'email', label: '邮箱', width: 200 },
	{ prop: 'address', label: '地址', width: 300 },
];

const visibleColumns = ref<string[]>(['name', 'age', 'email', 'address']);

// 根据 visibleColumns 过滤出需要显示的列
const visibleTableColumns = computed(() => {
	return tableColumns.filter((col) => visibleColumns.value.includes(col.prop || col.label));
});

const handleColumnChange = (columns: string[]) => {
	console.log('显示的列:', columns);
};
</script>
```

### 使用 localStorage 持久化

```vue
<TableColumnControl :columns="tableColumns" v-model="visibleColumns" storage-key="my-table-columns" />
```

### 固定列（不可隐藏）

```vue
const tableColumns = [ { prop: 'name', label: '姓名', fixed: 'left' }, // 固定左侧，不可隐藏 { prop: 'age', label: '年龄' }, { prop: 'action', label:
'操作', fixed: 'right' } // 固定右侧，不可隐藏 ]
```

### 始终显示的列

```vue
const tableColumns = [ { prop: 'name', label: '姓名', alwaysShow: true }, // 始终显示，不可隐藏 { prop: 'age', label: '年龄' } ]
```

### 自定义触发按钮

```vue
<!-- 使用图标按钮 -->
<TableColumnControl :columns="tableColumns" v-model="visibleColumns" trigger-type="default" trigger-circle />

<!-- 使用文字按钮 -->
<TableColumnControl :columns="tableColumns" v-model="visibleColumns" trigger-text="列设置" trigger-type="primary" />

<!-- 使用链接按钮 -->
<TableColumnControl :columns="tableColumns" v-model="visibleColumns" trigger-link trigger-text="自定义列" />
```

## Props

| 参数          | 说明                                | 类型                                                                             | 默认值    |
| ------------- | ----------------------------------- | -------------------------------------------------------------------------------- | --------- |
| columns       | 表格列配置数组                      | Column[]                                                                         | 必填      |
| modelValue    | 当前显示的列的 prop 或 label 数组   | string[]                                                                         | -         |
| storageKey    | localStorage 存储的 key，用于持久化 | string                                                                           | -         |
| triggerType   | 触发按钮的类型                      | 'default' \| 'primary' \| 'success' \| 'warning' \| 'danger' \| 'info' \| 'text' | 'default' |
| triggerSize   | 触发按钮的大小                      | 'large' \| 'default' \| 'small'                                                  | 'default' |
| triggerCircle | 触发按钮是否为圆形                  | boolean                                                                          | false     |
| triggerText   | 触发按钮的文字                      | string                                                                           | ''        |
| triggerLink   | 触发按钮是否为链接样式              | boolean                                                                          | false     |

## Events

| 事件名            | 说明               | 回调参数            |
| ----------------- | ------------------ | ------------------- |
| update:modelValue | 显示的列变化时触发 | (columns: string[]) |
| change            | 显示的列变化时触发 | (columns: string[]) |

## Column 接口

```typescript
interface Column {
	prop?: string; // 列的 prop，用于标识列
	label: string; // 列的标签
	fixed?: boolean | 'left' | 'right'; // 固定列，不可隐藏
	alwaysShow?: boolean; // 始终显示的列，不可隐藏
	[key: string]: any; // 其他属性
}
```

## 插槽

| 插槽名  | 说明               |
| ------- | ------------------ |
| trigger | 自定义触发按钮内容 |
