# 基础使用

<cite>
**本文引用的文件**
- [ProTable.vue](file://packages/components/ProTable.vue)
- [ProTable.vue（演示视图）](file://src/views/ProTable.vue)
- [TableRender.vue（演示视图）](file://src/views/TableRender.vue)
- [ProSearch.vue](file://packages/components/ProSearch.vue)
- [ProTypeItem.vue](file://packages/components/ProTypeItem/ProTypeItem.vue)
- [request.js](file://packages/libs/request.js)
- [components/index.js](file://packages/components/index.js)
- [main.js](file://src/main.js)
- [ProTable.d.ts](file://types/ProTable.d.ts)
- [ProTable 编辑版组件（参考）](file://packages/components/ProTableEdit.vue)
- [全局类型声明（安装与全局选项）](file://types/index.d.ts)
</cite>

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

## 简介
本篇“基础使用”文档面向新手开发者，帮助你快速掌握 ProTable 组件的核心能力：配置数据源、定义基础列、启用搜索与分页，并完成一次完整的页面集成。我们将围绕以下关键点展开：
- 数据源配置（request、autoFetch、map）
- 基本列定义（columns）
- 搜索与分页（ProSearch、Page）
- 完整示例与最佳实践

## 项目结构
ProTable 位于组件库 packages/components 下，配套的搜索组件 ProSearch、通用渲染器 ProTypeItem 与其请求适配器 request.js 协同工作；在示例工程 src/views 中提供了两个可直接运行的演示页面。

```mermaid
graph TB
subgraph "应用入口"
main_js["src/main.js"]
end
subgraph "组件库"
pt["packages/components/ProTable.vue"]
ps["packages/components/ProSearch.vue"]
pti["packages/components/ProTypeItem/ProTypeItem.vue"]
req["packages/libs/request.js"]
idx["packages/components/index.js"]
end
subgraph "示例页面"
demo1["src/views/ProTable.vue"]
demo2["src/views/TableRender.vue"]
end
main_js --> idx
idx --> pt
pt --> ps
pt --> pti
pt --> req
demo1 --> pt
demo2 --> pt
```

**图表来源**
- [main.js:1-14](file://src/main.js#L1-L14)
- [components/index.js:1-23](file://packages/components/index.js#L1-L23)
- [ProTable.vue:1-152](file://packages/components/ProTable.vue#L1-L152)
- [ProSearch.vue:1-112](file://packages/components/ProSearch.vue#L1-L112)
- [ProTypeItem.vue:1-132](file://packages/components/ProTypeItem/ProTypeItem.vue#L1-L132)
- [request.js:1-78](file://packages/libs/request.js#L1-L78)
- [ProTable.vue（演示视图）:1-306](file://src/views/ProTable.vue#L1-L306)
- [TableRender.vue（演示视图）:1-51](file://src/views/TableRender.vue#L1-L51)

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

## 核心组件
- ProTable：提供搜索、工具栏、表格主体、分页、弹窗表单等一体化能力，支持远程数据拉取与本地数据绑定。
- ProSearch：根据 columns 中的 renderSearch 定义生成搜索表单项，统一触发查询。
- ProTypeItem：通用渲染器，支持传入组件类型、props、事件与插槽，用于在搜索、表格、表单中复用。
- request.js：统一请求适配器，支持字符串 URL、对象配置、函数回调三种 request 形式，自动处理 GET/POST 参数与占位替换。

**章节来源**
- [ProTable.vue:154-266](file://packages/components/ProTable.vue#L154-L266)
- [ProSearch.vue:114-151](file://packages/components/ProSearch.vue#L114-L151)
- [ProTypeItem.vue:7-25](file://packages/components/ProTypeItem/ProTypeItem.vue#L7-L25)
- [request.js:39-77](file://packages/libs/request.js#L39-L77)

## 架构总览
下面的序列图展示了从用户输入到数据加载的关键流程，以及 ProTable 如何与 ProSearch、request.js 协作：

```mermaid
sequenceDiagram
participant U as "用户"
participant PT as "ProTable"
participant PS as "ProSearch"
participant REQ as "request.js"
participant S as "服务端"
U->>PS : 输入搜索条件
PS-->>PT : 触发 search 事件
PT->>PT : 重置页码为 1
PT->>REQ : 发起请求携带分页与搜索参数
REQ->>S : GET/POST 请求
S-->>REQ : 返回数据含 dataPath、totalPath
REQ-->>PT : 返回响应
PT->>PT : 解析 map.dataPath/map.totalPath
PT-->>U : 渲染表格与分页
```

**图表来源**
- [ProTable.vue:605-741](file://packages/components/ProTable.vue#L605-L741)
- [ProSearch.vue:181-189](file://packages/components/ProSearch.vue#L181-L189)
- [request.js:39-77](file://packages/libs/request.js#L39-L77)

## 详细组件解析

### ProTable 基础配置与用法
- 数据源配置
  - request：支持字符串 URL、对象配置或函数回调。当为对象时，可指定 url/request、method、headers、keys 等。
  - autoFetch：是否在挂载后自动发起首次请求，默认开启。
  - map：约定后端返回的数据结构，如 dataPath、totalPath、message、success 等字段路径。
  - format：可选格式化函数，用于将分页参数转换为目标格式。
- 列定义 columns
  - 每个列可设置 title、key、width、align、fixed 等基础属性。
  - 支持 renderTable、renderSearch、renderForm 等渲染方式，亦可通过 ProTypeItem 快速组合常用控件。
  - 可通过 notShowSearch/notShowTable/notShowForm 控制不同场景下的显示。
- 搜索与分页
  - ProSearch 根据 columns 的 renderSearch 自动渲染搜索项，支持展开/收起。
  - Page 组件与 ProTable 内部页码状态联动，支持页大小变更与总数/页码显示。
- 表单与弹窗
  - 通过 submitForm 或列定义中的 request，在新建/编辑时提交数据。
  - 成功/失败消息由 map.message 与 map.success 控制。

**章节来源**
- [ProTable.vue:195-266](file://packages/components/ProTable.vue#L195-L266)
- [ProTable.vue:400-421](file://packages/components/ProTable.vue#L400-L421)
- [ProTable.vue:605-741](file://packages/components/ProTable.vue#L605-L741)
- [ProTable.vue:800-830](file://packages/components/ProTable.vue#L800-L830)
- [ProTable.d.ts:3-58](file://types/ProTable.d.ts#L3-L58)

### 示例：快速集成 ProTable
- 在入口文件注册组件库并挂载
  - 在应用入口引入组件库并在 app.use 中注册。
- 在页面中使用 ProTable
  - 通过 v-bind 绑定配置对象，v-model 绑定数据数组。
  - 使用 ref 调用内部方法（如 search）进行手动触发。
- 最小可用配置
  - 至少提供 request 与 columns；若后端返回结构非默认，请配置 map。
  - 若需要搜索，确保列定义中包含 renderSearch 或在 search 属性中传入初始值。

**章节来源**
- [main.js:7-13](file://src/main.js#L7-L13)
- [ProTable.vue（演示视图）:11-16](file://src/views/ProTable.vue#L11-L16)
- [ProTable.vue（演示视图）:26-96](file://src/views/ProTable.vue#L26-L96)

### 搜索与分页流程（算法流程图）
```mermaid
flowchart TD
Start(["开始"]) --> Init["初始化<br/>autoFetch/autoFetch=false"]
Init --> |true| FetchFirst["执行首次请求"]
Init --> |false| Wait["等待手动触发"]
FetchFirst --> Search["用户在搜索区输入"]
Search --> EmitSearch["触发 search 事件"]
EmitSearch --> ResetPage["页码重置为 1"]
ResetPage --> Request["调用 request.js 发送请求"]
Request --> Parse["按 map 解析 dataPath/totalPath"]
Parse --> Render["渲染表格与分页"]
Render --> End(["结束"])
```

**图表来源**
- [ProTable.vue:429-442](file://packages/components/ProTable.vue#L429-L442)
- [ProTable.vue:625-634](file://packages/components/ProTable.vue#L625-L634)
- [ProTable.vue:665-741](file://packages/components/ProTable.vue#L665-L741)
- [request.js:39-77](file://packages/libs/request.js#L39-L77)

### ProSearch 与 ProTypeItem 的协作
- ProSearch 根据 columns 的 renderSearch 渲染对应控件，支持自定义组件类型、props、事件与插槽。
- ProTypeItem 接收 renderItem 并动态渲染组件，支持表达式计算与格式化包装。

**章节来源**
- [ProSearch.vue:1-112](file://packages/components/ProSearch.vue#L1-L112)
- [ProTypeItem.vue:51-124](file://packages/components/ProTypeItem/ProTypeItem.vue#L51-L124)

## 依赖关系分析
- ProTable 依赖 ProSearch、ProForm、ProTypeItem、UIEditFrame、screenfull 等组件与工具。
- 请求层通过 request.js 统一适配 axios，支持多种 request 形式与参数抽取。
- 类型层面，ProTable.d.ts 提供 columns、request、map、hide、search、form、table 等属性说明。

```mermaid
graph LR
PT["ProTable.vue"] --> PS["ProSearch.vue"]
PT --> Pti["ProTypeItem.vue"]
PT --> Req["request.js"]
Demo1["src/views/ProTable.vue"] --> PT
Demo2["src/views/TableRender.vue"] --> PT
```

**图表来源**
- [ProTable.vue:159-164](file://packages/components/ProTable.vue#L159-L164)
- [ProSearch.vue:1-112](file://packages/components/ProSearch.vue#L1-L112)
- [ProTypeItem.vue:1-132](file://packages/components/ProTypeItem/ProTypeItem.vue#L1-L132)
- [request.js:1-78](file://packages/libs/request.js#L1-L78)
- [ProTable.vue（演示视图）:1-306](file://src/views/ProTable.vue#L1-L306)
- [TableRender.vue（演示视图）:1-51](file://src/views/TableRender.vue#L1-L51)

**章节来源**
- [ProTable.vue:159-164](file://packages/components/ProTable.vue#L159-L164)
- [ProTable.d.ts:1-59](file://types/ProTable.d.ts#L1-L59)

## 性能考量
- 合理设置分页参数（pageSize、page-size-opts），避免一次性加载过多数据。
- 使用 map.dataPath 与 map.totalPath 精准定位数据与总数，减少不必要的数据处理。
- 在 columns 中按需开启渲染（如 notShowSearch/notShowTable），降低 DOM 与事件数量。
- 对于复杂搜索项，尽量使用受控组件与防抖策略，避免频繁触发请求。

## 故障排查指南
- 请求路径为空
  - 现象：控制台提示请求路径为空。
  - 处理：确认 request 是否正确传入字符串、对象或函数。
  - 参考：[ProTable.vue:738-740](file://packages/components/ProTable.vue#L738-L740)
- 数据路径不匹配
  - 现象：表格无数据显示或总数为 0。
  - 处理：检查 map.dataPath 与 map.totalPath 是否与后端一致。
  - 参考：[ProTable.vue:707-720](file://packages/components/ProTable.vue#L707-L720)
- 分页参数格式不符
  - 现象：分页无效或请求参数异常。
  - 处理：通过 format.formatCurrent 将分页参数转换为目标格式。
  - 参考：[ProTable.vue:673-686](file://packages/components/ProTable.vue#L673-L686)
- 搜索项未生效
  - 现象：输入搜索条件后未触发查询。
  - 处理：确认 columns 中存在 renderSearch，或在 search 属性中传入初始值。
  - 参考：[ProSearch.vue:181-189](file://packages/components/ProSearch.vue#L181-L189)

**章节来源**
- [ProTable.vue:665-741](file://packages/components/ProTable.vue#L665-L741)
- [ProSearch.vue:181-189](file://packages/components/ProSearch.vue#L181-L189)

## 结论
通过本文档，你可以基于最小配置快速集成 ProTable：提供 request 与 columns，必要时配置 map 与 format，即可获得带搜索与分页的完整列表能力。随着业务深入，可进一步利用 ProTypeItem 的灵活渲染、ProSearch 的多形态搜索、以及弹窗表单的提交流程，构建更丰富的数据管理界面。

## 附录：快速上手清单
- 在入口文件注册组件库并挂载
  - 参考：[main.js:7-13](file://src/main.js#L7-L13)
- 在页面中使用 ProTable
  - v-bind 绑定配置，v-model 绑定数据，ref 调用内部方法
  - 参考：[ProTable.vue（演示视图）:11-16](file://src/views/ProTable.vue#L11-L16)
- 最小可用配置
  - request、columns；如后端返回结构非默认，配置 map
  - 参考：[ProTable.vue:229-242](file://packages/components/ProTable.vue#L229-L242)
- 搜索与分页
  - 在列定义中提供 renderSearch；Page 组件与 ProTable 内部页码联动
  - 参考：[ProSearch.vue:1-112](file://packages/components/ProSearch.vue#L1-L112)
- 提交表单
  - 通过 submitForm 或列定义中的 request 提交新建/编辑
  - 参考：[ProTable.vue:800-830](file://packages/components/ProTable.vue#L800-L830)