# API 参考文档

<cite>
**本文引用的文件**
- [README.md](file://README.md)
- [package.json](file://package.json)
- [ARCHITECTURE_SUMMARY.md](file://ARCHITECTURE_SUMMARY.md)
- [MIGRATION.md](file://MIGRATION.md)
- [types/index.d.ts](file://types/index.d.ts)
- [types/components.d.ts](file://types/components.d.ts)
- [types/ProTable.d.ts](file://types/ProTable.d.ts)
- [packages/core/src/index.js](file://packages/core/src/index.js)
- [packages/core/src/ui-adapter/types.ts](file://packages/core/src/ui-adapter/types.ts)
- [packages/core/src/ui-adapter/inject.ts](file://packages/core/src/ui-adapter/inject.ts)
- [packages/core/src/components/index.js](file://packages/core/src/components/index.js)
- [packages/core/src/components/ProTable.vue](file://packages/core/src/components/ProTable.vue)
- [packages/core/src/components/ProForm.vue](file://packages/core/src/components/ProForm.vue)
- [packages/core/src/components/ProSearch.vue](file://packages/core/src/components/ProSearch.vue)
- [packages/core/src/components/ProSelect.vue](file://packages/core/src/components/ProSelect.vue)
- [packages/core/src/components/ProCheckBox.vue](file://packages/core/src/components/ProCheckBox.vue)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [组件详细 API](#组件详细-api)
6. [依赖关系分析](#依赖关系分析)
7. [性能与可维护性](#性能与可维护性)
8. [故障排查](#故障排查)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本项目是一个基于 Vue 3 与 View UI Plus 的高级组件库，提供统一的 UI 适配器模式，支持在不同 UI 库（如 view-ui-plus、element-plus）之间无缝切换，并保持核心组件 API 的一致性。文档面向使用者与二次开发者，覆盖以下内容：
- 所有公共组件的属性、方法、事件与插槽
- TypeScript 类型定义说明
- 版本兼容性与迁移建议
- 最佳实践与常见问题排查

## 项目结构
项目采用 Monorepo 架构，核心包与适配器按模块拆分，便于独立构建与扩展。

```mermaid
graph TB
subgraph "核心包 @pro-iview/core"
CORE_INDEX["packages/core/src/index.js"]
UI_TYPES["packages/core/src/ui-adapter/types.ts"]
UI_INJECT["packages/core/src/ui-adapter/inject.ts"]
CMPS_INDEX["packages/core/src/components/index.js"]
PT["ProTable.vue"]
PF["ProForm.vue"]
PS["ProSearch.vue"]
PSEL["ProSelect.vue"]
PCB["ProCheckBox.vue"]
end
subgraph "适配器"
ADAPTER_VIEW["view-ui-plus 适配器"]
ADAPTER_ELEM["element-plus 适配器"]
end
subgraph "类型定义"
TYPES_IDX["types/index.d.ts"]
TYPES_COMP["types/components.d.ts"]
TYPES_PTABLE["types/ProTable.d.ts"]
end
CORE_INDEX --> CMPS_INDEX
CORE_INDEX --> UI_INJECT
CORE_INDEX --> UI_TYPES
CMPS_INDEX --> PT
CMPS_INDEX --> PF
CMPS_INDEX --> PS
CMPS_INDEX --> PSEL
CMPS_INDEX --> PCB
CORE_INDEX -. 使用 .-> ADAPTER_VIEW
CORE_INDEX -. 使用 .-> ADAPTER_ELEM
TYPES_IDX --> TYPES_COMP
TYPES_COMP --> TYPES_PTABLE
```

图表来源
- [packages/core/src/index.js:1-85](file://packages/core/src/index.js#L1-L85)
- [packages/core/src/ui-adapter/types.ts:1-60](file://packages/core/src/ui-adapter/types.ts#L1-L60)
- [packages/core/src/ui-adapter/inject.ts:1-43](file://packages/core/src/ui-adapter/inject.ts#L1-L43)
- [packages/core/src/components/index.js:1-23](file://packages/core/src/components/index.js#L1-L23)
- [types/index.d.ts:1-19](file://types/index.d.ts#L1-L19)
- [types/components.d.ts:1-2](file://types/components.d.ts#L1-L2)
- [types/ProTable.d.ts:1-59](file://types/ProTable.d.ts#L1-L59)

章节来源
- [README.md:1-18](file://README.md#L1-L18)
- [package.json:1-47](file://package.json#L1-L47)
- [ARCHITECTURE_SUMMARY.md:59-120](file://ARCHITECTURE_SUMMARY.md#L59-L120)

## 核心组件
- ProTable：高级表格组件，内置搜索、分页、弹窗表单、工具栏等能力
- ProForm：高级表单组件，支持栅格布局、分组标题、动态渲染
- ProSearch：高级搜索组件，支持折叠展开、快捷按钮、统一校验钩子
- ProSelect：远程/本地数据源的选择器，支持模板化标题与首项自动填充
- ProCheckBox：复选框组，支持远程/本地数据源与模板化标题
- ProModal、ProFooter：辅助布局组件（由核心包导出）

章节来源
- [MIGRATION.md:83-93](file://MIGRATION.md#L83-L93)
- [packages/core/src/components/index.js:1-23](file://packages/core/src/components/index.js#L1-L23)

## 架构总览
核心包通过 UI 适配器注入机制，将不同 UI 库的组件映射为统一接口，从而实现核心逻辑与 UI 库解耦。

```mermaid
sequenceDiagram
participant App as "应用"
participant Core as "ProCore 插件"
participant Adapter as "UI 适配器"
participant Comp as "核心组件"
App->>Core : "app.use(ProCore, { adapter })"
Core->>Adapter : "provideUIAdapter(adapter)"
Core->>Core : "遍历注册全局组件"
Comp->>Adapter : "useUIAdapter()"
Adapter-->>Comp : "返回 Form/Input/Button/Table 等组件"
```

图表来源
- [packages/core/src/index.js:13-57](file://packages/core/src/index.js#L13-L57)
- [packages/core/src/ui-adapter/inject.ts:15-34](file://packages/core/src/ui-adapter/inject.ts#L15-L34)

章节来源
- [ARCHITECTURE_SUMMARY.md:122-156](file://ARCHITECTURE_SUMMARY.md#L122-L156)
- [MIGRATION.md:11-18](file://MIGRATION.md#L11-L18)

## 组件详细 API

### ProTable API
- 组件名称：ProTable
- 功能：高级表格，支持搜索、分页、弹窗表单、工具栏、列设置、全屏等
- 使用场景：数据列表展示、条件筛选、分页查询、新增/编辑/查看弹窗

属性（Props）
- columns: 数组，表格列配置
- hide: 对象，控制隐藏区域
  - toolBar: 是否隐藏工具栏
  - search: 是否隐藏搜索区
  - page: 是否隐藏分页区
- map: 对象，远程数据映射
  - dataPath: 数据数组路径
  - totalPath: 总条数路径
- request: 字符串/函数/对象，列表数据请求配置
- submitForm: 字符串/函数/对象，新建/编辑提交接口配置
- search: 对象，ProSearch 配置透传
- form: 对象，ProForm 配置透传
- table: 对象，底层 Table 组件配置透传
- uiEdit: 布尔，是否启用可视化编辑模式
- pageSize: 数字，默认 10，分页大小

事件（Emits）
- search: 触发时机为点击“搜索”或回车时；回调参数为当前查询条件对象
- reset: 触发时机为点击“重置”时；无参数
- change: 当分页或每页数量变化时触发；回调参数为当前页码与页大小
- update:modelValue: 当表格数据更新时触发；回调参数为当前数据数组

插槽（Slots）
- header: 自定义头部区域，可放置标题与操作按钮
- title: 自定义标题内容
- tableTip: 表格上方提示信息
- footer: 自定义底部区域（与 ProForm 的 footer 插槽配合）

方法（Methods）
- 无公开方法（内部通过子组件组合与事件冒泡实现交互）

最佳实践
- 使用 request 与 map 统一后端数据格式，减少重复处理
- 将复杂搜索项放入 ProSearch，避免在 ProTable 内部写死逻辑
- 在 form/dialog 场景下，结合 ProForm 的 v-model 与 submitForm 提交

章节来源
- [types/ProTable.d.ts:1-59](file://types/ProTable.d.ts#L1-L59)
- [packages/core/src/components/ProTable.vue:195-200](file://packages/core/src/components/ProTable.vue#L195-L200)

### ProForm API
- 组件名称：ProForm
- 功能：高级表单，支持栅格布局、分组标题、动态渲染、校验规则、编辑/查看模式

属性（Props）
- uiEdit: 布尔，是否启用可视化编辑
- submitForm: 对象，控制底部按钮显示与对齐位置
- type: 字符串，默认 "edit"，支持 "edit"/"view"
- labelWidth: 数字，默认 110，标签宽度
- formLineNum: 数字，默认 1，一行显示的字段数
- labelPosition: 字符串，默认 "left"，支持 "left"/"top"
- modelValue: 对象，双向绑定的表单数据
- columns: 数组，字段配置（见下文）

事件（Emits）
- update:modelValue: 表单值变更时触发
- submit: 点击“确认”按钮时触发
- reset: 点击“重置”按钮时触发

插槽（Slots）
- footer: 自定义底部按钮区域

方法（Methods）
- 无公开方法（通过内部计算属性 useUIAdapter 获取 UI 组件）

字段配置（columns 子项）
- key: 字段标识
- title: 标题
- formWidth: 宽度（百分比或像素）
- disabled/readonly: 禁用/只读
- formLineNum: 占位列数
- renderForm: 自定义渲染函数
- icons.form: 表单标签前图标
- rules: 校验规则
- 其他：透传给底层 UI 组件

章节来源
- [packages/core/src/components/ProForm.vue:175-200](file://packages/core/src/components/ProForm.vue#L175-L200)

### ProSearch API
- 组件名称：ProSearch
- 功能：高级搜索，支持折叠展开、快捷按钮、统一校验钩子

属性（Props）
- position: 字符串，默认 "left"，标签位置
- loading: 布尔，默认 false，搜索按钮加载态
- columns: 数组，搜索字段配置
- modelValue: 对象，双向绑定的搜索条件
- searchLableWidth: 数字，标签宽度
- searchLineNum: 数字，默认 3，一行显示的字段数
- upDown: 布尔，默认 true，是否显示“展开/收起”

事件（Emits）
- search: 触发时机为点击“搜索”或回车；回调参数为当前查询条件
- reset: 触发时机为点击“重置”；无参数
- update:modelValue: 条件变更时触发

插槽（Slots）
- buttons: 自定义按钮区域（位于“重置/搜索”右侧）

方法（Methods）
- reset(): 重置搜索条件
- search(): 触发搜索（支持 beforeSearch 钩子）

章节来源
- [packages/core/src/components/ProSearch.vue:142-167](file://packages/core/src/components/ProSearch.vue#L142-L167)
- [packages/core/src/components/ProSearch.vue:171-200](file://packages/core/src/components/ProSearch.vue#L171-L200)

### ProSelect API
- 组件名称：ProSelect
- 功能：远程/本地数据源的选择器，支持模板化标题与首项自动填充

属性（Props）
- request: 请求配置（字符串/函数/对象），用于远程拉取数据
- method: 字符串，默认 "GET"，HTTP 方法
- map: 对象，数据映射
  - dataPath: 数据数组路径
  - titlePath: 标题路径（支持模板表达式）
  - valuePath: 值路径
- first: 布尔，默认 false，是否在空值时自动选择第一项
- list: 数组，本地数据源
- modelValue: 值（支持字符串/数组，取决于多选）
- valueType: 字符串，"string" 或其他，决定输出值类型

事件（Emits）
- update:modelValue: 值变更时触发
- change: 选中项变更时触发（携带完整选项对象）

方法（Methods）
- init(): 初始化并拉取数据
- fetchList(): 拉取列表数据
- getExpText(item): 渲染标题（支持模板）

章节来源
- [packages/core/src/components/ProSelect.vue:26-59](file://packages/core/src/components/ProSelect.vue#L26-L59)
- [packages/core/src/components/ProSelect.vue:60-100](file://packages/core/src/components/ProSelect.vue#L60-L100)

### ProCheckBox API
- 组件名称：ProCheckBox
- 功能：复选框组，支持远程/本地数据源与模板化标题

属性（Props）
- request: 请求配置（字符串/函数/对象），用于远程拉取数据
- multiple: 布尔，默认 true，是否多选
- map: 对象，数据映射
  - dataPath: 数据数组路径
  - titlePath: 标题路径（支持模板表达式）
  - valuePath: 值路径
- first: 布尔，默认 false，是否在空值时自动选择第一项
- list: 数组，本地数据源
- modelValue: 值（字符串/数组）
- valueType: 字符串，"string" 或其他，决定输出值类型

事件（Emits）
- update:modelValue: 值变更时触发
- change: 选中项变更时触发（携带完整选项对象）

方法（Methods）
- init(): 初始化并拉取数据
- fetchList(): 拉取列表数据
- getExpText(item): 渲染标题（支持模板）
- innerValue 计算属性：处理字符串与数组之间的转换

章节来源
- [packages/core/src/components/ProCheckBox.vue:32-62](file://packages/core/src/components/ProCheckBox.vue#L32-L62)
- [packages/core/src/components/ProCheckBox.vue:63-100](file://packages/core/src/components/ProCheckBox.vue#L63-L100)

### ProModal / ProFooter
- ProModal：高级弹窗组件（由核心包导出）
- ProFooter：页脚组件（由核心包导出）
- 使用方式：通过 app.use(ProCore) 注册后全局可用

章节来源
- [packages/core/src/components/index.js:7-19](file://packages/core/src/components/index.js#L7-L19)

## 依赖关系分析

```mermaid
classDiagram
class UIAdapter {
+Form
+FormItem
+Input
+Select
+Option
+Checkbox
+Button
+Table
+TableColumn
+Modal
+Message
+Icon
+Page
+install(app)
}
class ProForm {
+props : uiEdit, submitForm, type, labelWidth, formLineNum, labelPosition, modelValue, columns
+emits : update : modelValue, submit, reset
+slots : footer
}
class ProSearch {
+props : position, loading, columns, modelValue, searchLableWidth, searchLineNum, upDown
+emits : search, reset, update : modelValue
+slots : buttons
}
class ProSelect {
+props : request, method, map, first, list, modelValue, valueType
+emits : update : modelValue, change
}
class ProCheckBox {
+props : request, multiple, map, first, list, modelValue, valueType
+emits : update : modelValue, change
}
class ProTable {
+props : columns, hide, map, request, submitForm, search, form, table, uiEdit, pageSize
+emits : search, reset, change, update : modelValue
+slots : header, title, tableTip, footer
}
ProForm --> UIAdapter : "useUIAdapter()"
ProSearch --> UIAdapter : "useUIAdapter()"
ProSelect --> UIAdapter : "useUIAdapter()"
ProCheckBox --> UIAdapter : "useUIAdapter()"
ProTable --> UIAdapter : "useUIAdapter()"
```

图表来源
- [packages/core/src/ui-adapter/types.ts:9-48](file://packages/core/src/ui-adapter/types.ts#L9-L48)
- [packages/core/src/components/ProForm.vue:154-174](file://packages/core/src/components/ProForm.vue#L154-L174)
- [packages/core/src/components/ProSearch.vue:120-136](file://packages/core/src/components/ProSearch.vue#L120-L136)
- [packages/core/src/components/ProSelect.vue:7-19](file://packages/core/src/components/ProSelect.vue#L7-L19)
- [packages/core/src/components/ProCheckBox.vue:1-6](file://packages/core/src/components/ProCheckBox.vue#L1-L6)
- [packages/core/src/components/ProTable.vue:167-194](file://packages/core/src/components/ProTable.vue#L167-L194)

章节来源
- [packages/core/src/ui-adapter/types.ts:1-60](file://packages/core/src/ui-adapter/types.ts#L1-L60)
- [packages/core/src/components/index.js:1-23](file://packages/core/src/components/index.js#L1-L23)

## 性能与可维护性
- 适配器模式降低耦合：核心逻辑不依赖具体 UI 库，便于替换与扩展
- 按需注册：通过 app.use(ProCore) 注册全局组件，避免重复引入
- 统一消息反馈：UIAdapter.Message 提供统一的 info/success/warning/error/loading/destroy
- 样式抽象：核心组件使用 pro-* 类名，适配器负责映射到具体 UI 库的类名
- 类型安全：提供完整的 TypeScript 类型定义，建议在项目中开启严格模式

[本节为通用指导，无需列出章节来源]

## 故障排查
- 未安装 UI 适配器
  - 现象：抛出错误提示“UI Adapter not installed”
  - 处理：确保 app.use(ProCore, { adapter }) 正确传入适配器实例
- 适配器未调用 install
  - 现象：部分 UI 组件未生效或样式异常
  - 处理：在安装适配器时调用其 install(app)
- 请求数据格式不一致
  - 现象：ProTable/ProSelect/ProCheckBox 无法正确解析数据
  - 处理：通过 map.dataPath、map.totalPath、map.titlePath、map.valuePath 统一映射
- 搜索/分页未触发
  - 现象：点击“搜索”或切换分页无响应
  - 处理：确认 ProSearch 的 search 事件与 ProTable 的 request/submitForm 配置正确

章节来源
- [packages/core/src/ui-adapter/inject.ts:23-34](file://packages/core/src/ui-adapter/inject.ts#L23-L34)
- [packages/core/src/index.js:25-31](file://packages/core/src/index.js#L25-L31)

## 结论
Pro-IVIEW V3 通过 UI 适配器模式实现了核心组件与 UI 库的解耦，提供了统一的高级表单、搜索、表格与选择器组件。借助完善的 TypeScript 类型定义与清晰的 API 设计，开发者可以在不同 UI 库间自由切换，同时保持业务代码的一致性与可维护性。

[本节为总结性内容，无需列出章节来源]

## 附录

### 版本兼容与迁移
- 2.0.0 版本引入 Monorepo 架构与 UI 适配器模式，提供三种使用方式：
  - 新方式（推荐）：分别安装 @pro-iview/core 与对应适配器
  - 兼容方式（老项目）：安装 pro_iview_v3@2.0.0，保持原有 API 不变
  - 向后兼容包：自动集成 view-ui-plus 适配器
- 迁移要点
  - 从 v1.x 升级到 v2.x：可选择零改动升级或模块化升级
  - 图标与样式差异：不同 UI 库的图标使用方式与类名不同，适配器已做兼容处理
  - 构建与开发：使用 pnpm workspace + Turborepo 管理多包

章节来源
- [MIGRATION.md:156-189](file://MIGRATION.md#L156-L189)
- [MIGRATION.md:190-214](file://MIGRATION.md#L190-L214)
- [MIGRATION.md:119-139](file://MIGRATION.md#L119-L139)

### TypeScript 类型定义
- 全局安装函数 install(app, options?)：用于注册插件与全局属性
- 全局属性
  - $PROIVIEW: 包含 format/map 的全局配置对象
  - $dayjs/$http/$lodash：全局工具对象
- 组件类型
  - ProTable：详见 types/ProTable.d.ts
  - 组件导出：通过 types/components.d.ts 汇总导出

章节来源
- [types/index.d.ts:1-19](file://types/index.d.ts#L1-L19)
- [types/ProTable.d.ts:1-59](file://types/ProTable.d.ts#L1-L59)
- [types/components.d.ts:1-2](file://types/components.d.ts#L1-L2)

### 使用示例与最佳实践
- 使用 view-ui-plus
  - 安装：@pro-iview/core + @pro-iview/view-ui-plus + view-ui-plus
  - 注册：app.use(ViewUIPlus) + app.use(ProCore, { adapter: ViewUIAdapter })
- 使用 element-plus
  - 安装：@pro-iview/core + @pro-iview/element-plus + element-plus
  - 注册：app.use(ElementPlus) + app.use(ProCore, { adapter: ElementAdapter })
- 向后兼容
  - 安装：pro_iview_v3@2.0.0
  - 注册：app.use(ProIView)，保持原有 API 不变

章节来源
- [MIGRATION.md:22-82](file://MIGRATION.md#L22-L82)
- [ARCHITECTURE_SUMMARY.md:235-279](file://ARCHITECTURE_SUMMARY.md#L235-L279)