# 组件 API

<cite>
**本文引用的文件**
- [packages/components/ProTable.vue](file://packages/components/ProTable.vue)
- [src/views/ProTable.vue](file://src/views/ProTable.vue)
- [types/ProTable.d.ts](file://types/ProTable.d.ts)
- [packages/components/ProForm.vue](file://packages/components/ProForm.vue)
- [src/views/ProForm.vue](file://src/views/ProForm.vue)
- [packages/components/ProSearch.vue](file://packages/components/ProSearch.vue)
- [src/views/ProSearch.vue](file://src/views/ProSearch.vue)
- [packages/components/ProSelect.vue](file://packages/components/ProSelect.vue)
- [src/views/ProSelect.vue](file://src/views/ProSelect.vue)
- [packages/components/ProCheckBox.vue](file://packages/components/ProCheckBox.vue)
- [src/views/ProCheckbox.vue](file://src/views/ProCheckbox.vue)
- [types/index.d.ts](file://types/index.d.ts)
- [types/components.d.ts](file://types/components.d.ts)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [组件详细 API 参考](#组件详细-api-参考)
6. [依赖关系分析](#依赖关系分析)
7. [性能与可用性建议](#性能与可用性建议)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录：常用配置速查](#附录常用配置速查)

## 简介
本文件为 Pro-IVIEW V3 的组件 API 参考，覆盖 ProTable、ProForm、ProSearch、ProSelect、ProCheckBox 等核心组件。内容包括：
- 属性（含类型、默认值、说明）
- 事件（触发时机、回调参数）
- 插槽（具名插槽与作用域插槽参数）
- 方法（调用方式、返回值）
- 组件间交互与依赖关系
- 使用示例（通过源码路径指引）

## 项目结构
- 组件实现位于 packages/components 下，示例位于 src/views 下，类型声明位于 types 下。
- ProTable 作为容器组件，内部组合 ProSearch、ProForm、工具栏、分页等模块；ProSelect/ProCheckBox 作为通用选择器被其他组件复用。

```mermaid
graph TB
subgraph "示例页面"
VPT["ProTable 示例<br/>src/views/ProTable.vue"]
VPF["ProForm 示例<br/>src/views/ProForm.vue"]
VPS["ProSearch 示例<br/>src/views/ProSearch.vue"]
VPC["ProSelect 示例<br/>src/views/ProSelect.vue"]
VCB["ProCheckBox 示例<br/>src/views/ProCheckbox.vue"]
end
subgraph "核心组件"
PT["ProTable<br/>packages/components/ProTable.vue"]
PF["ProForm<br/>packages/components/ProForm.vue"]
PS["ProSearch<br/>packages/components/ProSearch.vue"]
PSEL["ProSelect<br/>packages/components/ProSelect.vue"]
PCB["ProCheckBox<br/>packages/components/ProCheckBox.vue"]
end
VPT --> PT
VPF --> PF
VPS --> PS
VPC --> PSEL
VCB --> PCB
PT --> PS
PT --> PF
PF --> PSEL
PT --> PSEL
PT --> PCB
```

图表来源
- [packages/components/ProTable.vue:1-152](file://packages/components/ProTable.vue#L1-L152)
- [packages/components/ProForm.vue:1-144](file://packages/components/ProForm.vue#L1-L144)
- [packages/components/ProSearch.vue:1-112](file://packages/components/ProSearch.vue#L1-L112)
- [packages/components/ProSelect.vue:1-156](file://packages/components/ProSelect.vue#L1-L156)
- [packages/components/ProCheckBox.vue:1-144](file://packages/components/ProCheckBox.vue#L1-L144)
- [src/views/ProTable.vue:1-306](file://src/views/ProTable.vue#L1-L306)
- [src/views/ProForm.vue:1-198](file://src/views/ProForm.vue#L1-L198)
- [src/views/ProSearch.vue:1-59](file://src/views/ProSearch.vue#L1-L59)
- [src/views/ProSelect.vue:1-115](file://src/views/ProSelect.vue#L1-L115)
- [src/views/ProCheckbox.vue:1-48](file://src/views/ProCheckbox.vue#L1-L48)

章节来源
- [packages/components/ProTable.vue:1-152](file://packages/components/ProTable.vue#L1-L152)
- [packages/components/ProForm.vue:1-144](file://packages/components/ProForm.vue#L1-L144)
- [packages/components/ProSearch.vue:1-112](file://packages/components/ProSearch.vue#L1-L112)
- [packages/components/ProSelect.vue:1-156](file://packages/components/ProSelect.vue#L1-L156)
- [packages/components/ProCheckBox.vue:1-144](file://packages/components/ProCheckBox.vue#L1-L144)
- [src/views/ProTable.vue:1-306](file://src/views/ProTable.vue#L1-L306)
- [src/views/ProForm.vue:1-198](file://src/views/ProForm.vue#L1-L198)
- [src/views/ProSearch.vue:1-59](file://src/views/ProSearch.vue#L1-L59)
- [src/views/ProSelect.vue:1-115](file://src/views/ProSelect.vue#L1-L115)
- [src/views/ProCheckbox.vue:1-48](file://src/views/ProCheckbox.vue#L1-L48)

## 核心组件
- ProTable：表格容器，内置搜索、工具栏、表格、分页、弹窗表单，支持远程请求、列渲染、行操作、全屏等。
- ProForm：表单容器，支持栅格布局、分组、校验、远程提交、作用域输入包装。
- ProSearch：搜索表单，支持栅格布局、展开收起、自定义渲染、前置钩子。
- ProSelect：下拉选择器，支持本地/远程数据、模板化标题、首项自动选择。
- ProCheckBox：多选框组，支持本地/远程数据、模板化标题、首项自动选择。

章节来源
- [packages/components/ProTable.vue:154-428](file://packages/components/ProTable.vue#L154-L428)
- [packages/components/ProForm.vue:146-308](file://packages/components/ProForm.vue#L146-L308)
- [packages/components/ProSearch.vue:114-217](file://packages/components/ProSearch.vue#L114-L217)
- [packages/components/ProSelect.vue:6-119](file://packages/components/ProSelect.vue#L6-L119)
- [packages/components/ProCheckBox.vue:1-136](file://packages/components/ProCheckBox.vue#L1-L136)

## 架构总览
ProTable 作为中枢，协调搜索、表单、分页与工具栏；ProSelect/ProCheckBox 作为通用输入组件被复用。

```mermaid
graph TB
PT["ProTable"] --> PS["ProSearch"]
PT --> PF["ProForm"]
PT --> PG["Page"]
PT --> TB["Tool Bar Actions"]
PF --> PSEL["ProSelect"]
PT --> PSEL
PT --> PCB["ProCheckBox"]
```

图表来源
- [packages/components/ProTable.vue:1-152](file://packages/components/ProTable.vue#L1-L152)
- [packages/components/ProSearch.vue:1-112](file://packages/components/ProSearch.vue#L1-L112)
- [packages/components/ProForm.vue:1-144](file://packages/components/ProForm.vue#L1-L144)
- [packages/components/ProSelect.vue:1-156](file://packages/components/ProSelect.vue#L1-L156)
- [packages/components/ProCheckBox.vue:1-144](file://packages/components/ProCheckBox.vue#L1-L144)

## 组件详细 API 参考

### ProTable API
- 基本说明
  - 容器组件，负责请求数据、渲染表格、处理分页、弹窗表单、工具栏与搜索联动。
  - 支持 v-model 双向绑定数据，支持通过 $attrs 透传到内部组件（如 table/page/form/modal）。

- 属性
  - uiEdit: Boolean —— 是否启用可视化编辑模式
  - pageSize: Number —— 默认分页大小，默认 10
  - toolBarActions: Array —— 工具栏按钮集合，默认 ["new","refresh","fullscreen","rowSetting"]
  - attrs: Object —— 透传属性对象
  - title: String —— 表格标题
  - columns: Array —— 列配置数组（见“列配置”）
  - method: String —— 请求方法，默认 "GET"
  - headers: Object —— 请求头
  - request: String|Function|Object —— 请求配置或地址
  - autoFetch: Boolean —— 是否自动请求，默认 true
  - map: Object —— 数据映射，包含 current、pageSize、dataPath、totalPath、success/message 等
  - format: Object —— 页码格式化策略（支持函数或字符串表达式）
  - modelValue: Array —— 外部绑定的表格数据
  - hide: Object —— 控制区域显示，包含 search、table、pages、toolBar
  - submitForm: String|Function|Object —— 新建/编辑提交配置
  - storage: Object —— 存储键，如 rowSetting

- 事件
  - pageClick(e) —— 分页点击事件
  - uiConfig(options) —— 可视化配置变更
  - search(form, page, table) —— 搜索触发
  - searchReset(form, page, table) —— 搜索重置
  - formReset(form, page, table) —— 表单重置
  - fetchFinish(data) —— 请求完成（数据已注入）

- 插槽
  - header：工具栏区域插槽
  - title：自定义标题
  - tableTip：表格上方提示区
  - footer（来自 ProForm）：表单底部按钮区

- 方法
  - search(current?) —— 触发搜索并可指定页码
  - fetch(fn?, options?) —— 发起请求，返回 {msg,res}
  - fetchCurrent(current?) —— 设置当前页并请求
  - pageSizeChange(pageSize) —— 修改页大小并按需请求
  - setTotal(value)/getTotal() —— 设置/获取总数
  - getDatas() —— 获取当前上下文数据（search/table/page/form/attr/resData/dialog）
  - getSelection() —— 获取表格选中项
  - finish()/cancel() —— 关闭弹窗并刷新/重置
  - success(res)/error(res) —— 成功/失败消息提示
  - submitLoading() —— 表单提交加载动画
  - resetForm() —— 重置表单
  - uiConfig(options) —— 触发可视化配置

- 列配置（columns 子项常见字段）
  - title/key/width/minWidth/align/fixed/children
  - notShowSearch/notShowTable/notShowForm
  - renderSearch/renderForm/renderTable
  - formWidth/formLineNum/rule/rule[].trigger
  - actions: [{ type/title/request/action/prevent/show/render }]

- 类型声明（节选）
  - 参考 [types/ProTable.d.ts:1-59](file://types/ProTable.d.ts#L1-L59)

章节来源
- [packages/components/ProTable.vue:195-266](file://packages/components/ProTable.vue#L195-L266)
- [packages/components/ProTable.vue:271-422](file://packages/components/ProTable.vue#L271-L422)
- [packages/components/ProTable.vue:456-800](file://packages/components/ProTable.vue#L456-L800)
- [src/views/ProTable.vue:20-301](file://src/views/ProTable.vue#L20-L301)
- [types/ProTable.d.ts:1-59](file://types/ProTable.d.ts#L1-L59)

### ProForm API
- 基本说明
  - 表单容器，支持栅格布局、分组、标签位置/宽度、远程提交、单项/整体校验。

- 属性
  - uiEdit: Boolean —— 可视化编辑
  - submitForm: Object —— 提交配置（position/request/method/complete/...）
  - type: String —— 表单类型，默认 "edit"
  - labelWidth: Number —— 标签宽度，默认 110
  - formLineNum: Number —— 每行列数，默认 1
  - labelPosition: String —— 标签位置，默认 "left"
  - columns: Array —— 字段配置数组
  - modelValue: Object —— 表单数据

- 事件
  - uiChoose(item) —— 选择可视化配置项
  - uiConfig(item) —— 触发可视化配置
  - itemClick(item, type) —— 字段点击

- 方法
  - submit() —— 校验并提交
  - reset(fn?) —— 重置表单
  - validate(fn?) —— 整体校验
  - validateField(prop, fn?) —— 单字段校验
  - change(item, value) —— 内部双向更新
  - wapperInput(item, wrapperObj) —— 输入包装更新

- 插槽
  - footer：自定义底部按钮区（当 submitForm 且未 hide 时显示）

章节来源
- [packages/components/ProForm.vue:153-194](file://packages/components/ProForm.vue#L153-L194)
- [packages/components/ProForm.vue:207-303](file://packages/components/ProForm.vue#L207-L303)
- [src/views/ProForm.vue:15-194](file://src/views/ProForm.vue#L15-L194)

### ProSearch API
- 基本说明
  - 搜索表单，支持栅格布局、展开收起、自定义渲染、enter 快捷搜索、前置钩子。

- 属性
  - position: String —— 标签位置，默认 "left"
  - loading: Boolean —— 搜索/重置禁用态
  - columns: Array —— 字段配置（同 ProTable 列配置）
  - modelValue: Object —— 搜索表单数据
  - searchLableWidth: Number —— 标签宽度
  - searchLineNum: Number —— 每行列数，默认 3
  - upDown: Boolean —— 是否允许展开收起，默认 true

- 事件
  - search —— 触发搜索
  - reset —— 触发重置
  - update:modelValue —— 输入值变更

- 插槽
  - buttons：右侧按钮区

- 方法
  - upDownHandle() —— 切换展开/收起
  - search() —— 触发搜索（支持 beforeSearch 钩子）
  - reset() —— 触发重置（支持 beforeReset 钩子）

章节来源
- [packages/components/ProSearch.vue:119-151](file://packages/components/ProSearch.vue#L119-L151)
- [packages/components/ProSearch.vue:155-190](file://packages/components/ProSearch.vue#L155-L190)
- [src/views/ProSearch.vue:17-57](file://src/views/ProSearch.vue#L17-L57)

### ProSelect API
- 基本说明
  - 下拉选择器，支持本地 list 或远程 request，模板化标题，首项自动选择，多选/单选。

- 属性
  - request: String|Object —— 远程请求配置
  - method: String —— 请求方法，默认 "GET"
  - map: Object —— 数据映射 { dataPath,titlePath,valuePath }
  - first: Boolean —— 首项自动选择
  - list: Array —— 本地选项列表
  - modelValue: any —— 绑定值
  - valueType: String —— 值类型（如 "string"）
  - $attrs：透传到 Select 组件（如 multiple、filterable 等）

- 事件
  - update:modelValue —— 值变更
  - change —— 选中项变更（首项自动选择时也会触发）

- 方法
  - init() —— 初始化并拉取数据
  - getExpText(item) —— 渲染标题（支持模板表达式）
  - fetchList() —— 拉取列表（优先 list，否则 request）

- 计算属性
  - innerValue —— 内部值（多选/单选、字符串/数组、valuePath）

- watch
  - request/list —— 变化时重新初始化

章节来源
- [packages/components/ProSelect.vue:6-47](file://packages/components/ProSelect.vue#L6-L47)
- [packages/components/ProSelect.vue:48-119](file://packages/components/ProSelect.vue#L48-L119)
- [src/views/ProSelect.vue:13-111](file://src/views/ProSelect.vue#L13-L111)

### ProCheckBox API
- 基本说明
  - 多选框组，支持本地/远程数据、模板化标题、首项自动选择、字符串/数组值。

- 属性
  - request: String|Object —— 远程请求配置
  - multiple: Boolean —— 是否多选，默认 true
  - map: Object —— 数据映射 { dataPath,titlePath,valuePath }
  - first: Boolean —— 首项自动选择
  - list: Array —— 本地选项列表
  - modelValue: any —— 绑定值
  - valueType: String —— 值类型（如 "string"）
  - $attrs：透传到 CheckboxGroup/Checkbox

- 事件
  - update:modelValue —— 值变更
  - change —— 选中项变更

- 方法
  - init()/getExpText()/fetchList() —— 同 ProSelect
  - 内部 innerValue 计算与 watch 逻辑

章节来源
- [packages/components/ProCheckBox.vue:1-62](file://packages/components/ProCheckBox.vue#L1-L62)
- [packages/components/ProCheckBox.vue:63-136](file://packages/components/ProCheckBox.vue#L63-L136)
- [src/views/ProCheckbox.vue:8-43](file://src/views/ProCheckbox.vue#L8-L43)

## 依赖关系分析

```mermaid
classDiagram
class ProTable {
+props : columns, request, map, hide, submitForm, ...
+events : search, searchReset, fetchFinish, ...
+methods : search(), fetch(), getDatas(), ...
}
class ProSearch {
+props : columns, modelValue, searchLineNum, ...
+events : search, reset
}
class ProForm {
+props : columns, modelValue, submitForm, ...
+events : uiChoose, uiConfig
+methods : submit(), reset(), validate()
}
class ProSelect {
+props : request, map, first, list, ...
+events : update : modelValue, change
}
class ProCheckBox {
+props : request, map, first, list, ...
+events : update : modelValue, change
}
ProTable --> ProSearch : "使用"
ProTable --> ProForm : "使用"
ProForm --> ProSelect : "使用"
ProTable --> ProSelect : "使用"
ProTable --> ProCheckBox : "使用"
```

图表来源
- [packages/components/ProTable.vue:1-152](file://packages/components/ProTable.vue#L1-L152)
- [packages/components/ProSearch.vue:1-112](file://packages/components/ProSearch.vue#L1-L112)
- [packages/components/ProForm.vue:1-144](file://packages/components/ProForm.vue#L1-L144)
- [packages/components/ProSelect.vue:1-156](file://packages/components/ProSelect.vue#L1-L156)
- [packages/components/ProCheckBox.vue:1-144](file://packages/components/ProCheckBox.vue#L1-L144)

章节来源
- [packages/components/ProTable.vue:1-152](file://packages/components/ProTable.vue#L1-L152)
- [packages/components/ProSearch.vue:1-112](file://packages/components/ProSearch.vue#L1-L112)
- [packages/components/ProForm.vue:1-144](file://packages/components/ProForm.vue#L1-L144)
- [packages/components/ProSelect.vue:1-156](file://packages/components/ProSelect.vue#L1-L156)
- [packages/components/ProCheckBox.vue:1-144](file://packages/components/ProCheckBox.vue#L1-L144)

## 性能与可用性建议
- 请求与分页
  - 合理设置 map.current/pageSize/dataPath/totalPath，避免重复解析。
  - 使用 format.formatCurrent 将页码转换为后端期望格式，减少额外处理。
- 渲染优化
  - 对于复杂 renderTable/renderForm，尽量使用受控更新，避免不必要的整表重渲染。
  - 使用 v-show 控制搜索/工具栏显隐，减少 DOM 重建。
- 选择器
  - ProSelect/ProCheckBox 优先使用 list，减少网络请求；必要时开启 filterable 并注意大量数据时的虚拟滚动。
- 表单校验
  - 使用单项 validateField 减少校验抖动；避免在高频输入中进行昂贵的正则匹配。

## 故障排查指南
- 请求路径为空
  - 现象：控制台输出“请求路径为空”
  - 排查：确认 request 是否正确传入或通过 $attrs 透传
  - 参考：[packages/components/ProTable.vue:738-741](file://packages/components/ProTable.vue#L738-L741)
- 数据路径不匹配
  - 现象：表格为空，提示“请检查数据路径和分页配置”
  - 排查：核对 map.dataPath/map.totalPath 与后端返回一致
  - 参考：[packages/components/ProTable.vue:707-721](file://packages/components/ProTable.vue#L707-L721)
- 自定义搜索未生效
  - 现象：点击搜索无响应
  - 排查：确保 v-model 绑定的 form 与 ProSearch 的 modelValue 对齐，并监听 search/reset 事件
  - 参考：[src/views/ProTable.vue:293-301](file://src/views/ProTable.vue#L293-L301)
- 表单提交未触发
  - 现象：点击提交无响应
  - 排查：确认 submitForm.complete 回调是否正确执行；检查 ProForm 的 validate 结果
  - 参考：[packages/components/ProForm.vue:215-225](file://packages/components/ProForm.vue#L215-L225)
- 选择器首项未自动选中
  - 现象：首次打开无默认值
  - 排查：确认 first=true 且初始 modelValue 为空；检查 map.valuePath 正确性
  - 参考：[packages/components/ProSelect.vue:77-82](file://packages/components/ProSelect.vue#L77-L82)

章节来源
- [packages/components/ProTable.vue:665-741](file://packages/components/ProTable.vue#L665-L741)
- [src/views/ProTable.vue:293-301](file://src/views/ProTable.vue#L293-L301)
- [packages/components/ProForm.vue:215-225](file://packages/components/ProForm.vue#L215-L225)
- [packages/components/ProSelect.vue:77-82](file://packages/components/ProSelect.vue#L77-L82)

## 结论
Pro-IVIEW V3 的组件体系以 ProTable 为核心，围绕搜索、表单、分页与工具栏形成完整数据流闭环；ProSelect/ProCheckBox 作为通用输入组件贯穿各场景。通过合理的属性配置、事件监听与方法调用，可快速构建复杂的增删改查界面。建议在生产环境中关注请求路径、数据映射与渲染性能，并结合示例页面进行对照调试。

## 附录：常用配置速查
- ProTable
  - columns.renderSearch/renderForm/renderTable：支持函数或对象，对象包含 type/props/format/scopedSlots 等
  - map：{ current, pageSize, dataPath, totalPath, success, message }
  - submitForm：{ request, method, complete(res) }
- ProForm
  - columns[].rules：支持 trigger、pattern（字符串会转为正则）
  - submitForm：{ position, request, complete(res) }
- ProSearch
  - columns[].renderSearch：支持 DatePicker、Select 等组件及 format 包装
  - beforeSearch/beforeReset：可传入回调以拦截搜索/重置
- ProSelect/ProCheckBox
  - map：{ dataPath, titlePath, valuePath }
  - first：自动选择首项
  - multiple/valueType：控制多选与值类型