149 lines
7.0 KiB
Markdown
149 lines
7.0 KiB
Markdown
# 技术栈与依赖
|
||
|
||
<cite>
|
||
**Referenced Files in This Document **
|
||
- [package.json](file://package.json)
|
||
- [vite.config.ts](file://vite.config.ts)
|
||
- [tsconfig.json](file://tsconfig.json)
|
||
- [uno.config.ts](file://uno.config.ts)
|
||
- [src/main.ts](file://src/main.ts)
|
||
- [src/common/naive-ui/components.ts](file://src/common/naive-ui/components.ts)
|
||
- [src/stores/counter.ts](file://src/stores/counter.ts)
|
||
</cite>
|
||
|
||
## 目录
|
||
1. [核心框架：Vue 3](#核心框架vue-3)
|
||
2. [状态管理：Pinia](#状态管理pinia)
|
||
3. [UI 组件库：Naive UI](#ui-组件库naive-ui)
|
||
4. [原子化样式：UnoCSS](#原子化样式unocss)
|
||
5. [构建工具：Vite](#构建工具vite)
|
||
6. [类型安全：TypeScript](#类型安全typescript)
|
||
7. [关键依赖项版本与选择理由](#关键依赖项版本与选择理由)
|
||
|
||
## 核心框架：Vue 3
|
||
|
||
本项目采用 Vue 3 作为核心前端框架，利用其组合式 API（Composition API）实现更灵活、可复用的逻辑组织。在 `main.ts` 文件中通过 `createApp` 初始化应用实例，并挂载根组件 `App.vue`，构成整个应用的入口。
|
||
|
||
Vue 3 提供了响应式系统、虚拟 DOM 渲染机制以及强大的组件化能力，使得桌面级 Web 应用的开发更加高效和模块化。结合 Vite 的现代构建流程，实现了极快的冷启动和热更新体验。
|
||
|
||
**Section sources**
|
||
- [src/main.ts](file://src/main.ts#L1-L15)
|
||
|
||
## 状态管理：Pinia
|
||
|
||
Pinia 作为 Vue 官方推荐的状态管理库，在本项目中用于集中管理全局状态。通过 `defineStore` 创建具有命名空间的 store 实例，如 `useCounterStore`，支持使用 `ref` 和 `computed` 构建响应式状态，并导出操作方法以供组件调用。
|
||
|
||
在 `main.ts` 中通过 `app.use(createPinia())` 注册 Pinia 插件，使所有组件均可通过 `useXXXStore()` 获取共享状态，避免了传统 Vuex 的冗余配置，提升了开发效率与类型推断准确性。
|
||
|
||
```mermaid
|
||
classDiagram
|
||
class useCounterStore {
|
||
+count : Ref<number>
|
||
+doubleCount : ComputedRef<number>
|
||
+increment() : void
|
||
}
|
||
useCounterStore --> ref : "uses"
|
||
useCounterStore --> computed : "uses"
|
||
useCounterStore --> defineStore : "created via"
|
||
```
|
||
|
||
**Diagram sources**
|
||
- [src/stores/counter.ts](file://src/stores/counter.ts#L3-L11)
|
||
|
||
**Section sources**
|
||
- [src/stores/counter.ts](file://src/stores/counter.ts#L1-L13)
|
||
- [src/main.ts](file://src/main.ts#L8-L9)
|
||
|
||
## UI 组件库：Naive UI
|
||
|
||
项目集成 Naive UI 作为 UI 组件解决方案，提供高质量、可定制的 Vue 3 组件集。为优化打包体积并实现按需引入，项目在 `src/common/naive-ui/components.ts` 中手动创建了一个轻量化的 UI 实例，仅注册所需组件（如 `NButton`, `NCard`, `NConfigProvider`），并通过 `create()` 方法生成可被 `app.use()` 注册的插件对象。
|
||
|
||
此外，项目还通过 `discrete-api.ts` 导出独立使用的 API（如 message、modal），并在 `theme.ts` 中扩展默认主题，自定义主色调为 `#0070f3`，确保视觉风格统一。
|
||
|
||
```mermaid
|
||
classDiagram
|
||
class naiveUi {
|
||
+components : Array<Component>
|
||
}
|
||
naiveUi --> NButton : "includes"
|
||
naiveUi --> NCard : "includes"
|
||
naiveUi --> NConfigProvider : "includes"
|
||
naiveUi --> create : "created via"
|
||
```
|
||
|
||
**Diagram sources**
|
||
- [src/common/naive-ui/components.ts](file://src/common/naive-ui/components.ts#L1-L11)
|
||
- [src/common/naive-ui/theme.ts](file://src/common/naive-ui/theme.ts#L2-L14)
|
||
|
||
**Section sources**
|
||
- [src/common/naive-ui/components.ts](file://src/common/naive-ui/components.ts#L1-L11)
|
||
|
||
## 原子化样式：UnoCSS
|
||
|
||
UnoCSS 是一个即时（on-the-fly）原子化 CSS 引擎，取代传统的 Tailwind CSS 实现方式。它允许开发者直接在模板中使用类名（如 `flex`, `p-4`, `text-lg`），并在构建时动态生成最小化 CSS，极大提升样式编写效率并减少冗余代码。
|
||
|
||
项目通过 `unocss/vite` 插件集成 UnoCSS，并在 `uno.config.ts` 中启用 `transformerVariantGroup` 和 `transformerDirectives`，支持嵌套语法（如 `hover:(bg-red-500 text-white)`）和 `@apply` 指令，增强可读性与灵活性。同时，`virtual:uno.css` 被引入 `main.ts`，确保样式正确注入。
|
||
|
||
**Section sources**
|
||
- [uno.config.ts](file://uno.config.ts#L1-L10)
|
||
- [vite.config.ts](file://vite.config.ts#L15-L16)
|
||
- [src/main.ts](file://src/main.ts#L6)
|
||
|
||
## 构建工具：Vite
|
||
|
||
Vite 作为现代前端构建工具，基于 ES 模块原生支持，显著提升了开发服务器的启动速度与热更新性能。项目通过 `vite.config.ts` 配置核心插件：
|
||
|
||
- `@vitejs/plugin-vue`：支持 `.vue` 单文件组件解析
|
||
- `@vitejs/plugin-vue-jsx`：支持 JSX/TSX 语法
|
||
- `vite-plugin-vue-devtools`：集成 Vue DevTools 调试工具
|
||
- `unocss/vite`：集成 UnoCSS 样式引擎
|
||
|
||
配置中还设置了路径别名 `@` 指向 `src` 目录，便于模块导入。Vite 的开箱即用特性与 TypeScript、JSX、Sass 等技术无缝集成，构成了高效的开发环境基础。
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A["用户请求 /"] --> B[Vite Dev Server]
|
||
B --> C{资源类型}
|
||
C --> |HTML| D[index.html]
|
||
C --> |.vue 文件| E[Vite 解析 SFC]
|
||
E --> F[编译 template/script/style]
|
||
F --> G[返回 ES Module]
|
||
C --> |TypeScript| H[Vite 实时转译]
|
||
H --> I[浏览器执行]
|
||
C --> |UnoCSS 类名| J[UnoCSS 动态生成 CSS]
|
||
J --> K[注入 style 标签]
|
||
I & K --> L[页面渲染完成]
|
||
```
|
||
|
||
**Diagram sources**
|
||
- [vite.config.ts](file://vite.config.ts#L1-L30)
|
||
|
||
**Section sources**
|
||
- [vite.config.ts](file://vite.config.ts#L1-L30)
|
||
|
||
## 类型安全：TypeScript
|
||
|
||
TypeScript 在项目中承担关键的角色，提供静态类型检查以预防运行时错误。项目采用分层配置策略，`tsconfig.json` 通过 `references` 引入 `tsconfig.node.json` 和 `tsconfig.app.json`，分别处理 Node.js 环境与应用代码的类型定义。
|
||
|
||
`.vue` 文件的类型支持通过 `vue-tsc` 实现，替代标准 `tsc` 进行类型检查，确保模板中的 props、emits 等具备完整类型推断。配合 VSCode 与 Volar 插件，开发者可在编辑器中获得精准的智能提示与错误检测。
|
||
|
||
**Section sources**
|
||
- [tsconfig.json](file://tsconfig.json#L1-L12)
|
||
- [README.md](file://README.md#L12-L15)
|
||
|
||
## 关键依赖项版本与选择理由
|
||
|
||
| 依赖包 | 版本范围 | 选择理由 |
|
||
|-------|--------|---------|
|
||
| vue | ^3.5.18 | 使用最新稳定版 Vue 3，支持 Composition API 与 Fragment |
|
||
| pinia | ^3.0.3 | 官方状态管理库，轻量、类型友好、API 简洁 |
|
||
| naive-ui | ^2.42.0 | 功能丰富、文档完善、支持 Tree-shaking 的 Vue 3 组件库 |
|
||
| unocss | ^66.4.2 | 即时原子化 CSS，性能优于传统方案，支持高度定制 |
|
||
| vite | ^7.0.6 | 极速 HMR、原生 ES Modules 支持、生态成熟 |
|
||
| typescript | ~5.8.0 | 精确控制 TS 版本，避免意外升级导致兼容问题 |
|
||
| vue-tsc | ^3.0.4 | 专为 Vue + TypeScript 设计的类型检查工具，支持 `<script setup>` 和模板类型校验 |
|
||
|
||
这些依赖共同构建了一个现代化、高性能、类型安全的前端开发体系，为项目的长期维护与扩展提供了坚实基础。
|
||
|
||
**Section sources**
|
||
- [package.json](file://package.json#L1-L43) |