# 基础使用示例

<cite>
**本文引用的文件**
- [README.md](file://README.md)
- [package.json](file://package.json)
- [src/main.js](file://src/main.js)
- [packages/index.js](file://packages/index.js)
- [packages/components/index.js](file://packages/components/index.js)
- [types/index.d.ts](file://types/index.d.ts)
- [types/ProTable.d.ts](file://types/ProTable.d.ts)
- [src/views/ProTable.vue](file://src/views/ProTable.vue)
- [src/views/ProForm.vue](file://src/views/ProForm.vue)
- [src/views/Home.vue](file://src/views/Home.vue)
- [src/views/ProSearch.vue](file://src/views/ProSearch.vue)
- [src/views/ProSelect.vue](file://src/views/ProSelect.vue)
- [src/views/EditTable.vue](file://src/views/EditTable.vue)
</cite>

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

## 简介
本示例文档面向希望在 Vue 3 + View UI Plus 项目中快速上手 Pro-IVIEW V3 的开发者，重点覆盖 ProTable、ProForm 等核心组件的基础使用方法：包括安装与初始化、最简配置、基础属性设置、典型使用场景与最佳实践，并提供可直接复制使用的代码片段路径与配置模板。同时给出常见问题与调试技巧，帮助你快速落地。

## 项目结构
该仓库采用多包工作区组织方式，核心组件位于 packages/components 下，示例页面位于 src/views 中；应用入口在 src/main.js 中完成插件安装与挂载。

```mermaid
graph TB
A["应用入口<br/>src/main.js"] --> B["组件库安装器<br/>packages/index.js"]
B --> C["组件清单导出<br/>packages/components/index.js"]
A --> D["视图示例ProTable<br/>src/views/ProTable.vue"]
A --> E["视图示例ProForm<br/>src/views/ProForm.vue"]
A --> F["视图示例Home<br/>src/views/Home.vue"]
A --> G["视图示例ProSearch<br/>src/views/ProSearch.vue"]
A --> H["视图示例ProSelect<br/>src/views/ProSelect.vue"]
A --> I["视图示例EditTable<br/>src/views/EditTable.vue"]
```

**图表来源**
- [src/main.js:1-14](file://src/main.js#L1-L14)
- [packages/index.js:1-69](file://packages/index.js#L1-L69)
- [packages/components/index.js:1-23](file://packages/components/index.js#L1-L23)

**章节来源**
- [README.md:1-18](file://README.md#L1-L18)
- [src/main.js:1-14](file://src/main.js#L1-L14)
- [packages/index.js:1-69](file://packages/index.js#L1-L69)
- [packages/components/index.js:1-23](file://packages/components/index.js#L1-L23)

## 核心组件
- ProTable：表格组件，支持远程数据、搜索、分页、工具栏、行内编辑等能力。
- ProForm：表单组件，支持动态渲染、校验、联动、远程下拉等。
- ProSearch：搜索区域组件，配合 ProTable 使用。
- ProSelect：选择器组件，支持本地 list 与远程 request 两种数据源。
- ProTableEdit：可编辑表格组件，用于批量编辑与行级编辑。

这些组件通过统一安装器进行全局注册，便于在项目中按需使用。

**章节来源**
- [types/ProTable.d.ts:1-59](file://types/ProTable.d.ts#L1-L59)
- [packages/components/index.js:1-23](file://packages/components/index.js#L1-L23)
- [types/index.d.ts:1-19](file://types/index.d.ts#L1-L19)

## 架构总览
下图展示了应用启动时的插件安装流程与组件注册关系：

```mermaid
sequenceDiagram
participant App as "应用实例<br/>src/main.js"
participant UI as "View UI Plus<br/>视图组件库"
participant Pro as "Pro 组件库<br/>packages/index.js"
participant Comp as "组件清单<br/>packages/components/index.js"
App->>UI : "use(ViewUIPlus)"
App->>Pro : "use(ProComponents)"
Pro->>Comp : "遍历并注册组件"
Comp-->>Pro : "组件已注册"
Pro-->>App : "安装完成"
```

**图表来源**
- [src/main.js:1-14](file://src/main.js#L1-L14)
- [packages/index.js:1-69](file://packages/index.js#L1-L69)
- [packages/components/index.js:1-23](file://packages/components/index.js#L1-L23)

## 详细组件分析

### ProTable 基础使用
- 安装与初始化
  - 在应用入口完成 View UI Plus 与 Pro 组件库的安装与挂载。
  - 参考：[src/main.js:1-14](file://src/main.js#L1-L14)，[packages/index.js:1-69](file://packages/index.js#L1-L69)

- 最简配置要点
  - v-model 绑定数据数组
  - request 提供远程数据接口或函数
  - columns 定义列与渲染行为
  - map 指定数据与总数字段路径
  - search、form、table 等子配置按需启用
  - 参考示例：[src/views/ProTable.vue:11-100](file://src/views/ProTable.vue#L11-L100)

- 常见属性与子配置
  - columns：列定义、渲染函数、规则、动作等
  - request：字符串 URL 或函数，支持分页参数注入
  - map：dataPath、totalPath 等
  - search：位置、默认值、行数等
  - form：表单布局、默认值等
  - table：高度、样式等
  - 参考类型定义：[types/ProTable.d.ts:1-59](file://types/ProTable.d.ts#L1-L59)

- 典型使用场景
  - 列表查询与分页：绑定 request 与 columns，设置 map
  - 行内编辑：结合 ProTableEdit 或列级 renderTableEdit
  - 动态搜索：通过 ProSearch 与 v-model 同步查询条件
  - 参考示例：[src/views/Home.vue:16-50](file://src/views/Home.vue#L16-L50)

- 最佳实践
  - 使用 v-model.sync 替代 v-model 时注意双向绑定语义
  - 合理设置 columns 的 width/resizable/ellipsis/tooltip 等提升可读性
  - 将复杂格式化逻辑放入 format/value 处理函数，保持模板简洁
  - 对于高频请求，建议在父组件缓存查询条件并节流触发

- 可直接复制的配置模板（路径）
  - 最简表格配置：[src/views/ProTable.vue:26-96](file://src/views/ProTable.vue#L26-L96)
  - 带搜索与分页的表格配置：[src/views/Home.vue:16-50](file://src/views/Home.vue#L16-L50)
  - 列定义与动作示例：[src/views/Home.vue:260-592](file://src/views/Home.vue#L260-L592)

**章节来源**
- [src/main.js:1-14](file://src/main.js#L1-L14)
- [packages/index.js:1-69](file://packages/index.js#L1-L69)
- [types/ProTable.d.ts:1-59](file://types/ProTable.d.ts#L1-L59)
- [src/views/ProTable.vue:11-100](file://src/views/ProTable.vue#L11-L100)
- [src/views/Home.vue:16-50](file://src/views/Home.vue#L16-L50)
- [src/views/Home.vue:260-592](file://src/views/Home.vue#L260-L592)

### ProForm 基础使用
- 安装与初始化
  - 与 ProTable 相同，通过安装器统一注册
  - 参考：[src/main.js:1-14](file://src/main.js#L1-L14)，[packages/index.js:1-69](file://packages/index.js#L1-L69)

- 最简配置要点
  - v-model 绑定表单数据对象
  - columns 定义字段、渲染器、校验规则
  - submitForm 提交接口或函数
  - labelPosition/formLineNum 控制布局
  - 参考示例：[src/views/ProForm.vue:5-28](file://src/views/ProForm.vue#L5-L28)

- 常见属性与子配置
  - columns：title/key/renderForm/rules 等
  - submitForm：request/method/position/complete 等
  - 参考示例：[src/views/ProForm.vue:29-192](file://src/views/ProForm.vue#L29-L192)

- 典型使用场景
  - 动态表单：renderForm 使用 ProSelect、DatePicker 等组合
  - 远程下拉：通过 renderForm.props.request 与 map
  - 表单校验：rules 中配置 required/pattern/message/trigger
  - 参考示例：[src/views/ProForm.vue:36-112](file://src/views/ProForm.vue#L36-L112)

- 最佳实践
  - 将复杂格式化逻辑放入 renderForm.format，避免模板中嵌套过多逻辑
  - 对于多选/级联等复杂控件，优先使用 ProSelect 并配置 request/map
  - 使用 v-model.sync 时确保双向绑定一致

- 可直接复制的配置模板（路径）
  - 最简表单配置：[src/views/ProForm.vue:5-28](file://src/views/ProForm.vue#L5-L28)
  - 动态渲染与校验示例：[src/views/ProForm.vue:29-112](file://src/views/ProForm.vue#L29-L112)

**章节来源**
- [src/main.js:1-14](file://src/main.js#L1-L14)
- [packages/index.js:1-69](file://packages/index.js#L1-L69)
- [src/views/ProForm.vue:5-28](file://src/views/ProForm.vue#L5-L28)
- [src/views/ProForm.vue:29-112](file://src/views/ProForm.vue#L29-L112)

### ProSearch 与 ProSelect
- ProSearch
  - 与 ProTable 搜索联动，通过 v-model 同步查询条件
  - 示例：[src/views/ProSearch.vue:1-59](file://src/views/ProSearch.vue#L1-L59)

- ProSelect
  - 支持本地 list 与远程 request，通过 map 指定标题与值字段
  - 示例：[src/views/ProSelect.vue:45-102](file://src/views/ProSelect.vue#L45-L102)

**章节来源**
- [src/views/ProSearch.vue:1-59](file://src/views/ProSearch.vue#L1-L59)
- [src/views/ProSelect.vue:45-102](file://src/views/ProSelect.vue#L45-L102)

### ProTableEdit（可编辑表格）
- 适用场景：批量编辑、行内编辑、校验与保存
- 常用配置：columns、request、map、controls、table、page、toolBarActions 等
- 示例：[src/views/EditTable.vue:48-357](file://src/views/EditTable.vue#L48-L357)

**章节来源**
- [src/views/EditTable.vue:48-357](file://src/views/EditTable.vue#L48-L357)

## 依赖关系分析
- 应用层依赖 View UI Plus 与 Pro-IVIEW V3
- Pro-IVIEW V3 通过安装器统一注册组件清单
- 组件间通过 v-model、事件与 props 协作

```mermaid
graph LR
Pkg["package.json 依赖"] --> Vue["vue"]
Pkg --> UI["view-ui-plus"]
Pkg --> Axios["axios"]
Pkg --> Dayjs["dayjs"]
Pkg --> Lodash["lodash-es"]
App["src/main.js"] --> ProIndex["packages/index.js"]
ProIndex --> CompIndex["packages/components/index.js"]
```

**图表来源**
- [package.json:20-33](file://package.json#L20-L33)
- [src/main.js:1-14](file://src/main.js#L1-L14)
- [packages/index.js:1-69](file://packages/index.js#L1-L69)
- [packages/components/index.js:1-23](file://packages/components/index.js#L1-L23)

**章节来源**
- [package.json:20-33](file://package.json#L20-L33)
- [src/main.js:1-14](file://src/main.js#L1-L14)
- [packages/index.js:1-69](file://packages/index.js#L1-L69)
- [packages/components/index.js:1-23](file://packages/components/index.js#L1-L23)

## 性能考虑
- 列渲染优化
  - 合理设置列宽与 resizable，避免过度重排
  - 对复杂渲染使用 renderTable/renderForm 的懒加载策略
- 请求与分页
  - 使用 request 函数时，对分页参数进行合并与去抖
  - 通过 map 指定 dataPath/totalPath，减少数据处理开销
- 表单与搜索
  - 将格式化逻辑放入 format/value 处理函数，避免模板重复计算
  - 对高频输入使用防抖/节流
- 可编辑表格
  - 控制每页数据量与列数量，必要时启用虚拟滚动（如组件支持）

## 故障排查指南
- 组件未注册
  - 确认已在入口完成 use(ViewUIPlus) 与 use(ProComponents)
  - 参考：[src/main.js:1-14](file://src/main.js#L1-L14)，[packages/index.js:1-69](file://packages/index.js#L1-L69)

- 表格无数据或总数不正确
  - 检查 request 返回结构与 map 配置
  - 参考：[src/views/ProTable.vue:88-96](file://src/views/ProTable.vue#L88-L96)，[src/views/Home.vue:184-192](file://src/views/Home.vue#L184-L192)

- 表单字段不生效或校验无效
  - 确认 v-model 绑定字段与 key 一致
  - rules 触发时机（trigger）与输入方式匹配
  - 参考：[src/views/ProForm.vue:29-112](file://src/views/ProForm.vue#L29-L112)

- 搜索条件未同步
  - 确保 v-model 与 ProSearch/ProTable 的搜索配置一致
  - 参考：[src/views/ProSearch.vue:22-54](file://src/views/ProSearch.vue#L22-L54)

- 可编辑表格保存异常
  - 检查 save 回调返回结构与 request/map
  - 参考：[src/views/EditTable.vue:458-472](file://src/views/EditTable.vue#L458-L472)

## 结论
通过统一安装器与清晰的组件清单，Pro-IVIEW V3 能够在 Vue 3 + View UI Plus 项目中快速集成 ProTable、ProForm 等核心组件。遵循本文提供的安装、初始化、最简配置与最佳实践，你可以高效构建列表查询、动态表单与可编辑表格等常见业务场景。

## 附录
- 快速开始（步骤）
  1) 在应用入口安装 View UI Plus 与 Pro 组件库
     - 参考：[src/main.js:1-14](file://src/main.js#L1-L14)
  2) 在页面中使用 ProTable/ProForm 等组件
     - 参考：[src/views/ProTable.vue:11-100](file://src/views/ProTable.vue#L11-L100)，[src/views/ProForm.vue:5-28](file://src/views/ProForm.vue#L5-L28)
  3) 配置 request/map 与 columns
     - 参考：[src/views/Home.vue:173-192](file://src/views/Home.vue#L173-L192)，[src/views/Home.vue:260-592](file://src/views/Home.vue#L260-L592)

- 可直接复制的配置模板（路径）
  - ProTable 最简配置：[src/views/ProTable.vue:26-96](file://src/views/ProTable.vue#L26-L96)
  - ProForm 最简配置：[src/views/ProForm.vue:5-28](file://src/views/ProForm.vue#L5-L28)
  - ProSearch 示例：[src/views/ProSearch.vue:22-54](file://src/views/ProSearch.vue#L22-L54)
  - ProSelect 示例：[src/views/ProSelect.vue:45-102](file://src/views/ProSelect.vue#L45-L102)
  - 可编辑表格示例：[src/views/EditTable.vue:138-357](file://src/views/EditTable.vue#L138-L357)