# 迁移指南

<cite>
**本文引用的文件**
- [MIGRATION.md](file://MIGRATION.md)
- [ARCHITECTURE_SUMMARY.md](file://ARCHITECTURE_SUMMARY.md)
- [README.md](file://README.md)
- [package.json](file://package.json)
- [turbo.json](file://turbo.json)
- [src/main.js](file://src/main.js)
- [packages/index.js](file://packages/index.js)
- [packages/compat/index.js](file://packages/compat/index.js)
- [packages/core/src/index.js](file://packages/core/src/index.js)
- [packages/adapters/view-ui-plus/src/index.js](file://packages/adapters/view-ui-plus/src/index.js)
- [packages/adapters/element-plus/src/index.js](file://packages/adapters/element-plus/src/index.js)
- [src/views/ProTable.vue](file://src/views/ProTable.vue)
- [src/views/ProForm.vue](file://src/views/ProForm.vue)
- [src/App.vue](file://src/App.vue)
- [types/index.d.ts](file://types/index.d.ts)
</cite>

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

## 简介
本迁移指南面向从 Pro-IVIEW V1.x 升级到 V3（基于 Monorepo 的多 UI 库适配架构）的团队与个人开发者。V3 提供三种使用方式：
- 零改动升级：通过向后兼容包 pro_iview_v3@2.x 保持原有 API 不变；
- 新架构迁移：拆分为 @pro-iview/core + UI 适配器（view-ui-plus 或 element-plus），获得更强的可扩展性与解耦能力；
- 直接采用新方式：按需选择 UI 库并注入对应适配器。

同时，V3 引入了 UI 适配器模式、Monorepo 管理、样式抽象、国际化与全局工具属性等能力，帮助在多 UI 库之间平滑切换，并为未来扩展更多 UI 库奠定基础。

章节来源
- [MIGRATION.md:156-188](file://MIGRATION.md#L156-L188)
- [ARCHITECTURE_SUMMARY.md:122-174](file://ARCHITECTURE_SUMMARY.md#L122-L174)

## 项目结构
V3 采用 Monorepo 架构，核心目录与职责如下：
- packages/core：核心业务逻辑与组件，不绑定具体 UI 库；
- packages/adapters：UI 适配器，分别对接 view-ui-plus 与 element-plus；
- packages/compat：向后兼容包，封装 core + view-ui-plus 适配器，保持 v1.x 使用方式；
- packages/index.js：传统打包入口（兼容旧项目）；
- src：示例应用与演示组件（ProTable、ProForm 等）；
- types：TypeScript 类型声明；
- turbo.json：Turborepo 构建管线配置；
- package.json：根级依赖与脚本。

```mermaid
graph TB
subgraph "根项目"
Pkg["package.json<br/>脚本与依赖"]
Turbo["turbo.json<br/>构建管线"]
Readme["README.md"]
end
subgraph "packages"
Core["@pro-iview/core<br/>核心包"]
Adapters["adapters/<br/>UI 适配器"]
Compat["compat/<br/>向后兼容包"]
Legacy["packages/index.js<br/>传统入口"]
end
subgraph "适配器"
VUEPlus["@pro-iview/view-ui-plus<br/>适配器"]
EPlus["@pro-iview/element-plus<br/>适配器"]
end
subgraph "示例应用"
SrcMain["src/main.js<br/>示例应用入口"]
Views["src/views/*.vue<br/>演示组件"]
end
Pkg --> Core
Pkg --> Adapters
Pkg --> Compat
Pkg --> Legacy
Turbo --> Core
Turbo --> Adapters
Turbo --> Compat
Core --> VUEPlus
Core --> EPlus
Compat --> Core
Compat --> VUEPlus
SrcMain --> Legacy
SrcMain --> Core
Views --> Core
```

图表来源
- [package.json:8-19](file://package.json#L8-L19)
- [turbo.json:1-18](file://turbo.json#L1-L18)
- [packages/index.js:1-69](file://packages/index.js#L1-L69)
- [packages/compat/index.js:1-40](file://packages/compat/index.js#L1-L40)
- [packages/core/src/index.js:1-85](file://packages/core/src/index.js#L1-L85)
- [packages/adapters/view-ui-plus/src/index.js:1-64](file://packages/adapters/view-ui-plus/src/index.js#L1-L64)
- [packages/adapters/element-plus/src/index.js:1-109](file://packages/adapters/element-plus/src/index.js#L1-L109)
- [src/main.js:1-14](file://src/main.js#L1-L14)

章节来源
- [ARCHITECTURE_SUMMARY.md:59-120](file://ARCHITECTURE_SUMMARY.md#L59-L120)
- [package.json:1-47](file://package.json#L1-L47)
- [turbo.json:1-18](file://turbo.json#L1-L18)

## 核心组件
V3 提供以下高级组件（核心包内）：
- ProTable：高级表格（支持搜索、分页、编辑等）
- ProForm：高级表单
- ProSearch：高级搜索
- ProSelect：高级选择器
- ProTableEdit：可编辑表格
- ProModal：高级弹窗
- ProFooter：页脚
- ProCheckBox：复选框

这些组件通过 UI 适配器注入具体 UI 库的组件，从而实现核心逻辑与 UI 库解耦。

章节来源
- [MIGRATION.md:83-92](file://MIGRATION.md#L83-L92)
- [ARCHITECTURE_SUMMARY.md:66-76](file://ARCHITECTURE_SUMMARY.md#L66-L76)

## 架构总览
V3 的关键设计包括：
- UI 适配器模式：定义统一 UI 接口，核心包通过依赖注入使用 UI 组件；
- Monorepo 管理：pnpm workspace + Turborepo，支持独立构建与发布；
- 向后兼容：compat 包封装 core + view-ui-plus 适配器，保持原有 API；
- 样式抽象：核心组件使用抽象类名（pro-*），适配器负责映射到具体 UI 库类名；
- 国际化与全局工具：统一的 locale/i18n 与全局工具属性（$http/$dayjs/$lodash/$PRO_IVIEW）。

```mermaid
graph TB
Core["@pro-iview/core<br/>核心逻辑"]
Inject["provideUIAdapter()<br/>依赖注入"]
VUEPlus["@pro-iview/view-ui-plus<br/>适配器"]
EPlus["@pro-iview/element-plus<br/>适配器"]
Compat["pro_iview_v3<br/>compat 包"]
Demo["示例应用<br/>src/main.js"]
Demo --> Compat
Demo --> Core
Core --> Inject
Inject --> VUEPlus
Inject --> EPlus
Compat --> Core
Compat --> VUEPlus
```

图表来源
- [packages/core/src/index.js:13-57](file://packages/core/src/index.js#L13-L57)
- [packages/compat/index.js:12-24](file://packages/compat/index.js#L12-L24)
- [packages/adapters/view-ui-plus/src/index.js:23-61](file://packages/adapters/view-ui-plus/src/index.js#L23-L61)
- [packages/adapters/element-plus/src/index.js:66-105](file://packages/adapters/element-plus/src/index.js#L66-L105)
- [src/main.js:1-14](file://src/main.js#L1-L14)

章节来源
- [ARCHITECTURE_SUMMARY.md:122-174](file://ARCHITECTURE_SUMMARY.md#L122-L174)
- [MIGRATION.md:190-214](file://MIGRATION.md#L190-L214)

## 详细组件分析

### 向后兼容包（compat）
compat 包的作用是“零改动升级”：它自动安装 view-ui-plus 并注入 ViewUIPlusAdapter 到 core，使现有项目无需修改即可升级到 V3。

```mermaid
sequenceDiagram
participant App as "应用"
participant Compat as "compat/index.js"
participant Core as "@pro-iview/core"
participant Adapter as "@pro-iview/view-ui-plus"
participant UI as "view-ui-plus"
App->>Compat : "app.use(ProIView)"
Compat->>UI : "app.use(ViewUIPlus)"
Compat->>Core : "Core.install(app, { adapter : ViewUIPlusAdapter })"
Core->>Adapter : "provideUIAdapter(ViewUIPlusAdapter)"
Core-->>App : "注册全局组件/指令/国际化"
```

图表来源
- [packages/compat/index.js:12-24](file://packages/compat/index.js#L12-L24)
- [packages/core/src/index.js:26-31](file://packages/core/src/index.js#L26-L31)
- [packages/adapters/view-ui-plus/src/index.js:23-61](file://packages/adapters/view-ui-plus/src/index.js#L23-L61)

章节来源
- [packages/compat/index.js:1-40](file://packages/compat/index.js#L1-L40)
- [MIGRATION.md:69-81](file://MIGRATION.md#L69-L81)

### 核心包（@pro-iview/core）安装流程
核心包通过 install 方法完成：
- 注入 UI 适配器（可选）；
- 安装国际化与 i18n；
- 注册全局组件与指令；
- 提供全局工具属性（$http/$dayjs/$lodash/$PRO_IVIEW）。

```mermaid
flowchart TD
Start(["install(app, opts)"]) --> CheckAdapter{"是否提供 adapter?"}
CheckAdapter --> |是| Provide["provideUIAdapter(adapter)"]
Provide --> AdapterInstall{"adapter.install(app) 存在?"}
AdapterInstall --> |是| RunAdapterInstall["执行 adapter.install(app)"]
AdapterInstall --> |否| SkipAdapter["跳过"]
CheckAdapter --> |否| SkipAdapter
SkipAdapter --> Locale{"opts.locale/i18n?"}
RunAdapterInstall --> Locale
Locale --> |是| ApplyLocale["localeFile.use/i18n"]
Locale --> |否| Register
ApplyLocale --> Register["注册全局组件/指令/ClickAway"]
Register --> GlobalProps["设置全局工具属性"]
GlobalProps --> Done(["完成"])
```

图表来源
- [packages/core/src/index.js:13-57](file://packages/core/src/index.js#L13-L57)

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

### UI 适配器对比（view-ui-plus vs element-plus）
- 组件映射：Form/FormItem、Input、Select/Option、Button、Table、Modal、Icon 等；
- 反馈组件 API 统一：info/success/warning/error/loading/destroy；
- 图标差异：element-plus 需要单独导入图标组件，提供 CompatibleIcon 兼容层；
- 安装行为：适配器可选择在 install(app) 中进行额外注册（如注册 CompatibleIcon）。

```mermaid
classDiagram
class ViewUIPlusAdapter {
+Form
+FormItem
+Input
+Select
+Option
+Button
+Table
+Modal
+Message
+Icon
+install(app)
}
class ElementPlusAdapter {
+Form
+FormItem
+Input
+Select
+Option
+Button
+Table
+TableColumn
+Modal
+Message
+Icon
+install(app)
}
class CompatibleIcon {
+props : type
+render()
}
ElementPlusAdapter --> CompatibleIcon : "使用"
```

图表来源
- [packages/adapters/view-ui-plus/src/index.js:23-61](file://packages/adapters/view-ui-plus/src/index.js#L23-L61)
- [packages/adapters/element-plus/src/index.js:66-105](file://packages/adapters/element-plus/src/index.js#L66-L105)

章节来源
- [MIGRATION.md:190-214](file://MIGRATION.md#L190-L214)
- [packages/adapters/view-ui-plus/src/index.js:1-64](file://packages/adapters/view-ui-plus/src/index.js#L1-L64)
- [packages/adapters/element-plus/src/index.js:1-109](file://packages/adapters/element-plus/src/index.js#L1-L109)

### 示例组件（ProTable、ProForm）
- ProTable：演示表格配置、列定义、搜索、分页、请求映射、动作按钮等；
- ProForm：演示表单配置、校验规则、渲染函数、远程下拉等。

```mermaid
sequenceDiagram
participant View as "ProTable.vue"
participant Core as "@pro-iview/core"
participant Adapter as "UI 适配器"
participant UI as "UI 组件库"
View->>Core : "使用 <pro-table>"
Core->>Adapter : "useUIAdapter()"
Adapter-->>Core : "返回 Table/Input/Button 等组件"
Core->>UI : "渲染具体 UI 组件"
View-->>View : "响应事件/数据绑定"
```

图表来源
- [src/views/ProTable.vue:11-16](file://src/views/ProTable.vue#L11-L16)
- [src/views/ProForm.vue:5-11](file://src/views/ProForm.vue#L5-L11)
- [packages/core/src/index.js:41-47](file://packages/core/src/index.js#L41-L47)

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

## 依赖关系分析
- 根依赖与脚本：package.json 定义了构建脚本（dev/build/lib/build:core/build:adapter:*）、依赖（Vue3、axios、dayjs、lodash-es、view-ui-plus、element-plus 等）；
- Monorepo 构建：turbo.json 定义了构建流水线，支持跨包依赖与缓存；
- 示例应用：src/main.js 展示了如何在示例应用中使用传统入口或核心包。

```mermaid
graph LR
RootPkg["根 package.json<br/>scripts/dependencies"] --> Build["构建脚本<br/>dev/build/lib"]
RootPkg --> Deps["依赖<br/>Vue3/axios/dayjs/lodash-es"]
Deps --> UI1["view-ui-plus"]
Deps --> UI2["element-plus"]
Turbo["turbo.json<br/>pipeline"] --> Build
Example["src/main.js<br/>示例入口"] --> Legacy["packages/index.js<br/>传统入口"]
Example --> Core["@pro-iview/core<br/>核心包"]
```

图表来源
- [package.json:8-47](file://package.json#L8-L47)
- [turbo.json:3-16](file://turbo.json#L3-L16)
- [src/main.js:1-14](file://src/main.js#L1-L14)

章节来源
- [package.json:1-47](file://package.json#L1-L47)
- [turbo.json:1-18](file://turbo.json#L1-L18)
- [src/main.js:1-14](file://src/main.js#L1-L14)

## 性能考虑
- Monorepo 与 Turborepo：利用增量构建与缓存减少重复编译时间；
- 适配器注入：仅在安装阶段注入一次，运行时无额外开销；
- 全局工具属性：集中管理，避免重复实例化；
- 样式抽象：减少对具体 UI 库样式的直接依赖，降低样式冲突风险。

章节来源
- [ARCHITECTURE_SUMMARY.md:288-296](file://ARCHITECTURE_SUMMARY.md#L288-L296)

## 故障排查指南
- 编译错误
  - 检查依赖安装：确保安装了 Vue3、axios、dayjs、lodash-es、view-ui-plus 或 element-plus；
  - 检查构建脚本：使用 pnpm 执行 dev/build/lib/build:core/build:adapter:*；
  - 检查示例入口：确认示例应用正确引入 UI 库与组件库。
- 运行时异常
  - 未安装 UI 库：确保在使用核心包前先 app.use 对应 UI 库；
  - 未注入适配器：使用核心包时传入 adapter；使用 compat 包时无需手动注入；
  - 图标缺失（element-plus）：根据提示注册所需图标组件，或使用 CompatibleIcon。
- 样式冲突
  - 使用抽象类名（pro-*）避免直接依赖具体 UI 库类名；
  - 确认 UI 库样式文件已正确引入；
  - 如需覆盖样式，建议通过自定义 CSS 或主题变量实现。

章节来源
- [package.json:20-33](file://package.json#L20-L33)
- [MIGRATION.md:190-214](file://MIGRATION.md#L190-L214)
- [packages/adapters/element-plus/src/index.js:29-61](file://packages/adapters/element-plus/src/index.js#L29-L61)
- [src/main.js:4-5](file://src/main.js#L4-L5)

## 结论
V3 在保持向后兼容的同时，提供了更强的可扩展性与解耦能力。推荐新项目直接采用新架构（@pro-iview/core + 适配器），老项目可先通过 compat 包零改动升级，再逐步迁移到新架构。通过 Monorepo 与适配器模式，V3 为多 UI 库共存与未来扩展奠定了坚实基础。

章节来源
- [MIGRATION.md:156-188](file://MIGRATION.md#L156-L188)
- [ARCHITECTURE_SUMMARY.md:297-311](file://ARCHITECTURE_SUMMARY.md#L297-L311)

## 附录

### 迁移步骤与路径
- 零改动升级（推荐用于快速上线）
  - 安装：使用 npm/yarn/pnpm 安装 pro_iview_v3@2.x；
  - 使用：与 v1.x 完全一致，内部自动使用适配器；
  - 适用场景：已有项目短期内无法重构，但希望获得 V3 的稳定性与新特性。
- 迁移到新架构（推荐长期演进）
  - 卸载旧版本：移除旧的 pro_iview_v3；
  - 安装新版本：安装 @pro-iview/core 与目标 UI 适配器（view-ui-plus 或 element-plus）；
  - 修改入口：在 app.use 中传入 adapter；
  - 渐进替换：逐步将组件与样式迁移至抽象类名（pro-*）。
- 直接采用新方式（全新项目）
  - 选择 UI 库：view-ui-plus 或 element-plus；
  - 安装依赖：安装对应 UI 库与适配器；
  - 引入样式：引入 UI 库样式文件；
  - 注册插件：app.use(UI 库).use(@pro-iview/core, { adapter })。

章节来源
- [MIGRATION.md:160-188](file://MIGRATION.md#L160-L188)
- [MIGRATION.md:22-81](file://MIGRATION.md#L22-L81)

### API 变更与兼容性说明
- 兼容性策略
  - compat 包：保持原有 API 不变，内部自动注入 ViewUIPlusAdapter；
  - 核心包：新增 adapter 参数，通过 provideUIAdapter 注入；
  - 全局工具属性：$http/$dayjs/$lodash/$PRO_IVIEW 保持不变；
  - 国际化：locale/i18n/lang 保持不变。
- 废弃与新增
  - 废弃：直接依赖 view-ui-plus 的硬编码组件（已在核心包中通过适配器解耦）；
  - 新增：UI 适配器接口、依赖注入机制、抽象样式类名（pro-*）。

章节来源
- [packages/compat/index.js:12-24](file://packages/compat/index.js#L12-L24)
- [packages/core/src/index.js:13-57](file://packages/core/src/index.js#L13-L57)
- [MIGRATION.md:190-214](file://MIGRATION.md#L190-L214)

### 迁移前准备与迁移后验证
- 迁移前准备
  - 备份当前项目；
  - 确认 UI 库版本与依赖；
  - 准备好 element-plus 的图标注册方案（如需使用 element-plus）。
- 迁移后验证
  - 功能验证：ProTable、ProForm、ProSelect 等组件是否正常；
  - 样式验证：界面布局、字体、颜色是否符合预期；
  - 国际化验证：语言包加载与切换；
  - 构建验证：执行 pnpm build 与 pnpm build:core/build:adapter:*。

章节来源
- [ARCHITECTURE_SUMMARY.md:175-210](file://ARCHITECTURE_SUMMARY.md#L175-L210)
- [package.json:8-19](file://package.json#L8-L19)

### 自动化迁移工具与脚本
- 构建与开发脚本
  - 安装依赖：pnpm install；
  - 构建全部：pnpm build；
  - 构建核心包：pnpm build:core；
  - 构建适配器：pnpm build:adapter:view 或 pnpm build:adapter:element；
  - 开发模式：pnpm dev；
  - 构建文档/演示：pnpm build:docs 或 pnpm build:aopule。
- 使用建议
  - 先执行 pnpm install 与 pnpm build 验证整体可用性；
  - 分别构建 core 与适配器，确保独立包的产物正确；
  - 在示例应用中验证 UI 库与组件库的组合效果。

章节来源
- [package.json:8-19](file://package.json#L8-L19)
- [turbo.json:3-16](file://turbo.json#L3-L16)

### 迁移示例与最佳实践
- 示例入口
  - 传统入口：packages/index.js 展示了如何注册全局组件与指令；
  - 核心包入口：packages/core/src/index.js 展示了 install 流程；
  - 示例应用：src/main.js 展示了如何在示例中使用 UI 库与组件库。
- 最佳实践
  - 新项目优先使用 @pro-iview/core + 适配器；
  - 保持 UI 库样式文件与组件库样式文件同步；
  - 使用抽象类名（pro-*）避免样式污染；
  - 在 element-plus 下使用 CompatibleIcon 时，提前注册所需图标组件。

章节来源
- [packages/index.js:12-42](file://packages/index.js#L12-L42)
- [packages/core/src/index.js:13-57](file://packages/core/src/index.js#L13-L57)
- [src/main.js:1-14](file://src/main.js#L1-L14)
- [packages/adapters/element-plus/src/index.js:29-61](file://packages/adapters/element-plus/src/index.js#L29-L61)