# 核心包 (@pro-iview/core)

<cite>
**本文引用的文件**
- [packages/core/src/index.js](file://packages/core/src/index.js)
- [packages/core/src/components/index.js](file://packages/core/src/components/index.js)
- [packages/core/src/ui-adapter/index.ts](file://packages/core/src/ui-adapter/index.ts)
- [packages/core/src/ui-adapter/inject.ts](file://packages/core/src/ui-adapter/inject.ts)
- [packages/core/src/ui-adapter/types.ts](file://packages/core/src/ui-adapter/types.ts)
- [packages/core/src/locale/index.js](file://packages/core/src/locale/index.js)
- [packages/core/src/directive/index.js](file://packages/core/src/directive/index.js)
- [packages/core/src/fix.css](file://packages/core/src/fix.css)
- [packages/core/src/components/ProTable.vue](file://packages/core/src/components/ProTable.vue)
- [packages/core/src/components/ProForm.vue](file://packages/core/src/components/ProForm.vue)
- [packages/core/src/components/ProModal.vue](file://packages/core/src/components/ProModal.vue)
- [packages/core/src/components/ProTableEdit.vue](file://packages/core/src/components/ProTableEdit.vue)
- [packages/core/package.json](file://packages/core/package.json)
</cite>

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

## 简介
@pro-iview/core 是一个“无 UI 依赖”的核心逻辑层包，旨在通过统一的 UI 适配器机制解耦具体 UI 组件库（如 Element Plus、View UI Plus 等），使核心业务能力（表格、表单、搜索、弹窗等）与底层 UI 组件实现完全解耦。该包提供安装器模式、国际化、指令、全局样式修复以及核心组件导出，便于在不同 UI 生态下复用同一套业务逻辑。

## 项目结构
核心包采用“按功能域+按职责”的组织方式：
- 安装器与入口：负责全局安装、注入工具库、注册组件与指令、国际化初始化
- UI 适配器：提供 provide/inject 机制，定义适配器接口类型
- 国际化：提供本地化文本解析与与 vue-i18n 的桥接
- 指令：集中导出自定义指令
- 组件：导出核心组件清单，包含 ProTable、ProForm、ProModal、ProTableEdit 等
- 通用资源：全局样式修复、全局混入等

```mermaid
graph TB
A["@pro-iview/core<br/>安装器与入口"] --> B["组件导出<br/>components/index.js"]
A --> C["UI 适配器<br/>ui-adapter/*"]
A --> D["国际化<br/>locale/index.js"]
A --> E["指令<br/>directive/index.js"]
A --> F["全局样式<br/>fix.css"]
B --> B1["ProTable.vue"]
B --> B2["ProForm.vue"]
B --> B3["ProModal.vue"]
B --> B4["ProTableEdit.vue"]
C --> C1["inject.ts<br/>provide/use"]
C --> C2["types.ts<br/>UIAdapter 接口"]
```

图表来源
- [packages/core/src/index.js:1-85](file://packages/core/src/index.js#L1-L85)
- [packages/core/src/components/index.js:1-23](file://packages/core/src/components/index.js#L1-L23)
- [packages/core/src/ui-adapter/index.ts:1-7](file://packages/core/src/ui-adapter/index.ts#L1-L7)
- [packages/core/src/locale/index.js:1-65](file://packages/core/src/locale/index.js#L1-L65)
- [packages/core/src/directive/index.js:1-6](file://packages/core/src/directive/index.js#L1-L6)
- [packages/core/src/fix.css:1-7](file://packages/core/src/fix.css#L1-L7)

章节来源
- [packages/core/src/index.js:1-85](file://packages/core/src/index.js#L1-L85)
- [packages/core/src/components/index.js:1-23](file://packages/core/src/components/index.js#L1-L23)

## 核心组件
本包导出的核心组件包括：
- ProTable：带搜索、工具栏、分页、弹窗表单联动的表格组件
- ProForm：支持栅格布局、分组、校验、动态渲染的表单组件
- ProModal：基于适配器的弹窗封装，统一确认/取消流程
- ProTableEdit：可编辑表格，支持新增、复制、删除、批量操作与实时校验

这些组件均通过 UI 适配器注入机制获取具体 UI 组件（如 Form、FormItem、Input、Button、Table、Modal 等），从而实现 UI 解耦。

章节来源
- [packages/core/src/components/index.js:1-23](file://packages/core/src/components/index.js#L1-L23)
- [packages/core/src/components/ProTable.vue:1-957](file://packages/core/src/components/ProTable.vue#L1-L957)
- [packages/core/src/components/ProForm.vue:1-360](file://packages/core/src/components/ProForm.vue#L1-L360)
- [packages/core/src/components/ProModal.vue:1-60](file://packages/core/src/components/ProModal.vue#L1-L60)
- [packages/core/src/components/ProTableEdit.vue:1-1301](file://packages/core/src/components/ProTableEdit.vue#L1-L1301)

## 架构总览
核心包通过安装器完成全局初始化，并通过 UI 适配器实现 UI 解耦。安装器会：
- 注入全局工具库（HTTP、日期、lodash）
- 安装 UI 适配器（可选）
- 初始化国际化（语言包与 vue-i18n）
- 注册所有核心组件与自定义指令
- 安装第三方指令库（如点击外部区域）

```mermaid
sequenceDiagram
participant App as "应用"
participant Core as "@pro-iview/core 安装器"
participant Adapter as "UI 适配器"
participant Comp as "核心组件"
participant I18n as "国际化"
App->>Core : 调用 install(app, options)
Core->>Core : 注入全局工具库与配置
alt 提供 adapter
Core->>Adapter : provideUIAdapter(adapter)
Adapter->>Adapter : install(app)
end
Core->>I18n : locale/i18n 初始化
Core->>Comp : app.component 注册组件
Core->>Core : 安装指令与第三方库
Core-->>App : 安装完成
```

图表来源
- [packages/core/src/index.js:13-57](file://packages/core/src/index.js#L13-L57)
- [packages/core/src/ui-adapter/inject.ts:15-34](file://packages/core/src/ui-adapter/inject.ts#L15-L34)

章节来源
- [packages/core/src/index.js:1-85](file://packages/core/src/index.js#L1-L85)

## 详细组件分析

### UI 适配器注入机制
- 设计目标：通过 provide/inject 在运行时注入 UI 组件库的适配器，使核心组件不直接依赖具体 UI 库
- 关键点：
  - 提供符号键用于隔离注入上下文
  - 提供 provide 函数与 use 函数，未安装适配器时抛出明确错误
  - 支持获取当前组件实例，便于在组合式 API 中使用

```mermaid
flowchart TD
Start(["组件需要 UI 组件"]) --> Use["调用 useUIAdapter()"]
Use --> Found{"是否已安装适配器？"}
Found --> |否| Throw["抛出错误：未安装 UI 适配器"]
Found --> |是| Return["返回适配器实例"]
Return --> UseUI["读取 Form/FormItem/Input/Button/Table/Modal 等"]
```

图表来源
- [packages/core/src/ui-adapter/inject.ts:23-34](file://packages/core/src/ui-adapter/inject.ts#L23-L34)
- [packages/core/src/ui-adapter/types.ts:9-48](file://packages/core/src/ui-adapter/types.ts#L9-L48)

章节来源
- [packages/core/src/ui-adapter/index.ts:1-7](file://packages/core/src/ui-adapter/index.ts#L1-L7)
- [packages/core/src/ui-adapter/inject.ts:1-43](file://packages/core/src/ui-adapter/inject.ts#L1-L43)
- [packages/core/src/ui-adapter/types.ts:1-60](file://packages/core/src/ui-adapter/types.ts#L1-L60)

### ProTable 内部机制
- 功能概览：表格 + 搜索 + 工具栏 + 分页 + 弹窗表单联动；支持列过滤、列渲染、动作按钮、全屏、行设置等
- 关键流程：
  - 请求数据：根据分页与搜索条件调用请求函数，映射数据与总数
  - 渲染列：根据列配置生成表格列，支持自定义渲染与操作列
  - 表单弹窗：新增/编辑/查看模式，联动 ProForm 进行校验与提交
  - 工具栏：内置新建、刷新、全屏、行设置等按钮，支持自定义扩展
  - 分页：支持页码与页大小变更，自动触发查询

```mermaid
sequenceDiagram
participant UI as "用户界面"
participant PT as "ProTable"
participant Req as "请求封装"
participant PF as "ProForm"
participant AD as "适配器"
UI->>PT : 触发搜索/分页/工具栏
PT->>Req : 组装分页与查询参数
Req-->>PT : 返回数据与总数
PT->>PT : 映射数据、计算列与动作
UI->>PT : 新增/编辑/删除
PT->>PF : 打开弹窗并传入表单配置
PF->>AD : 使用适配器组件渲染
PF-->>PT : 提交结果
PT->>Req : 刷新数据或局部更新
```

图表来源
- [packages/core/src/components/ProTable.vue:605-800](file://packages/core/src/components/ProTable.vue#L605-L800)
- [packages/core/src/components/ProForm.vue:154-328](file://packages/core/src/components/ProForm.vue#L154-L328)

章节来源
- [packages/core/src/components/ProTable.vue:1-957](file://packages/core/src/components/ProTable.vue#L1-L957)

### ProForm 内部机制
- 功能概览：支持栅格布局、分组、标签位置、多列展示、动态渲染与校验
- 关键点：
  - 通过 useUIAdapter 获取 Form、FormItem、Input、Button、Icon 等组件
  - 基于列配置生成表单项，支持自定义渲染与规则转换
  - 提交时进行字段级校验，再发起请求并回调完成处理

```mermaid
sequenceDiagram
participant PT as "ProTable"
participant PF as "ProForm"
participant AD as "适配器"
participant Val as "校验器"
PT->>PF : 打开弹窗并传入 columns/modelValue
PF->>AD : useUIAdapter().Form/FormItem/Input/Button/Icon
PF->>Val : 校验字段规则
Val-->>PF : 校验结果
PF-->>PT : 提交成功/失败
```

图表来源
- [packages/core/src/components/ProForm.vue:154-328](file://packages/core/src/components/ProForm.vue#L154-L328)

章节来源
- [packages/core/src/components/ProForm.vue:1-360](file://packages/core/src/components/ProForm.vue#L1-L360)

### ProModal 内部机制
- 功能概览：统一弹窗的确认/取消流程，支持异步确认与加载状态
- 关键点：
  - 通过 v-model 控制显隐
  - onOk/onCancel 事件透传到父组件，由父组件决定关闭时机
  - 使用适配器的 Modal/Button 组件进行渲染

章节来源
- [packages/core/src/components/ProModal.vue:1-60](file://packages/core/src/components/ProModal.vue#L1-L60)

### ProTableEdit 内部机制
- 功能概览：可编辑表格，支持新增、复制、删除、批量操作、实时校验与保存
- 关键点：
  - 通过 useUIAdapter 获取 Message、Modal 等反馈组件
  - 使用 async-validator 对单元格进行规则校验
  - 通过 editList 记录编辑状态，支持键盘快捷键与焦点切换
  - 保存时对比初始值与当前值，仅提交变更项

章节来源
- [packages/core/src/components/ProTableEdit.vue:1-1301](file://packages/core/src/components/ProTableEdit.vue#L1-L1301)

## 依赖关系分析
- 安装器依赖：
  - axios：网络请求
  - lodash-es：数据处理
  - dayjs：日期处理
  - vue3-click-away：点击外部区域指令
  - vue-i18n：国际化
  - vuedraggable：拖拽排序
  - vue：框架基础
- 组件依赖：
  - ProTable/ProForm/ProModal/ProTableEdit 通过 useUIAdapter 获取 UI 组件
  - 共享工具：自定义请求封装、通用工具函数
  - 国际化：t 函数与本地化资源

```mermaid
graph LR
Core["@pro-iview/core"] --> Axios["axios"]
Core --> Lodash["lodash-es"]
Core --> Dayjs["dayjs"]
Core --> VCA["vue3-click-away"]
Core --> I18n["vue-i18n"]
Core --> Draggable["vuedraggable"]
Core --> Vue["vue"]
PT["ProTable"] --> Adapter["UI 适配器"]
PF["ProForm"] --> Adapter
PM["ProModal"] --> Adapter
PTE["ProTableEdit"] --> Adapter
```

图表来源
- [packages/core/package.json:23-46](file://packages/core/package.json#L23-L46)
- [packages/core/src/index.js:1-11](file://packages/core/src/index.js#L1-L11)

章节来源
- [packages/core/package.json:1-46](file://packages/core/package.json#L1-L46)

## 性能考量
- 组件渲染优化
  - ProTable 通过列过滤与延迟渲染减少不必要的 DOM 开销
  - ProTableEdit 使用 editList 精准记录编辑状态，避免全量重渲染
- 数据处理优化
  - 使用 lodash-es 进行深拷贝与合并，避免副作用
  - 请求封装统一处理分页与查询参数，减少重复逻辑
- 国际化与指令
  - 国际化桥接优先使用组件内 $t，回退至 vue-i18n global，避免重复合并消息

[本节为通用建议，无需特定文件来源]

## 故障排查指南
- 未安装 UI 适配器
  - 现象：调用 useUIAdapter 抛出错误
  - 处理：在安装核心包时传入 adapter，并确保 adapter.install(app) 正常执行
  - 参考：[packages/core/src/ui-adapter/inject.ts:23-34](file://packages/core/src/ui-adapter/inject.ts#L23-L34)
- 国际化未生效
  - 现象：t 函数无法解析本地化文本
  - 处理：确保 locale/i18n 初始化顺序正确，且 vue-i18n 已注册
  - 参考：[packages/core/src/locale/index.js:12-33](file://packages/core/src/locale/index.js#L12-L33)
- 表单校验异常
  - 现象：正则表达式规则未生效
  - 处理：在规则中将字符串正则转换为 RegExp 对象
  - 参考：[packages/core/src/components/ProForm.vue:270-277](file://packages/core/src/components/ProForm.vue#L270-L277)
- 表格请求失败
  - 现象：数据为空或总数为 0
  - 处理：检查请求函数、数据路径映射与分页字段
  - 参考：[packages/core/src/components/ProTable.vue:665-741](file://packages/core/src/components/ProTable.vue#L665-L741)

章节来源
- [packages/core/src/ui-adapter/inject.ts:23-34](file://packages/core/src/ui-adapter/inject.ts#L23-L34)
- [packages/core/src/locale/index.js:12-33](file://packages/core/src/locale/index.js#L12-L33)
- [packages/core/src/components/ProForm.vue:270-277](file://packages/core/src/components/ProForm.vue#L270-L277)
- [packages/core/src/components/ProTable.vue:665-741](file://packages/core/src/components/ProTable.vue#L665-L741)

## 结论
@pro-iview/core 通过“安装器 + UI 适配器 + 国际化 + 指令 + 组件”五位一体的设计，在不绑定具体 UI 库的前提下，提供了完整的表格、表单、弹窗与可编辑表格能力。其核心价值在于：
- UI 解耦：通过适配器机制实现 UI 与业务逻辑分离
- 可扩展：支持自定义适配器与 UI 组件替换
- 易集成：安装器统一初始化，组件即插即用
- 可维护：清晰的职责划分与稳定的 API 设计

[本节为总结性内容，无需特定文件来源]

## 附录

### 使用示例与最佳实践
- 安装与初始化
  - 在应用中安装核心包，并传入 UI 适配器与国际化配置
  - 参考：[packages/core/src/index.js:13-57](file://packages/core/src/index.js#L13-L57)
- 自定义适配器
  - 实现 UIAdapter 接口，提供 Form、FormItem、Input、Button、Table、Modal、Message、Icon、Page 等组件与 install 方法
  - 参考：[packages/core/src/ui-adapter/types.ts:9-48](file://packages/core/src/ui-adapter/types.ts#L9-L48)
- 在组件中使用适配器
  - 在组合式 API 中调用 useUIAdapter() 获取组件库实例
  - 参考：[packages/core/src/components/ProForm.vue:159-173](file://packages/core/src/components/ProForm.vue#L159-L173)
- 国际化
  - 通过 locale/i18n 初始化语言包与 vue-i18n
  - 参考：[packages/core/src/locale/index.js:52-64](file://packages/core/src/locale/index.js#L52-L64)
- 全局样式修复
  - 引入 fix.css 以解决特定 UI 库的交互问题
  - 参考：[packages/core/src/fix.css:1-7](file://packages/core/src/fix.css#L1-L7)

章节来源
- [packages/core/src/index.js:13-57](file://packages/core/src/index.js#L13-L57)
- [packages/core/src/ui-adapter/types.ts:9-48](file://packages/core/src/ui-adapter/types.ts#L9-L48)
- [packages/core/src/components/ProForm.vue:159-173](file://packages/core/src/components/ProForm.vue#L159-L173)
- [packages/core/src/locale/index.js:52-64](file://packages/core/src/locale/index.js#L52-L64)
- [packages/core/src/fix.css:1-7](file://packages/core/src/fix.css#L1-L7)