# 代码片段集合

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

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

## 简介
本文件面向 Pro-IVIEW V3 的使用者与二次开发者，系统性整理常用“代码片段与配置模板”，覆盖以下主题：
- 组件配置：表格、表单、搜索、可编辑表格、复选框等
- 事件处理：点击、校验、保存、导出、分页等
- 样式定制：列宽、对齐、固定列、工具栏动作等
- 可直接使用的模板：表格配置、表单定义、搜索条件等
- 性能优化：懒加载、防抖、分页策略、缓存映射
- 错误处理：HTTP 拦截器、消息提示、异常分支
- 扩展与修改：基于适配器模式的 UI 解耦、全局配置注入

## 项目结构
项目采用多包（Monorepo）结构，核心能力集中在 packages/core，并通过适配器模式对接 view-ui-plus 与 element-plus。示例应用位于 src 下，包含多个演示视图。

```mermaid
graph TB
subgraph "示例应用(src)"
A_App["App.vue"]
A_Router["router/index.js"]
V_ProTable["views/ProTable.vue"]
V_ProForm["views/ProForm.vue"]
V_ProSearch["views/ProSearch.vue"]
V_EditTable["views/EditTable.vue"]
V_ProCheckbox["views/ProCheckbox.vue"]
Lib_HTTP["libs/http.js"]
end
subgraph "组件库(packages)"
P_Index["packages/index.js"]
Core_Main["packages/core/src/index.js"]
Adapter_View["packages/adapters/view-ui-plus/src/index.js"]
Adapter_Element["packages/adapters/element-plus/src/index.js"]
end
A_App --> A_Router
A_Router --> V_ProTable
A_Router --> V_ProForm
A_Router --> V_ProSearch
A_Router --> V_EditTable
A_Router --> V_ProCheckbox
A_App --> P_Index
P_Index --> Core_Main
P_Index --> Adapter_View
P_Index --> Adapter_Element
Lib_HTTP --> P_Index
```

图表来源
- [src/App.vue:1-9](file://src/App.vue#L1-L9)
- [src/router/index.js:1-66](file://src/router/index.js#L1-L66)
- [packages/index.js:1-69](file://packages/index.js#L1-L69)
- [src/libs/http.js:1-70](file://src/libs/http.js#L1-L70)

章节来源
- [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)

## 核心组件
- 表格组件：支持远程数据、分页、搜索、列配置、工具栏动作、行内操作等
- 表单组件：支持动态渲染、规则校验、提交回调、联动选择等
- 搜索组件：支持多字段搜索、日期范围、格式化输出
- 可编辑表格：支持新增/删除/编辑、校验、导出、快捷键
- 复选框组件：支持远程数据源、映射、多选/单选

章节来源
- [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/EditTable.vue:1-479](file://src/views/EditTable.vue#L1-L479)
- [src/views/ProCheckbox.vue:1-48](file://src/views/ProCheckbox.vue#L1-L48)

## 架构总览
组件库通过统一的安装入口注册全局组件与指令，并提供国际化与全局对象注入。示例应用通过路由挂载各演示视图。

```mermaid
sequenceDiagram
participant App as "应用(App.vue)"
participant Main as "入口(main.js)"
participant Pro as "组件库(packages/index.js)"
participant Router as "路由(router/index.js)"
participant View as "视图(views/*)"
App->>Main : 加载入口
Main->>Pro : app.use(ProComponents)
Pro->>Pro : 注册全局组件/指令/国际化
Main->>Router : app.use(router)
Router->>View : 路由切换渲染
```

图表来源
- [src/main.js:1-14](file://src/main.js#L1-L14)
- [packages/index.js:11-42](file://packages/index.js#L11-L42)
- [src/router/index.js:1-66](file://src/router/index.js#L1-L66)

章节来源
- [src/main.js:1-14](file://src/main.js#L1-L14)
- [packages/index.js:11-42](file://packages/index.js#L11-L42)
- [src/router/index.js:1-66](file://src/router/index.js#L1-L66)

## 详细组件分析

### 表格组件（ProTable）
- 配置要点
  - 远程请求：通过 request 字段绑定接口地址
  - 分页映射：通过 map.dataPath、map.totalPath 映射数据与总数
  - 列配置：columns 支持标题、宽度、对齐、固定、渲染函数、搜索渲染、表单渲染、规则校验等
  - 工具栏：toolBarActions 控制刷新、全屏、行设置等
  - 操作列：actions 定义删除、自定义方法等
- 事件与方法
  - 行点击事件：@table:on-row-click
  - 触发搜索：通过 ref 调用 search() 方法
- 模板片段路径
  - [表格配置与列定义:26-96](file://src/views/ProTable.vue#L26-L96)
  - [复杂列与规则示例:160-281](file://src/views/ProTable.vue#L160-L281)
  - [行点击与触发搜索:293-301](file://src/views/ProTable.vue#L293-L301)

```mermaid
sequenceDiagram
participant Demo as "演示页面(ProTable.vue)"
participant Table as "ProTable 组件"
participant API as "后端接口"
Demo->>Table : v-bind="config" v-model="datas"
Demo->>Table : @table : on-row-click
Demo->>Table : ref.search()
Table->>API : GET request + 查询参数
API-->>Table : { data, totalRows }
Table-->>Demo : 渲染表格/更新分页
```

图表来源
- [src/views/ProTable.vue:11-16](file://src/views/ProTable.vue#L11-L16)
- [src/views/ProTable.vue:26-96](file://src/views/ProTable.vue#L26-L96)

章节来源
- [src/views/ProTable.vue:1-306](file://src/views/ProTable.vue#L1-L306)

### 表单组件（ProForm）
- 配置要点
  - 表单项：通过 columns 数组定义标题、键值、渲染函数、规则等
  - 提交配置：submitForm.request、position、complete 回调
  - 动态渲染：renderForm 支持 JSX/组件属性/函数返回
  - 日期格式化：format 函数用于格式化时间值
- 模板片段路径
  - [表单配置与提交:17-29](file://src/views/ProForm.vue#L17-L29)
  - [动态渲染与规则:29-192](file://src/views/ProForm.vue#L29-L192)

```mermaid
flowchart TD
Start(["进入表单"]) --> LoadConfig["加载 columns 配置"]
LoadConfig --> RenderFields["渲染表单项"]
RenderFields --> Validate["按 rules 校验"]
Validate --> Valid{"校验通过？"}
Valid --> |否| ShowError["显示错误提示"]
Valid --> |是| Submit["调用 submitForm.complete 回调"]
Submit --> End(["完成"])
ShowError --> End
```

图表来源
- [src/views/ProForm.vue:17-29](file://src/views/ProForm.vue#L17-L29)
- [src/views/ProForm.vue:29-192](file://src/views/ProForm.vue#L29-L192)

章节来源
- [src/views/ProForm.vue:1-198](file://src/views/ProForm.vue#L1-L198)

### 搜索组件（ProSearch）
- 配置要点
  - columns 定义搜索字段，renderSearch 支持 DatePicker 等控件
  - format 支持 formatWapper 与 ES6 表达式格式化
  - 插槽 buttons 可扩展额外按钮
- 模板片段路径
  - [搜索列与格式化:22-54](file://src/views/ProSearch.vue#L22-L54)

```mermaid
sequenceDiagram
participant Demo as "演示页面(ProSearch.vue)"
participant Search as "ProSearch 组件"
participant API as "后端接口"
Demo->>Search : v-bind="columns" v-model="cc"
Search->>Search : renderSearch 渲染控件
Search->>API : 传入格式化后的查询参数
API-->>Search : 返回结果
Search-->>Demo : 更新查询条件
```

图表来源
- [src/views/ProSearch.vue:3-14](file://src/views/ProSearch.vue#L3-L14)
- [src/views/ProSearch.vue:22-54](file://src/views/ProSearch.vue#L22-L54)

章节来源
- [src/views/ProSearch.vue:1-59](file://src/views/ProSearch.vue#L1-L59)

### 可编辑表格（ProTableEdit）
- 配置要点
  - columns 支持 renderTableEdit.normal/edit、规则、固定列、排序等
  - request/page/map 控制分页与数据加载
  - controls/toolBarActions 控制工具栏与左侧控件
  - 支持导出 CSV、批量新增、设置焦点、禁用状态等
- 事件与方法
  - addRow/addMultiple/reset/setEditRow/validateAll/fetch/exportCsv/setTableStatus
  - save 回调用于持久化
- 模板片段路径
  - [编辑表格配置与列定义:119-357](file://src/views/EditTable.vue#L119-L357)
  - [工具栏与保存回调:144-160](file://src/views/EditTable.vue#L144-L160)
  - [行内编辑渲染示例:221-248](file://src/views/EditTable.vue#L221-L248)

```mermaid
sequenceDiagram
participant Demo as "演示页面(EditTable.vue)"
participant Edit as "ProTableEdit 组件"
participant API as "后端接口"
Demo->>Edit : v-bind="config" v-model="myData"
Demo->>Edit : addRow()/addMultiple()/validateAll()
Edit->>API : request + page 参数
API-->>Edit : { data, totalRows }
Edit-->>Demo : 渲染表格/更新数据
Demo->>Edit : save(data)
Edit->>API : 保存请求
API-->>Edit : 保存结果
Edit-->>Demo : 完成回调/关闭加载
```

图表来源
- [src/views/EditTable.vue:48-58](file://src/views/EditTable.vue#L48-L58)
- [src/views/EditTable.vue:119-357](file://src/views/EditTable.vue#L119-L357)
- [src/views/EditTable.vue:458-472](file://src/views/EditTable.vue#L458-L472)

章节来源
- [src/views/EditTable.vue:1-479](file://src/views/EditTable.vue#L1-L479)

### 复选框组件（ProCheckBox）
- 配置要点
  - 支持远程 request 与本地 list
  - map.titlePath/valuePath 映射标题与值
  - multiple 控制多选/单选
- 模板片段路径
  - [复选框配置与映射:13-41](file://src/views/ProCheckbox.vue#L13-L41)

章节来源
- [src/views/ProCheckbox.vue:1-48](file://src/views/ProCheckbox.vue#L1-L48)

## 依赖关系分析
- 全局依赖
  - axios：HTTP 请求与拦截器
  - dayjs/lodash-es：日期与工具函数
  - view-ui-plus：UI 组件库
  - vue3-click-away：点击外部关闭
- 应用依赖
  - 路由：vue-router
  - i18n：vue-i18n
- 类型定义
  - 全局属性 $http/$dayjs/$lodash/$PRO_IVIEW 注入

```mermaid
graph LR
App["应用(main.js)"] --> Axios["axios"]
App --> Dayjs["dayjs"]
App --> Lodash["lodash-es"]
App --> UI["view-ui-plus"]
App --> Router["vue-router"]
App --> I18n["vue-i18n"]
App --> ClickAway["vue3-click-away"]
App --> ProIndex["packages/index.js"]
```

图表来源
- [src/main.js:1-14](file://src/main.js#L1-L14)
- [package.json:20-32](file://package.json#L20-L32)
- [packages/index.js:4-9](file://packages/index.js#L4-L9)

章节来源
- [package.json:1-47](file://package.json#L1-L47)
- [src/main.js:1-14](file://src/main.js#L1-L14)
- [types/index.d.ts:4-19](file://types/index.d.ts#L4-L19)

## 性能考虑
- 分页与懒加载
  - 使用 page.pageSize 与 map.dataPath/totalPath 控制分页与数据映射
  - 可结合虚拟滚动或服务端分页减少首屏压力
- 渲染优化
  - 列渲染尽量使用受控组件与最小化 JSX 计算
  - 对高频交互（如输入框）使用防抖/节流
- 缓存与映射
  - 使用 $PRO_IVIEW.map/format 进行全局映射与格式化
  - 对远程下拉/选择建议做本地缓存与去重
- 网络与超时
  - axios 默认超时与拦截器统一处理错误，避免重复弹窗
- 事件与内存
  - 合理销毁定时器与监听器，避免内存泄漏

## 故障排查指南
- HTTP 异常处理
  - 请求拦截器：自动注入 Authorization、统一 Content-Type、超时处理
  - 响应拦截器：状态码判断、错误消息提示、统一返回结构
- 常见问题
  - 401/403：检查本地 token 是否存在与过期
  - 504/404：服务端异常或接口不存在
  - 超时：调整 axios.defaults.timeout 或网络环境
- 消息提示
  - 统一使用 Message 组件进行提示，避免分散日志

章节来源
- [src/libs/http.js:12-67](file://src/libs/http.js#L12-L67)

## 结论
本集合文档提供了 Pro-IVIEW V3 的核心组件使用范式与可复用模板，配合适配器模式与全局配置，可在不改变业务代码的情况下灵活切换 UI 库。建议在实际项目中：
- 将配置抽离为可复用的 JSON/JS 模块
- 在拦截器中统一处理鉴权与错误
- 对高频交互进行性能优化与缓存
- 通过路由与视图分离，逐步替换旧组件

## 附录
- 全局对象与类型
  - $http/$dayjs/$lodash/$PRO_IVIEW 注入与类型声明
- 适配器与 UI 解耦
  - 通过 useUIAdapter 注入 UI 组件，实现核心逻辑与 UI 库解耦

章节来源
- [types/index.d.ts:4-19](file://types/index.d.ts#L4-L19)
- [ARCHITECTURE_SUMMARY.md:124-156](file://ARCHITECTURE_SUMMARY.md#L124-L156)