# 数据配置

<cite>
**本文引用的文件**
- [packages/components/ProTable.vue](file://packages/components/ProTable.vue)
- [packages/libs/request.js](file://packages/libs/request.js)
- [src/views/ProTable.vue](file://src/views/ProTable.vue)
- [types/ProTable.d.ts](file://types/ProTable.d.ts)
- [src/libs/http.js](file://src/libs/http.js)
- [packages/components/ProTableEdit.vue](file://packages/components/ProTableEdit.vue)
- [packages/core/src/components/ProTable.vue](file://packages/core/src/components/ProTable.vue)
- [packages/core/src/libs/request.js](file://packages/core/src/libs/request.js)
</cite>

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

## 简介
本章节聚焦 ProTable 的“数据配置”能力，系统讲解以下主题：
- 数据源配置方式：静态数据、远程 API 请求、数据格式映射
- request 属性的配置方法：HTTP 方法、请求头、数据格式化（含 keys、params/data 自动拆分）
- map 属性的作用与配置：分页参数映射、数据路径与总数路径、成功条件与消息映射
- 实际配置示例与最佳实践
- 错误处理与数据验证要点

## 项目结构
围绕数据配置的关键文件与职责如下：
- 组件层：ProTable.vue 负责表格渲染、搜索、分页、提交表单、请求封装与结果映射
- 请求封装层：request.js 提供统一的请求适配器，支持字符串、对象与函数三种 request 形态
- 类型定义：ProTable.d.ts 描述 request、map、submitForm 等属性类型
- 示例与演示：src/views/ProTable.vue 展示了 map、request、submitForm 的典型用法
- 全局 HTTP 配置：src/libs/http.js 提供拦截器与默认配置（如 Content-Type、Authorization）

```mermaid
graph TB
A["视图示例<br/>src/views/ProTable.vue"] --> B["组件实现<br/>packages/components/ProTable.vue"]
B --> C["请求适配器<br/>packages/libs/request.js"]
C --> D["HTTP 库封装<br/>src/libs/http.js"]
E["类型定义<br/>types/ProTable.d.ts"] --> B
F["核心组件实现<br/>packages/core/src/components/ProTable.vue"] --> C
G["核心请求适配器<br/>packages/core/src/libs/request.js"] --> D
```

**图表来源**
- [src/views/ProTable.vue:1-306](file://src/views/ProTable.vue#L1-L306)
- [packages/components/ProTable.vue:154-957](file://packages/components/ProTable.vue#L154-L957)
- [packages/libs/request.js:1-78](file://packages/libs/request.js#L1-L78)
- [src/libs/http.js:1-70](file://src/libs/http.js#L1-L70)
- [types/ProTable.d.ts:1-59](file://types/ProTable.d.ts#L1-L59)
- [packages/core/src/components/ProTable.vue:167-957](file://packages/core/src/components/ProTable.vue#L167-L957)
- [packages/core/src/libs/request.js:44-77](file://packages/core/src/libs/request.js#L44-L77)

**章节来源**
- [src/views/ProTable.vue:1-306](file://src/views/ProTable.vue#L1-L306)
- [packages/components/ProTable.vue:154-957](file://packages/components/ProTable.vue#L154-L957)
- [packages/libs/request.js:1-78](file://packages/libs/request.js#L1-L78)
- [src/libs/http.js:1-70](file://src/libs/http.js#L1-L70)
- [types/ProTable.d.ts:1-59](file://types/ProTable.d.ts#L1-L59)
- [packages/core/src/components/ProTable.vue:167-957](file://packages/core/src/components/ProTable.vue#L167-L957)
- [packages/core/src/libs/request.js:44-77](file://packages/core/src/libs/request.js#L44-L77)

## 核心组件
- request：支持字符串 URL、对象（含 url/request 与 method、headers 等）、函数；内部通过 request.js 统一适配
- map：用于从后端响应中提取 data 与 total，以及可选的成功条件与消息字段
- submitForm：新增/编辑提交接口，可复用 request 或单独配置
- method、headers：全局请求方法与请求头
- format.formatCurrent：可自定义分页 current 的计算表达式或函数

上述能力在组件实现与类型定义中均有体现。

**章节来源**
- [packages/components/ProTable.vue:222-243](file://packages/components/ProTable.vue#L222-L243)
- [types/ProTable.d.ts:26-45](file://types/ProTable.d.ts#L26-L45)
- [packages/components/ProTable.vue:665-735](file://packages/components/ProTable.vue#L665-L735)

## 架构总览
下面的序列图展示了 ProTable 在一次查询中的数据流：从用户触发搜索到最终渲染表格数据与分页总数。

```mermaid
sequenceDiagram
participant U as "用户"
participant PT as "ProTable 组件"
participant CR as "customRequest<br/>request.js"
participant AX as "HTTP 客户端<br/>src/libs/http.js"
participant API as "后端接口"
U->>PT : 触发搜索/分页变更
PT->>PT : 计算分页值与查询参数
PT->>CR : 调用 customRequest({request, method, headers, datas})
CR->>AX : 发送 HTTP 请求
AX-->>CR : 返回响应数据
CR-->>PT : 返回响应
PT->>PT : 使用 map.dataPath/map.totalPath 提取数据
PT-->>U : 渲染表格与分页
```

**图表来源**
- [packages/components/ProTable.vue:665-735](file://packages/components/ProTable.vue#L665-L735)
- [packages/libs/request.js:39-77](file://packages/libs/request.js#L39-L77)
- [src/libs/http.js:12-67](file://src/libs/http.js#L12-L67)

## 详细组件分析

### 数据源配置方式
- 静态数据：通过 v-model 或直接传入数组，组件内部会根据 hide.page 控制是否显示分页
- 远程 API：通过 request 配置字符串 URL、对象或函数；组件自动拼装分页与查询参数
- 数据格式映射：通过 map.dataPath 与 map.totalPath 从响应体中提取列表与总数

示例参考：
- [src/views/ProTable.vue:26-96](file://src/views/ProTable.vue#L26-L96)
- [packages/components/ProTable.vue:665-735](file://packages/components/ProTable.vue#L665-L735)

**章节来源**
- [src/views/ProTable.vue:26-96](file://src/views/ProTable.vue#L26-L96)
- [packages/components/ProTable.vue:665-735](file://packages/components/ProTable.vue#L665-L735)

### request 属性详解
- 支持三种形态：
  - 字符串：作为 URL，自动注入 headers、params/data
  - 对象：可包含 url/request、method、headers、keys 等；若包含 request 且为函数则直接调用
  - 函数：直接接收 datas 并返回 Promise
- 参数选择 keys：仅从 datas 中挑选指定字段参与请求
- URL 占位替换：支持 ${key} 替换
- HTTP 默认行为：由 src/libs/http.js 注入默认 Content-Type、Authorization、超时与拦截器

```mermaid
flowchart TD
Start(["进入 customRequest"]) --> Type{"request 类型？"}
Type --> |字符串| S1["构造 axios({url, method, headers})<br/>params 或 data 取决于 method"]
Type --> |对象| O1["解析 keys/request/url/method"]
O1 --> O2{"request.request 是否函数？"}
O2 --> |是| F1["调用 request.request(datas)"]
O2 --> |否| F2["替换 URL 占位<br/>合并 headers/method"]
Type --> |函数| FN["调用 request(datas)"]
S1 --> End(["返回 Promise"])
F1 --> End
F2 --> End
FN --> End
```

**图表来源**
- [packages/libs/request.js:39-77](file://packages/libs/request.js#L39-L77)
- [src/libs/http.js:12-67](file://src/libs/http.js#L12-L67)

**章节来源**
- [packages/libs/request.js:1-78](file://packages/libs/request.js#L1-L78)
- [src/libs/http.js:1-70](file://src/libs/http.js#L1-L70)

### map 属性详解
- dataPath：从响应体中提取数据数组的路径
- totalPath：从响应体中提取总数的路径
- success：可选，用于判断响应是否成功的表达式（如 "code===200"），未设置时默认以 success 字段为准
- message：可选，用于展示成功/失败消息的字段路径
- 在 ProTableEdit 中还存在 savePath，用于保存场景的数据提取

```mermaid
flowchart TD
R(["收到响应 res"]) --> P1{"res 是否包含 dataPath 指向的数据？"}
P1 --> |是| D1["proData = get(res, dataPath)"]
P1 --> |否| D0["proData = []"]
D1 --> T1{"res 是否包含 totalPath？"}
D0 --> T0["total = 0"]
T1 --> |是| N1["total = get(res, totalPath)"]
T1 --> |否| N0["total = 0"]
N1 --> S1{"是否配置 success 条件？"}
N0 --> S1
S1 --> |是| C1{"条件成立？"}
C1 --> |是| OK["执行成功回调"]
C1 --> |否| ER["执行错误提示"]
S1 --> |否| DEF{"res.success 存在且为真？"}
DEF --> |是| OK
DEF --> |否| ER
```

**图表来源**
- [packages/components/ProTable.vue:707-722](file://packages/components/ProTable.vue#L707-L722)
- [packages/components/ProTable.vue:782-798](file://packages/components/ProTable.vue#L782-L798)

**章节来源**
- [packages/components/ProTable.vue:234-243](file://packages/components/ProTable.vue#L234-L243)
- [packages/components/ProTable.vue:707-722](file://packages/components/ProTable.vue#L707-L722)
- [packages/components/ProTable.vue:782-798](file://packages/components/ProTable.vue#L782-L798)
- [packages/components/ProTableEdit.vue:721-751](file://packages/components/ProTableEdit.vue#L721-L751)

### 分页与数据格式化
- 默认分页键：current 与 pageSize 由 map.current 与 map.pageSize 控制
- format.formatCurrent：支持函数或字符串表达式，用于重写 current 的计算逻辑
- 当前实现中，字符串表达式会被包装为函数执行，并与默认 pageValue 合并

```mermaid
flowchart TD
S(["开始 fetch"]) --> Init["初始化 pageValue = {current, pageSize}"]
Init --> HasFmt{"是否存在 format.formatCurrent？"}
HasFmt --> |函数| F1["pageValue = formatCurrent(page)"]
HasFmt --> |字符串| S1["编译表达式并执行<br/>得到新的 current 值"]
HasFmt --> |无| J1["保持默认 current/pageSize"]
F1 --> Merge["合并分页与查询参数"]
S1 --> Merge
J1 --> Merge
Merge --> Request["调用 customRequest 发起请求"]
Request --> Done(["完成"])
```

**图表来源**
- [packages/components/ProTable.vue:669-687](file://packages/components/ProTable.vue#L669-L687)

**章节来源**
- [packages/components/ProTable.vue:669-687](file://packages/components/ProTable.vue#L669-L687)
- [src/views/Home.vue:165-171](file://src/views/Home.vue#L165-L171)

### 提交表单与删除流程
- 新增/编辑：通过 submitForm 或 request 提交，使用 headers 与 method
- 删除：对列动作中的 delete 类型，使用自定义请求，删除成功后刷新当前页
- 成功/失败提示：依据 map.message 或默认文案

```mermaid
sequenceDiagram
participant U as "用户"
participant PT as "ProTable 组件"
participant CR as "customRequest"
participant AX as "HTTP 客户端"
participant API as "后端接口"
U->>PT : 点击“删除”
PT->>CR : 调用 customRequest(val)
CR->>AX : 发送删除请求
AX-->>CR : 返回响应
CR-->>PT : 返回响应
PT->>PT : 若成功则刷新页面
PT-->>U : 更新表格数据
```

**图表来源**
- [packages/components/ProTable.vue:569-588](file://packages/components/ProTable.vue#L569-L588)
- [packages/components/ProTable.vue:799-830](file://packages/components/ProTable.vue#L799-L830)

**章节来源**
- [packages/components/ProTable.vue:569-588](file://packages/components/ProTable.vue#L569-L588)
- [packages/components/ProTable.vue:799-830](file://packages/components/ProTable.vue#L799-L830)

### 类型与属性定义
- request：字符串、函数或对象
- map：包含 dataPath、totalPath、success、message 等
- submitForm：同 request
- method、headers：全局请求方法与请求头
- format：包含 formatCurrent（函数或字符串表达式）

**章节来源**
- [types/ProTable.d.ts:3-58](file://types/ProTable.d.ts#L3-L58)

## 依赖关系分析
- 组件依赖 request.js 进行请求适配
- request.js 依赖 src/libs/http.js 提供的 axios 实例与拦截器
- 组件通过 lodash 的 get/has/map 等工具进行数据路径提取与结构处理

```mermaid
graph LR
PT["ProTable.vue"] --> REQ["request.js"]
REQ --> HTTP["http.js"]
PT --> LODASH["lodash-es"]
REQ --> LODASH
```

**图表来源**
- [packages/components/ProTable.vue:156-165](file://packages/components/ProTable.vue#L156-L165)
- [packages/libs/request.js:1-78](file://packages/libs/request.js#L1-L78)
- [src/libs/http.js:1-70](file://src/libs/http.js#L1-L70)

**章节来源**
- [packages/components/ProTable.vue:156-165](file://packages/components/ProTable.vue#L156-L165)
- [packages/libs/request.js:1-78](file://packages/libs/request.js#L1-L78)
- [src/libs/http.js:1-70](file://src/libs/http.js#L1-L70)

## 性能考量
- 合理使用 keys：仅传递必要字段，减少请求体大小
- 分页策略：避免一次性加载过多数据，结合 totalPath 与分页控件使用
- 请求缓存：可在自定义 request 函数中实现缓存逻辑（需自行扩展）
- 大数据量渲染：建议配合虚拟滚动或服务端分页，避免前端渲染压力

## 故障排查指南
- 数据路径不匹配
  - 现象：表格为空，total 为 0，提示“请检查数据路径和分页配置”
  - 排查：确认 map.dataPath 与 map.totalPath 是否正确指向响应体
  - 参考：[packages/components/ProTable.vue:707-720](file://packages/components/ProTable.vue#L707-L720)
- 成功条件不满足
  - 现象：successHandle 校验失败，触发 error 提示
  - 排查：配置 map.success 或确保响应体包含 success 字段
  - 参考：[packages/components/ProTable.vue:782-798](file://packages/components/ProTable.vue#L782-L798)
- 请求头缺失或鉴权失败
  - 现象：401/403 或统一错误提示
  - 排查：确认 Authorization 是否注入，headers 是否正确传递
  - 参考：[src/libs/http.js:12-28](file://src/libs/http.js#L12-L28)
- URL 占位替换异常
  - 现象：URL 不完整或 404
  - 排查：确认占位符 ${key} 对应的值存在于 datas 中
  - 参考：[packages/libs/request.js:23-31](file://packages/libs/request.js#L23-L31)
- 删除失败或未刷新
  - 现象：删除后数据未更新
  - 排查：确认删除接口返回 success 且响应体包含 totalPath
  - 参考：[packages/components/ProTable.vue:569-588](file://packages/components/ProTable.vue#L569-L588)

**章节来源**
- [packages/components/ProTable.vue:707-720](file://packages/components/ProTable.vue#L707-L720)
- [packages/components/ProTable.vue:782-798](file://packages/components/ProTable.vue#L782-L798)
- [src/libs/http.js:12-28](file://src/libs/http.js#L12-L28)
- [packages/libs/request.js:23-31](file://packages/libs/request.js#L23-L31)
- [packages/components/ProTable.vue:569-588](file://packages/components/ProTable.vue#L569-L588)

## 结论
ProTable 的数据配置围绕 request、map、format、submitForm 等属性展开，具备灵活的远程请求适配、强大的数据路径映射与成功条件校验能力。通过合理配置这些属性，可以快速对接不同风格的后端接口，并在前端实现一致的交互体验。

## 附录

### 实际配置示例与最佳实践
- 远程表格数据
  - 配置 request 为字符串或对象，设置 map.dataPath 与 map.totalPath
  - 参考：[src/views/ProTable.vue:26-96](file://src/views/ProTable.vue#L26-L96)
- 自定义分页键与表达式
  - 设置 map.current 与 map.pageSize，使用 format.formatCurrent 覆盖 current 计算
  - 参考：[packages/components/ProTable.vue:669-687](file://packages/components/ProTable.vue#L669-L687)
- 成功条件与消息映射
  - 通过 map.success 与 map.message 控制成功/失败提示
  - 参考：[packages/components/ProTable.vue:782-798](file://packages/components/ProTable.vue#L782-L798)
- 提交表单
  - 新增/编辑使用 submitForm 或 request，删除使用列动作中的 val.request
  - 参考：[packages/components/ProTable.vue:799-830](file://packages/components/ProTable.vue#L799-L830)

**章节来源**
- [src/views/ProTable.vue:26-96](file://src/views/ProTable.vue#L26-L96)
- [packages/components/ProTable.vue:669-687](file://packages/components/ProTable.vue#L669-L687)
- [packages/components/ProTable.vue:782-798](file://packages/components/ProTable.vue#L782-L798)
- [packages/components/ProTable.vue:799-830](file://packages/components/ProTable.vue#L799-L830)