# 列配置

<cite>
**本文引用的文件**
- [ProTable.vue](file://packages/components/ProTable.vue)
- [RowSetting.vue](file://packages/components/ProTable/RowSetting.vue)
- [ProTypeItem.vue](file://packages/components/ProTypeItem/ProTypeItem.vue)
- [ProTable.d.ts](file://types/ProTable.d.ts)
- [ProTable.vue](file://src/views/ProTable.vue)
- [TableRender.vue](file://src/views/TableRender.vue)
- [ProSearch.vue](file://packages/core/src/components/ProSearch.vue)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考量](#性能考量)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录：列配置示例与场景](#附录列配置示例与场景)

## 简介
本章节系统梳理 ProTable 的“列配置”能力，覆盖列定义语法、列类型与渲染、列宽与对齐、显示控制（如 show、notShowTable、notShowSearch 等）、以及行设置（列显隐与顺序）等关键主题。文档以代码为依据，配合可视化图示帮助读者快速理解与落地应用。

## 项目结构
围绕列配置的相关模块主要分布在以下位置：
- 组件层：ProTable 主组件、行设置弹窗 RowSetting、通用渲染器 ProTypeItem
- 视图示例：演示列配置与渲染的示例页面
- 类型声明：ProTable 的对外类型定义

```mermaid
graph TB
subgraph "组件层"
PT["ProTable.vue"]
RS["RowSetting.vue"]
PTI["ProTypeItem.vue"]
PS["ProSearch.vue"]
end
subgraph "视图示例"
VPT["src/views/ProTable.vue"]
TR["src/views/TableRender.vue"]
end
subgraph "类型定义"
TPT["types/ProTable.d.ts"]
end
VPT --> PT
TR --> PT
PT --> RS
PT --> PTI
PT --> PS
TPT --> PT
```

图表来源
- [ProTable.vue](file://packages/components/ProTable.vue)
- [RowSetting.vue](file://packages/components/ProTable/RowSetting.vue)
- [ProTypeItem.vue](file://packages/components/ProTypeItem/ProTypeItem.vue)
- [ProSearch.vue](file://packages/core/src/components/ProSearch.vue)
- [ProTable.d.ts](file://types/ProTable.d.ts)
- [ProTable.vue](file://src/views/ProTable.vue)
- [TableRender.vue](file://src/views/TableRender.vue)

章节来源
- [ProTable.vue](file://packages/components/ProTable.vue)
- [ProTable.d.ts](file://types/ProTable.d.ts)

## 核心组件
- ProTable：负责表格整体生命周期、列过滤与渲染、工具栏动作、分页与搜索联动、表单对话框等
- RowSetting：提供列显隐与拖拽排序的交互，支持本地持久化
- ProTypeItem：统一渲染列的渲染项（renderTable/renderSearch/renderForm），支持组件式与函数式两种写法
- ProSearch：基于列配置生成搜索表单，支持折叠/展开、行数控制等

章节来源
- [ProTable.vue](file://packages/components/ProTable.vue)
- [RowSetting.vue](file://packages/components/ProTable/RowSetting.vue)
- [ProTypeItem.vue](file://packages/components/ProTypeItem/ProTypeItem.vue)
- [ProSearch.vue](file://packages/core/src/components/ProSearch.vue)

## 架构总览
ProTable 的列配置通过“列定义 + 渲染器 + 过滤器”的组合实现：
- 列定义：columns 数组中的每个元素描述一列的标题、宽度、对齐、渲染方式、显示控制等
- 渲染器：renderTable/renderSearch/renderForm 将列映射到具体 UI 组件或函数
- 过滤器：columnFilter 基于 notShow* 属性筛选列，确保仅展示允许显示的列
- 行设置：RowSetting 提供勾选显隐、拖拽排序、重置等功能，并可持久化到 localStorage

```mermaid
sequenceDiagram
participant U as "用户"
participant PT as "ProTable"
participant RS as "RowSetting"
participant TF as "columnFilter"
participant TBL as "Table"
U->>PT : 打开行设置
PT->>RS : 传入当前列集合
U->>RS : 勾选/取消列、拖拽排序
RS-->>PT : 回传排序后的列集合
PT->>TF : 使用 notShowTable 过滤列
TF-->>PT : 返回可渲染列
PT->>TBL : 渲染表格列
```

图表来源
- [ProTable.vue](file://packages/components/ProTable.vue)
- [RowSetting.vue](file://packages/components/ProTable/RowSetting.vue)

## 详细组件分析

### 列定义语法与字段语义
- 基本字段
  - title：列标题
  - key：列键，用于数据映射与规则匹配
  - width/minWidth：列宽与最小宽度
  - align：单元格对齐（如 left/center/right）
  - fixed：固定列（left/right）
  - resizable：是否可调整宽度
  - tooltip/tooltipMaxWidth/tooltipTheme：单元格提示相关
  - formWidth/formLineNum/icons/form：表单相关配置
  - actions：操作列的动作集合
  - children：子列（用于表头分组）
- 显示控制
  - notShowTable：是否在表格列中显示
  - notShowSearch：是否在搜索列中显示
  - notShowForm：是否在表单列中显示
  - notShowRowSetting：是否在行设置中显示该列（用于控制行设置勾选项）
- 渲染相关
  - render：通用渲染（当未指定 renderTable 时生效）
  - renderTable：表格单元格渲染
  - renderSearch：搜索表单项渲染
  - renderForm：表单编辑渲染
  - rules：校验规则（支持数组型日期范围等复杂规则）

章节来源
- [ProTable.vue](file://packages/components/ProTable.vue)
- [ProTable.vue](file://src/views/ProTable.vue)
- [TableRender.vue](file://src/views/TableRender.vue)

### 列宽与对齐
- 宽度
  - width：固定宽度
  - minWidth：最小宽度（在响应式布局中更稳健）
  - resizable：开启后可通过拖拽调整宽度
- 对齐
  - align：支持 left/center/right；表格头部默认居中

章节来源
- [ProTable.vue](file://packages/components/ProTable.vue)
- [ProTable.vue](file://src/views/ProTable.vue)

### 显示控制：show 与 notShow*
- notShowTable：控制表格列是否显示
- notShowSearch：控制搜索列是否显示
- notShowForm：控制表单列是否显示
- notShowRowSetting：控制行设置勾选项是否出现
- 行设置交互
  - RowSetting 支持全选/反选、逐项勾选、拖拽排序、重置
  - 变更会通过事件回传到 ProTable，ProTable 再调用 columnFilter 过滤列

```mermaid
flowchart TD
Start(["进入行设置"]) --> Load["加载初始列集合"]
Load --> Toggle{"勾选/取消某列?"}
Toggle --> |是| UpdateNotShow["更新 notShowTable"]
Toggle --> |否| Drag{"拖拽排序?"}
UpdateNotShow --> Emit["发出 input/change 事件"]
Drag --> Emit
Emit --> Filter["ProTable.columnFilter 过滤列"]
Filter --> Render["渲染表格列"]
Render --> End(["完成"])
```

图表来源
- [RowSetting.vue](file://packages/components/ProTable/RowSetting.vue)
- [ProTable.vue](file://packages/components/ProTable.vue)

章节来源
- [RowSetting.vue](file://packages/components/ProTable/RowSetting.vue)
- [ProTable.vue](file://packages/components/ProTable.vue)

### 渲染方式：renderTable / renderSearch / renderForm
- renderTable：表格单元格渲染
  - 支持对象式（type/props/scopedSlots/style/format 等）与函数式两种写法
  - 当未显式提供 renderTable 且存在 children 或有对应渲染项时，会自动注入 render
- renderSearch：搜索表单项渲染
  - 常用于日期范围、下拉选择等复杂搜索控件
  - 支持 format 与 formatWapper，便于将控件值转换为后端期望格式
- renderForm：表单编辑渲染
  - 与 ProForm 协作，支持开关、日期选择等

```mermaid
sequenceDiagram
participant PT as "ProTable"
participant PTI as "ProTypeItem"
participant UI as "UI组件"
PT->>PTI : 传入 renderItem对象式/函数式
alt 对象式
PTI->>UI : 解析 type/props/scopedSlots/style
UI-->>PTI : 渲染结果
else 函数式
PTI->>PTI : 调用函数式 renderItem
PTI-->>UI : 返回 VNode
end
PTI-->>PT : 返回渲染结果
```

图表来源
- [ProTable.vue](file://packages/components/ProTable.vue)
- [ProTypeItem.vue](file://packages/components/ProTypeItem/ProTypeItem.vue)

章节来源
- [ProTable.vue](file://packages/components/ProTable.vue)
- [ProTypeItem.vue](file://packages/components/ProTypeItem/ProTypeItem.vue)
- [ProTable.vue](file://src/views/ProTable.vue)
- [TableRender.vue](file://src/views/TableRender.vue)

### 行设置：列显隐与顺序调整
- 显隐控制
  - 勾选/取消勾选会切换 notShowTable
  - 全选/反选由 RowSetting 内部逻辑维护
- 顺序调整
  - 通过拖拽对列进行排序，内部通过排序算法将原始列集合按当前顺序重排
- 持久化
  - 可通过 storage 参数将用户偏好保存至 localStorage，下次进入自动恢复

章节来源
- [RowSetting.vue](file://packages/components/ProTable/RowSetting.vue)
- [ProTable.vue](file://packages/components/ProTable.vue)

### 搜索与列过滤
- ProSearch 基于列配置生成搜索表单
- ProTable 在计算属性中使用 columnFilter 过滤搜索列（基于 notShowSearch）
- 搜索触发后，ProTable 重新请求数据并渲染表格

章节来源
- [ProSearch.vue](file://packages/core/src/components/ProSearch.vue)
- [ProTable.vue](file://packages/components/ProTable.vue)

## 依赖关系分析
- ProTable 依赖 RowSetting 实现行设置，依赖 ProTypeItem 实现统一渲染，依赖 ProSearch 生成搜索表单
- ProTypeItem 支持 HTML 标签与 Vue 组件两种渲染模式，兼容表达式与插槽
- RowSetting 通过 localStorage 持久化用户偏好，避免每次进入都回到默认状态

```mermaid
graph LR
PT["ProTable"] --> RS["RowSetting"]
PT --> PTI["ProTypeItem"]
PT --> PS["ProSearch"]
PTI --> UI["UI组件库"]
```

图表来源
- [ProTable.vue](file://packages/components/ProTable.vue)
- [RowSetting.vue](file://packages/components/ProTable/RowSetting.vue)
- [ProTypeItem.vue](file://packages/components/ProTypeItem/ProTypeItem.vue)
- [ProSearch.vue](file://packages/core/src/components/ProSearch.vue)

章节来源
- [ProTable.vue](file://packages/components/ProTable.vue)
- [ProTypeItem.vue](file://packages/components/ProTypeItem/ProTypeItem.vue)
- [ProSearch.vue](file://packages/core/src/components/ProSearch.vue)

## 性能考量
- 列过滤与渲染
  - columnFilter 会对列集合进行深拷贝与遍历，建议控制列数量与嵌套层级
  - children 子列在渲染时会递归处理，避免过深的树形结构
- 渲染器
  - 对象式 renderItem 会在每次渲染时解析表达式与插槽，建议减少复杂表达式
  - 函数式 renderItem 更灵活但需注意闭包与重复渲染
- 行设置
  - 拖拽排序与 localStorage 写入在变更时触发，频繁操作可能带来抖动，建议节流或合并更新

## 故障排查指南
- 列不显示
  - 检查 notShowTable/notShowSearch/notShowForm 是否被设置为 true
  - 确认列是否包含 renderTable/renderSearch/renderForm 或 children
- 搜索无响应
  - 检查 searchColumns 的过滤逻辑是否正确（基于 notShowSearch）
  - 确认请求参数与 map 配置是否匹配后端接口
- 行设置无效
  - 确认 storage 是否正确传入，localStorage 是否可用
  - 检查 notShowRowSetting 是否导致该列未出现在行设置列表中
- 渲染异常
  - 对象式 renderItem 的 type 是否为有效组件或 HTML 标签
  - 函数式 renderItem 是否正确绑定 v-model 或 onUpdate:modelValue

章节来源
- [ProTable.vue](file://packages/components/ProTable.vue)
- [RowSetting.vue](file://packages/components/ProTable/RowSetting.vue)
- [ProTypeItem.vue](file://packages/components/ProTypeItem/ProTypeItem.vue)

## 结论
ProTable 的列配置以“列定义 + 渲染器 + 过滤器 + 行设置”为核心，提供了灵活的列显隐、宽度与对齐、复杂渲染与搜索联动能力。通过 RowSetting 的本地持久化与拖拽排序，用户可按需定制表格列集，提升使用体验。建议在复杂场景下合理拆分列、简化渲染表达式，并关注性能与可维护性。

## 附录：列配置示例与场景
- 基础列
  - 设置标题、key、宽度、对齐、固定列等
  - 示例参考：[ProTable.vue](file://src/views/ProTable.vue)
- 自定义渲染
  - 使用 renderTable/renderSearch/renderForm 定制单元格/搜索/表单
  - 示例参考：[TableRender.vue](file://src/views/TableRender.vue)
- 复杂搜索
  - 使用 renderSearch 配合 format/formatWapper 实现日期范围等复杂输入
  - 示例参考：[ProTable.vue](file://src/views/ProTable.vue)
- 行设置
  - 通过 RowSetting 控制列显隐与顺序，支持重置与持久化
  - 示例参考：[ProTable.vue](file://packages/components/ProTable.vue)
- 类型与规则
  - rules 支持必填、数组型日期范围等复杂校验
  - 示例参考：[ProTable.vue](file://src/views/ProTable.vue)

章节来源
- [ProTable.vue](file://src/views/ProTable.vue)
- [TableRender.vue](file://src/views/TableRender.vue)
- [ProTable.vue](file://packages/components/ProTable.vue)