# 工具栏与分页

<cite>
**本文引用的文件**   
- [ProTable.vue](file://packages/components/ProTable.vue)
- [ProTable.d.ts](file://types/ProTable.d.ts)
- [ProTable.vue（核心版）](file://packages/core/src/components/ProTable.vue)
- [RowSetting.vue](file://packages/components/ProTable/RowSetting.vue)
- [ProTypeItem.vue](file://packages/components/ProTypeItem/ProTypeItem.vue)
- [ProTable.vue（示例页面）](file://src/views/ProTable.vue)
- [proTable.css（组件级）](file://packages/components/ProTable/proTable.css)
- [proTable.css（核心版）](file://packages/core/src/components/ProTable/proTable.css)
- [fix.css（全局修复）](file://packages/fix.css)
- [locale index（国际化）](file://src/locale/index.js)
- [it-IT 语言包（组件级）](file://lib/locales/it-IT.js)
- [it-IT 语言包（核心版）](file://packages/core/src/locale/lang/it-IT.js)
- [it-IT 语言包（打包版）](file://packages/locale/lang/it-IT.js)
</cite>

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

## 简介
本篇文档聚焦 ProTable 的“工具栏与分页”能力，系统讲解以下内容：
- 工具栏配置与使用：内置按钮、自定义按钮、布局控制、图标与文案定制
- 分页组件配置：分页大小设置、分页跳转、总页数显示、页码变更逻辑
- 全屏与行设置功能：全屏切换、列显隐与拖拽排序、本地持久化
- 样式定制与交互体验优化建议：主题适配、可访问性、动画与过渡

## 项目结构
围绕工具栏与分页的相关文件分布如下：
- 组件实现：packages/components/ProTable.vue（主组件）、packages/components/ProTable/RowSetting.vue（行设置）、packages/components/ProTypeItem/ProTypeItem.vue（渲染器）
- 类型定义：types/ProTable.d.ts（对外 API）
- 示例页面：src/views/ProTable.vue（演示配置与用法）
- 国际化：src/locale/index.js、lib/locales/it-IT.js 及核心版语言包
- 样式：packages/components/ProTable/proTable.css、packages/core/src/components/ProTable/proTable.css、packages/fix.css

```mermaid
graph TB
subgraph "组件层"
PT["ProTable.vue"]
RS["RowSetting.vue"]
PTI["ProTypeItem.vue"]
end
subgraph "类型与示例"
TYP["ProTable.d.ts"]
DEMO["src/views/ProTable.vue"]
end
subgraph "国际化"
LOCALE_IDX["src/locale/index.js"]
LOCALE_IT["lib/locales/it-IT.js"]
LOCALE_CORE_IT["packages/core/src/locale/lang/it-IT.js"]
LOCALE_PKG_IT["packages/locale/lang/it-IT.js"]
end
subgraph "样式"
CSS_COMP["packages/components/ProTable/proTable.css"]
CSS_CORE["packages/core/src/components/ProTable/proTable.css"]
FIX_CSS["packages/fix.css"]
end
PT --> RS
PT --> PTI
DEMO --> PT
TYP --> PT
LOCALE_IDX --> PT
LOCALE_IT --> PT
LOCALE_CORE_IT --> PT
LOCALE_PKG_IT --> PT
CSS_COMP --> PT
CSS_CORE --> PT
FIX_CSS --> PT
```

**图表来源**
- [ProTable.vue:1-152](file://packages/components/ProTable.vue#L1-L152)
- [RowSetting.vue:1-79](file://packages/components/ProTable/RowSetting.vue#L1-L79)
- [ProTypeItem.vue:1-132](file://packages/components/ProTypeItem/ProTypeItem.vue#L1-L132)
- [ProTable.d.ts:1-59](file://types/ProTable.d.ts#L1-L59)
- [ProTable.vue（示例页面）:1-306](file://src/views/ProTable.vue#L1-L306)
- [proTable.css（组件级）:1-20](file://packages/components/ProTable/proTable.css#L1-L20)
- [proTable.css（核心版）:1-19](file://packages/core/src/components/ProTable/proTable.css#L1-L19)
- [fix.css（全局修复）:1-7](file://packages/fix.css#L1-L7)

**章节来源**
- [ProTable.vue:1-152](file://packages/components/ProTable.vue#L1-L152)
- [ProTable.d.ts:1-59](file://types/ProTable.d.ts#L1-L59)
- [ProTable.vue（示例页面）:1-306](file://src/views/ProTable.vue#L1-L306)

## 核心组件
- ProTable：提供工具栏、搜索、表格主体、分页、弹窗表单等能力；支持国际化、本地持久化、全屏切换
- RowSetting：提供列显隐勾选、拖拽排序、重置、本地存储
- ProTypeItem：通用渲染器，支持函数式渲染、表达式计算、插槽转换
- 类型定义：对外暴露 columns、hide、map、request、submitForm、search、form、table 等配置项

**章节来源**
- [ProTable.vue:154-428](file://packages/components/ProTable.vue#L154-L428)
- [RowSetting.vue:81-262](file://packages/components/ProTable/RowSetting.vue#L81-L262)
- [ProTypeItem.vue:7-125](file://packages/components/ProTypeItem/ProTypeItem.vue#L7-L125)
- [ProTable.d.ts:3-58](file://types/ProTable.d.ts#L3-L58)

## 架构总览
ProTable 将“工具栏”“搜索”“表格”“分页”“弹窗表单”按区域组织，通过 UIEditFrame 提供可视化编辑能力；工具栏由内置动作与自定义渲染组成；分页基于 iView Page 组件，支持页码与页大小变更。

```mermaid
graph TB
UI["UIEditFrame<br/>可视化编辑"] --> TB["工具栏区域"]
UI --> SRCH["搜索区域"]
UI --> TBL["表格区域"]
UI --> PG["分页区域"]
TB --> BTN_NEW["新建按钮"]
TB --> BTN_REFRESH["刷新按钮"]
TB --> BTN_FULLSCREEN["全屏按钮"]
TB --> ROWSET["行设置按钮<br/>RowSetting"]
SRCH --> PROSEAR["ProSearch"]
TBL --> ITBL["iView Table"]
PG --> IPG["iView Page"]
ROWSET --> LS["localStorage<br/>列配置持久化"]
```

**图表来源**
- [ProTable.vue:1-152](file://packages/components/ProTable.vue#L1-L152)
- [RowSetting.vue:1-79](file://packages/components/ProTable/RowSetting.vue#L1-L79)

## 详细组件分析

### 工具栏配置与使用
- 内置动作
  - 新建：触发新建流程，打开表单弹窗
  - 刷新：重新拉取数据
  - 全屏：切换全屏模式，监听全屏状态变化，动态添加/移除 body 类名
  - 行设置：打开列显隐与排序面板，支持重置与本地持久化
- 自定义动作
  - 支持通过 toolBarActions 传入字符串或对象形式的自定义项
  - 字符串：从内置动作集中匹配
  - 对象：需提供 key 与 renderItem 或 render 方法，用于自定义按钮、图标、文案
- 布局控制
  - 通过 UIEditFrame 的 type="toolBar" 控制可视化编辑开关
  - 可通过 hide.toolBar 控制整体隐藏
- 国际化
  - 文案来自 t("pro.common.xxx")，支持多语言

```mermaid
sequenceDiagram
participant U as "用户"
participant PT as "ProTable"
participant FS as "screenfull"
participant RS as "RowSetting"
U->>PT : 点击“全屏”
PT->>FS : toggle(容器元素)
FS-->>PT : 全屏状态变更
PT->>PT : 切换 body 类名
U->>RS : 打开“行设置”
RS-->>U : 展示列勾选与拖拽排序
U->>RS : 勾选/拖拽/重置
RS-->>PT : 触发 input 事件更新列显示
```

**图表来源**
- [ProTable.vue:325-345](file://packages/components/ProTable.vue#L325-L345)
- [ProTable.vue:444-454](file://packages/components/ProTable.vue#L444-L454)
- [RowSetting.vue:119-167](file://packages/components/ProTable/RowSetting.vue#L119-L167)

**章节来源**
- [ProTable.vue:283-383](file://packages/components/ProTable.vue#L283-L383)
- [ProTable.vue:444-454](file://packages/components/ProTable.vue#L444-L454)
- [RowSetting.vue:119-167](file://packages/components/ProTable/RowSetting.vue#L119-L167)

### 分页组件配置
- 组件绑定
  - v-model="page.current"：双向绑定当前页
  - :total="total"：总记录数
  - :page-size="page.pageSize"：当前页大小
  - @on-change="search"：页码变更触发查询
  - @on-page-size-change="pageSizeChange"：页大小变更处理
  - show-total、show-sizer：显示总数与页大小选择
- 页码与页大小变更逻辑
  - 页码变更：重置到第一页并拉取数据
  - 页大小变更：若当前页为第一页则立即拉取；否则仅更新页大小
- 请求参数映射
  - 通过 map.current、map.pageSize、map.dataPath、map.totalPath 控制请求体字段与数据路径
  - 支持 format.formatCurrent 自定义页码格式化表达式

```mermaid
flowchart TD
Start(["开始"]) --> ChangePage["页码变更"]
ChangePage --> ResetCurrent["重置当前页为1"]
ResetCurrent --> Fetch["发起请求"]
Fetch --> UpdateData["更新数据与总数"]
UpdateData --> End(["结束"])
Start --> ChangeSize["页大小变更"]
ChangeSize --> IsFirst{"当前页为1？"}
IsFirst --> |是| Fetch2["立即发起请求"]
IsFirst --> |否| UpdateSize["仅更新页大小"]
Fetch2 --> End
UpdateSize --> End
```

**图表来源**
- [ProTable.vue:605-648](file://packages/components/ProTable.vue#L605-L648)
- [ProTable.vue:613-618](file://packages/components/ProTable.vue#L613-L618)

**章节来源**
- [ProTable.vue:105-116](file://packages/components/ProTable.vue#L105-L116)
- [ProTable.vue:605-648](file://packages/components/ProTable.vue#L605-L648)
- [ProTable.vue:665-741](file://packages/components/ProTable.vue#L665-L741)

### 全屏功能
- 切换方式：点击全屏图标，调用 screenfull.toggle 切换
- 状态监听：监听 change 事件，同步 fullscreen 状态
- 样式联动：根据全屏状态为 body 添加/移除类名，便于主题适配

**章节来源**
- [ProTable.vue:325-345](file://packages/components/ProTable.vue#L325-L345)
- [ProTable.vue:444-454](file://packages/components/ProTable.vue#L444-L454)
- [proTable.css（组件级）:947-956](file://packages/components/ProTable/proTable.css#L947-L956)
- [proTable.css（核心版）:947-956](file://packages/core/src/components/ProTable/proTable.css#L947-L956)

### 行设置功能
- 功能点
  - 列显隐勾选：支持全选/半选状态
  - 拖拽排序：通过 vuedraggable 实现
  - 重置：清除本地存储，恢复初始列配置
  - 本地持久化：localStorage 存储键值为 ProRowSetting:{storage}
- 交互流程
  - 打开下拉菜单
  - 勾选/取消勾选列
  - 拖拽调整顺序
  - 触发 input 事件，向父组件回传排序后的列配置

```mermaid
sequenceDiagram
participant U as "用户"
participant RS as "RowSetting"
participant LS as "localStorage"
U->>RS : 打开下拉菜单
U->>RS : 勾选/取消勾选
RS-->>U : 更新勾选状态
U->>RS : 拖拽排序
RS-->>U : 更新排序
RS->>LS : 写入持久化
RS-->>PT : 触发 input 事件
```

**图表来源**
- [RowSetting.vue:119-167](file://packages/components/ProTable/RowSetting.vue#L119-L167)
- [RowSetting.vue:197-260](file://packages/components/ProTable/RowSetting.vue#L197-L260)

**章节来源**
- [RowSetting.vue:81-262](file://packages/components/ProTable/RowSetting.vue#L81-L262)

### 工具栏动作自定义配置
- 自定义按钮
  - 通过 toolBarActions 传入对象项，提供 key 与 renderItem/render
  - 渲染器内部使用 ProTypeItem 支持函数式渲染与表达式
- 图标与文案
  - 内置按钮使用 iView Icon 与 t("pro.common.xxx") 国际化文案
  - 自定义按钮可自由指定图标与文案
- 布局控制
  - UIEditFrame 的 type="toolBar" 控制可视化编辑
  - hide.toolBar 控制整体隐藏

**章节来源**
- [ProTable.vue:283-383](file://packages/components/ProTable.vue#L283-L383)
- [ProTypeItem.vue:51-124](file://packages/components/ProTypeItem/ProTypeItem.vue#L51-L124)

### 分页与工具栏的样式定制
- 组件级样式
  - Modal 进出场动画：.pro-modal-enter-active、.pro-modal-leave-active 等
  - 全屏容器背景与 body 类名：.pro-table-container、:global(.pro-table-fullscreen)
- 全局修复
  - 修复固定阴影层的指针事件问题：.ivu-table-fixed-shadow
- 主题适配建议
  - 使用 CSS 变量或覆盖类名的方式统一按钮、图标、分页尺寸
  - 在全屏状态下通过 body 类名对弹窗、表格等进行额外样式约束

**章节来源**
- [proTable.css（组件级）:1-20](file://packages/components/ProTable/proTable.css#L1-L20)
- [proTable.css（核心版）:1-19](file://packages/core/src/components/ProTable/proTable.css#L1-L19)
- [fix.css（全局修复）:1-7](file://packages/fix.css#L1-L7)

### 交互体验优化建议
- 工具栏
  - 为每个按钮提供 Tooltip 提示，提升可发现性
  - 刷新按钮在请求期间禁用或显示加载态
  - 全屏切换时保持弹窗位置稳定（参考 transfer 属性）
- 分页
  - 当前页为最后一页且删除最后一项时，自动回退一页，避免空页
  - 页大小变更后，若当前页为第一页则立即刷新，否则提示用户
- 国际化
  - 通过 src/locale/index.js 注入多语言，确保工具栏文案与分页文案一致
  - 语言包位于 lib/locales/it-IT.js、packages/core/src/locale/lang/it-IT.js、packages/locale/lang/it-IT.js

**章节来源**
- [ProTable.vue:569-648](file://packages/components/ProTable.vue#L569-L648)
- [locale index（国际化）:1-18](file://src/locale/index.js#L1-L18)
- [it-IT 语言包（组件级）:1-47](file://lib/locales/it-IT.js#L1-L47)
- [it-IT 语言包（核心版）:1-47](file://packages/core/src/locale/lang/it-IT.js#L1-L47)
- [it-IT 语言包（打包版）:1-47](file://packages/locale/lang/it-IT.js#L1-L47)

## 依赖关系分析
- 组件耦合
  - ProTable 依赖 RowSetting、ProTypeItem、UIEditFrame、iView Table/Page、screenfull
  - RowSetting 依赖 vuedraggable、localStorage
- 外部依赖
  - lodash-es：深拷贝、过滤、映射、合并等
  - screenfull：全屏控制
  - vuedraggable：拖拽排序
- 接口契约
  - request、submitForm 支持字符串、函数、对象三种形式
  - map 与 format 控制请求参数与响应解析

```mermaid
graph LR
PT["ProTable"] --> RS["RowSetting"]
PT --> PTI["ProTypeItem"]
PT --> UI["UIEditFrame"]
PT --> IF["iView Table/Page"]
PT --> SF["screenfull"]
RS --> VD["vuedraggable"]
PT --> LO["lodash-es"]
PT --> SC["screenfull"]
```

**图表来源**
- [ProTable.vue:154-165](file://packages/components/ProTable.vue#L154-L165)
- [RowSetting.vue:82-90](file://packages/components/ProTable/RowSetting.vue#L82-L90)

**章节来源**
- [ProTable.vue:154-165](file://packages/components/ProTable.vue#L154-L165)
- [RowSetting.vue:82-90](file://packages/components/ProTable/RowSetting.vue#L82-L90)

## 性能考量
- 渲染优化
  - 使用 columnFilter 过滤不显示列，减少渲染节点
  - 表格列的动态渲染通过 ProTypeItem 延迟执行，避免不必要的计算
- 请求节流
  - 页大小变更时，仅在第一页立即刷新，其他页延迟至用户切换
- 存储策略
  - 行设置配置写入 localStorage，避免每次初始化重复计算

**章节来源**
- [ProTable.vue:490-554](file://packages/components/ProTable.vue#L490-L554)
- [ProTable.vue:613-618](file://packages/components/ProTable.vue#L613-L618)
- [RowSetting.vue:159-164](file://packages/components/ProTable/RowSetting.vue#L159-L164)

## 故障排查指南
- 分页不生效
  - 检查 hide.page 是否被设为 true
  - 确认 total 是否正确赋值（来自 map.totalPath）
- 页大小变更无效
  - 确认 @on-page-size-change 绑定到 pageSizeChange
  - 若当前页非第一页，页大小变更不会立即刷新
- 全屏无效果
  - 确认 screenfull 启用且容器元素存在
  - 检查 body 类名切换逻辑是否被覆盖
- 行设置不持久化
  - 检查 storage 配置与 localStorage 权限
  - 确认 input 事件是否正确回传排序后的列配置

**章节来源**
- [ProTable.vue:105-116](file://packages/components/ProTable.vue#L105-L116)
- [ProTable.vue:613-618](file://packages/components/ProTable.vue#L613-L618)
- [ProTable.vue:444-454](file://packages/components/ProTable.vue#L444-L454)
- [RowSetting.vue:159-164](file://packages/components/ProTable/RowSetting.vue#L159-L164)

## 结论
ProTable 的工具栏与分页能力通过清晰的组件边界与灵活的配置项实现高可用与可扩展性。借助 RowSetting 的本地持久化与拖拽排序、ProTypeItem 的通用渲染器、以及完善的国际化与样式体系，开发者可以快速构建符合业务需求的数据表格界面，并在全屏、分页、列管理等方面获得良好的用户体验。

## 附录
- 示例页面展示了工具栏动作、分页配置、请求映射与搜索区域的基本用法
- 类型定义明确了对外 API 的关键字段与默认值

**章节来源**
- [ProTable.vue（示例页面）:26-96](file://src/views/ProTable.vue#L26-L96)
- [ProTable.d.ts:3-58](file://types/ProTable.d.ts#L3-L58)