# 快速开始

<cite>
**本文引用的文件**
- [README.md](file://README.md)
- [package.json](file://package.json)
- [vite.config.js](file://vite.config.js)
- [turbo.json](file://turbo.json)
- [pnpm-workspace.yaml](file://pnpm-workspace.yaml)
- [ARCHITECTURE_SUMMARY.md](file://ARCHITECTURE_SUMMARY.md)
- [src/main.js](file://src/main.js)
- [src/App.vue](file://src/App.vue)
- [src/router/index.js](file://src/router/index.js)
- [src/views/Home.vue](file://src/views/Home.vue)
- [src/views/ProTable.vue](file://src/views/ProTable.vue)
- [packages/index.js](file://packages/index.js)
- [packages/components/ProTable.vue](file://packages/components/ProTable.vue)
- [packages/components/ProForm.vue](file://packages/components/ProForm.vue)
</cite>

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

## 简介
本指南面向希望在 10 分钟内成功运行第一个 Pro-IVIEW V3 示例的新用户。内容涵盖环境要求、安装步骤（npm/yarn/pnpm）、基础集成（Vue 3 项目初始化、组件库安装与基本配置）、UI 框架选择与配置（View UI Plus 与 Element Plus 的两种集成方式）、完整 Hello World 示例以及常见问题排查。

Pro-IVIEW V3 是基于 Vue 3 的高阶组件库，当前仓库提供了对 View UI Plus 的完整适配与示例，并同时支持 Element Plus 适配器。项目采用 Monorepo 管理，核心能力通过适配器模式解耦 UI 库差异，既可使用向后兼容包，也可按需选择新的核心包与适配器组合。

章节来源
- [README.md:1-18](file://README.md#L1-L18)
- [ARCHITECTURE_SUMMARY.md:235-279](file://ARCHITECTURE_SUMMARY.md#L235-L279)

## 项目结构
该仓库采用 Monorepo 结构，使用 pnpm workspace + Turborepo 管理多包，核心与适配器分离，便于独立构建与发布。根目录包含构建与运行脚本、Vite 配置、工作区配置等；src 目录提供示例应用与路由；packages 目录包含组件库入口与核心组件。

```mermaid
graph TB
root["根目录<br/>package.json / vite.config.js / turbo.json / pnpm-workspace.yaml"]
subgraph "示例应用"
src_main["src/main.js"]
src_app["src/App.vue"]
src_router["src/router/index.js"]
src_views["src/views/*.vue"]
end
subgraph "组件库"
pkg_index["packages/index.js"]
pkg_components["packages/components/*.vue"]
end
root --> src_main
src_main --> src_app
src_main --> src_router
src_main --> pkg_index
pkg_index --> pkg_components
```

图表来源
- [pnpm-workspace.yaml:1-5](file://pnpm-workspace.yaml#L1-L5)
- [turbo.json:1-18](file://turbo.json#L1-L18)
- [vite.config.js:11-23](file://vite.config.js#L11-L23)
- [src/main.js:1-14](file://src/main.js#L1-L14)
- [packages/index.js:1-69](file://packages/index.js#L1-L69)

章节来源
- [pnpm-workspace.yaml:1-5](file://pnpm-workspace.yaml#L1-L5)
- [turbo.json:1-18](file://turbo.json#L1-L18)
- [vite.config.js:11-23](file://vite.config.js#L11-L23)
- [src/main.js:1-14](file://src/main.js#L1-L14)
- [packages/index.js:1-69](file://packages/index.js#L1-L69)

## 核心组件
- 组件库入口与安装：通过 packages/index.js 提供 install 方法，自动注册所有组件与指令，并注入全局属性（如 HTTP、日期工具、国际化等）。
- 主应用集成：在 src/main.js 中引入 View UI Plus 样式与组件库，随后在应用实例上依次 use 国际化、UI 框架、组件库与路由。
- 路由与视图：src/router/index.js 定义了示例路由，src/views/Home.vue 展示了 ProTable 等组件的综合使用。

章节来源
- [packages/index.js:12-42](file://packages/index.js#L12-L42)
- [src/main.js:4-13](file://src/main.js#L4-L13)
- [src/router/index.js:12-66](file://src/router/index.js#L12-L66)
- [src/views/Home.vue:16-39](file://src/views/Home.vue#L16-L39)

## 架构总览
Pro-IVIEW V3 采用“核心包 + UI 适配器”的架构，核心包不直接依赖任何 UI 库，通过适配器注入 UI 组件，从而同时支持 View UI Plus 与 Element Plus。兼容包 pro_iview_v3 封装了核心包与 View UI Plus 适配器，保持 API 与 v1.x 一致。

```mermaid
graph TB
app["应用入口<br/>src/main.js"]
compat["兼容包<br/>pro_iview_v3"]
core["@pro-iview/core"]
view_adapter["@pro-iview/view-ui-plus"]
element_adapter["@pro-iview/element-plus"]
app --> compat
app --> core
core --> view_adapter
core --> element_adapter
```

图表来源
- [ARCHITECTURE_SUMMARY.md:124-156](file://ARCHITECTURE_SUMMARY.md#L124-L156)
- [ARCHITECTURE_SUMMARY.md:235-279](file://ARCHITECTURE_SUMMARY.md#L235-L279)

章节来源
- [ARCHITECTURE_SUMMARY.md:124-156](file://ARCHITECTURE_SUMMARY.md#L124-L156)
- [ARCHITECTURE_SUMMARY.md:235-279](file://ARCHITECTURE_SUMMARY.md#L235-L279)

## 详细组件分析

### 安装与环境要求
- Node.js 版本：建议使用长期支持版本（LTS），以确保 pnpm、Vite、Turbo 等工具稳定运行。
- 包管理器：推荐使用 pnpm（仓库已设置 packageManager），也可使用 npm 或 yarn，但需注意依赖解析差异。
- Vue 3：项目依赖 vue ^3.4.4，确保与组件库兼容。

章节来源
- [package.json:46](file://package.json#L46)
- [package.json:20-32](file://package.json#L20-L32)

### 安装步骤（npm/yarn/pnpm）
- 使用 pnpm（推荐）
  - 安装依赖：pnpm install
  - 构建：pnpm build
- 使用 npm
  - 安装依赖：npm install
  - 构建：npm run build
- 使用 yarn
  - 安装依赖：yarn install
  - 构建：yarn build

章节来源
- [package.json:8-18](file://package.json#L8-L18)
- [turbo.json:3-12](file://turbo.json#L3-L12)

### 基础集成（Vue 3 项目初始化）
- 初始化 Vue 3 项目（可参考官方 CLI 或模板）
- 在 main.js 中引入并注册组件库与 UI 框架（见下节）

章节来源
- [src/main.js:1-14](file://src/main.js#L1-L14)

### UI 框架选择与配置

#### 方式一：使用 View UI Plus（向后兼容）
- 安装依赖：安装 view-ui-plus 与组件库
- 在 main.js 中引入 UI 样式与组件库，并按顺序 use 国际化、UI 框架、组件库与路由
- 适用于希望零改动迁移的现有项目

章节来源
- [src/main.js:4-13](file://src/main.js#L4-L13)
- [ARCHITECTURE_SUMMARY.md:271-279](file://ARCHITECTURE_SUMMARY.md#L271-L279)

#### 方式二：使用 Element Plus（新方式，推荐）
- 安装依赖：安装 element-plus 与 @pro-iview/core、@pro-iview/element-plus
- 在 main.js 中引入 UI 样式与组件库，并按顺序 use UI 框架、use 核心包并传入 Element Plus 适配器
- 适用于新项目或希望拥抱新架构的项目

章节来源
- [ARCHITECTURE_SUMMARY.md:254-269](file://ARCHITECTURE_SUMMARY.md#L254-L269)

### Hello World 示例（10 分钟上手）
以下流程帮助你在 10 分钟内运行第一个示例：

步骤 1：准备环境
- 确保 Node.js 与 pnpm 已安装
- 在项目根目录执行 pnpm install 安装依赖

步骤 2：启动开发服务器
- 执行 pnpm dev 启动 Vite 开发服务器

步骤 3：访问示例页面
- 在浏览器打开本地地址，进入首页或对应路由（例如 /ProTable）
- 查看 ProTable 与 ProForm 等组件的渲染效果

```mermaid
sequenceDiagram
participant Dev as "开发者"
participant PNPM as "包管理器(pnpm/npm/yarn)"
participant Vite as "Vite 开发服务器"
participant Browser as "浏览器"
Dev->>PNPM : "pnpm install / npm install / yarn install"
Dev->>PNPM : "pnpm dev / npm run dev / yarn dev"
PNPM-->>Vite : "启动开发服务器"
Browser->>Vite : "请求 / 或 /ProTable"
Vite-->>Browser : "返回示例页面"
Browser-->>Dev : "看到 ProTable/ProForm 示例"
```

图表来源
- [package.json:8-18](file://package.json#L8-L18)
- [src/router/index.js:12-66](file://src/router/index.js#L12-L66)
- [src/views/Home.vue:16-39](file://src/views/Home.vue#L16-L39)

章节来源
- [package.json:8-18](file://package.json#L8-L18)
- [src/router/index.js:12-66](file://src/router/index.js#L12-L66)
- [src/views/Home.vue:16-39](file://src/views/Home.vue#L16-L39)

### 组件使用要点
- ProTable：用于表格数据展示、搜索、分页与弹窗表单联动，支持列配置、工具栏、全屏等功能
- ProForm：用于表单渲染与校验，支持栅格布局、分组标题、动态渲染等

章节来源
- [src/views/ProTable.vue:11-16](file://src/views/ProTable.vue#L11-L16)
- [packages/components/ProTable.vue:154-200](file://packages/components/ProTable.vue#L154-L200)
- [packages/components/ProForm.vue:146-200](file://packages/components/ProForm.vue#L146-L200)

## 依赖分析
- 运行时依赖（核心）：vue、view-ui-plus、element-plus（任选其一）、axios、dayjs、lodash-es、mousetrap、qs、screenfull、vue-i18n、vue3-click-away、vuedraggable
- 开发依赖：@vitejs/plugin-vue、@vitejs/plugin-vue-jsx、vite、turbo、rollup 插件等
- Monorepo 管理：pnpm-workspace.yaml 定义工作区；turbo.json 配置构建流水线

```mermaid
graph TB
vue["vue"]
view_ui_plus["view-ui-plus"]
element_plus["element-plus"]
axios["axios"]
dayjs["dayjs"]
lodash_es["lodash-es"]
mousetrap["mousetrap"]
qs["qs"]
screenfull["screenfull"]
vue_i18n["vue-i18n"]
vue3_click_away["vue3-click-away"]
vuedraggable["vuedraggable"]
vue --> view_ui_plus
vue --> element_plus
vue --> axios
vue --> dayjs
vue --> lodash_es
vue --> mousetrap
vue --> qs
vue --> screenfull
vue --> vue_i18n
vue --> vue3_click_away
vue --> vuedraggable
```

图表来源
- [package.json:20-32](file://package.json#L20-L32)

章节来源
- [package.json:20-32](file://package.json#L20-L32)
- [pnpm-workspace.yaml:1-5](file://pnpm-workspace.yaml#L1-L5)
- [turbo.json:3-12](file://turbo.json#L3-L12)

## 性能考虑
- 构建优化：Vite 默认启用 Rollup 打包，生产构建开启压缩与源码映射可选；Monorepo 使用 Turborepo 缓存提升重复构建速度
- 外部化依赖：库构建时将 Vue、UI 框架等外部化，避免重复打包
- 按需加载：在业务侧结合路由与组件按需加载策略，减少首屏体积

章节来源
- [vite.config.js:15-87](file://vite.config.js#L15-L87)
- [turbo.json:3-12](file://turbo.json#L3-L12)

## 故障排除指南
- 安装失败（pnpm/yarn/npm）
  - 清理缓存并重试：pnpm cache clean / yarn cache clean / npm cache verify
  - 检查网络代理与 registry 配置
- 构建失败
  - 确认 Node.js 版本满足要求
  - 检查 package.json 中的脚本与依赖版本
- UI 样式缺失
  - 确保已引入 UI 框架样式文件（View UI Plus 或 Element Plus）
- 组件未生效
  - 确认已在 main.js 中按顺序 use 国际化、UI 框架、组件库与路由
  - 检查组件名称与导入路径是否正确

章节来源
- [src/main.js:4-13](file://src/main.js#L4-L13)
- [package.json:8-18](file://package.json#L8-L18)

## 结论
通过本快速开始指南，你可以在 10 分钟内完成环境准备、安装与集成，并成功运行第一个示例页面。推荐优先采用 Element Plus + 新架构的方式进行新项目开发；若为存量项目，可继续使用 View UI Plus 的向后兼容包以实现零改动迁移。

## 附录

### A. 从零开始的最小示例步骤
- 初始化 Vue 3 项目
- 安装依赖：根据所选 UI 框架安装相应依赖
- 在 main.js 中引入 UI 样式与组件库，并 use 国际化、UI 框架、组件库与路由
- 新建一个路由视图，使用 ProTable/ProForm 等组件
- 运行 pnpm dev 启动开发服务器，访问对应路由查看效果

章节来源
- [src/main.js:4-13](file://src/main.js#L4-L13)
- [src/router/index.js:12-66](file://src/router/index.js#L12-L66)
- [src/views/Home.vue:16-39](file://src/views/Home.vue#L16-L39)