egova-admin-web/README.md

新版统一用户中心前端项目

# egova-admin-web

新版统一用户中心前端项目

## 概览

脚手架模板项目是基于 Vue 3 + Typescript + Vite 搭建项目，应用层的能力包含：

-   接入 vue-router
-   接入 axios
-   接入 ant-design-vue 组件库,dayjs 时间库
-   接入 Pinia
-   接入多页能力，借鉴了 webpack 的多页思路，在 pages/index.json 文件中定义多页的入口即可
-   接入按需引入能力 unplugin-vue-components
-   接入@vueuse/core，内含大量封装好的工具集

## 环境需求：

```sh
node>=16.0.0
pnpm>=8.0.0
```

## 运行

### 本地运行

```sh
pnpm install
pnpm serve

# 运行项目分支
pnpm serve --mode project
```

### 打包

```sh
pnpm build

# 打包项目分支
pnpm build --mode project
```

### 打包预览

```sh
pnpm preview

# 打包预览项目分支
pnpm preview --mode project
```

### 打包第三方集成 lib

```sh
pnpm run lib
打包后的文件在根目录lib下，
直接发布即可。
npm publish
```

## vscode 建议

建议安装以下工具

```sh
Volar
Vue 3 Snippets
SCSS Formatter
```

## 进阶

### 按需引入

项目使用了插件 unplugin-vue-components，该插件可以在 Vue 文件中自动引入组件（包括项目自身的组件和各种组件库中的组件）使用此插件后，不需要手动编写`import { Button } from 'ant-design-vue'`这样的代码了，插件会自动识别`template`中使用的自定义组件并自动注册。

具体使用可参考 https://www.jianshu.com/p/bce8e4b86c67 讲解

因为使用了此插件，所以 ant design 组件库就无需全局注册引入

```Vue
<!-- 平时我们在页面使用组件 -->
<template>
	<comp/>
</template>
<script>
import { defineComponent } from "vue"
import comp from "./src/components/comp.vue"
export default defineComponent({
	name: "page1",
	components: { comp }
})
<script>
```

```Vue
<!-- 引入unplugin-vue-components之后 -->
<template>
	<comp/>
</template>
<script>
// 不需要任何相关内容
</script>
```

### 文件拆分

将 `*.vue` 组件分散到多个文件中，可以为一个语块使用 `src` 这个 attribute 来导入一个外部文件

```Vue
<template src="./template.html"></template>
<style src="./style.css"></style>
<script setup></script> // 此文件最好不拆分，否则setup语法糖就没法用
```

如果需要给组件命名，使用了插件 vite-plugin-vue-setup-extend，就可以如下写法

```Vue
<script src="./script.ts" setup name="xxx"></script>
```

不使用插件，则如下

```Vue
<script lang="ts">
export default { name: 'CommonHeader' }
</script>
<script lang="ts" setup></script>
```

**拆分文件带来的问题**

1. 如果将 html 文件拆分出去，导致 html 中使用了一些变量，但是仍会在 ts 中报警告（变量已声明，但没有任何地方使用）

2. 如果将 ts 文件拆分出去，那么无法使用 setup 语法糖，需要手动声明 setup，并在 setup 中返回所需要的变量和方法
3. 同时发现，很多第三方插件，都是基于 vue 文件进行编写的，如果拆分，会导致很多第三方插件无法正确识别
4. 综上，**建议不拆分文件，只拆分 scss 文件即可**

### 工具集

项目中使用了 @vueuse/core ，基于组合 API 封装好用的工具函数，封装了常见的一些交互逻辑

官方使用文档 https://vueuse.org/guide/

### 自定义指令集

项目中如果有全局的一些问题，可以通过自定义指令集方式实现，目前实现的有：

v-emoji:限制输入内容，默认只能输入中文，英文，数字。可通过外部传入正则表达式：

例如：

```json
// 输入内容按照 传入的reg正则表达式进行处理
<a-input v-model:value="formData.username" v-emoji="reg"></a-input>

// 不传值，则默认只能输入 中文，英文，数字
<a-input v-model:value="formData.username" v-emoji></a-input>
```

v-upper:输入框小写转大写

### 登录页定制

支持登录页定制。

#### 项目文件夹与项目名称

标准版本登录组件与项目版本登录组件以 `src/views/login/projects` 目录划分，项目名称以公司统一规范的项目命名命名。

#### 开发说明

下述使用 `name` 指代项目名称：

-   新建 `src/views/login/projects/name` 文件夹，组件名称命名为 `LoginProjectName`
-   参考 `src/views/login/projects/standard` 组件开发登录组件。登录组件所需的变量与函数由 `useLogin` 函数统一提供，只需要定制编写 `<template>` 和 `<style>`。
-   登录入口组件添加动态组件引用 `LoginProjectName: defineAsyncComponent(() => import("./projects/name/index.vue"))`
-   **系统配置项** 修改 **登录页项目名称** 为 `name`

### 常见问题

#### 开发环境代理配置

使用环境变量 `env.PROXY_PATH_API` 定义服务代理地址，变量定义在 `.env.development` 中：

```
########## 代理配置 ##########
# 主代理
PROXY_PATH_API=http://192.168.1.1/admin-api
```

开发时，不建议修改 `.env.development` 文件，应该新建 `.env.development.local` 文件定义本地变量。此文件会被 git 忽略，不会提交。

参考文档 [环境变量和模式](https://cn.vitejs.dev/guide/env-and-mode.html#env-files)

#### 动态组件

```
<Component :is="defineAsyncComponent(() => import(`@/components/${component}.vue`))" />
```