# 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 | 自定义触发按钮内容 |

