# dawn

**Repository Path**: Kunoky/dawn

## Basic Information

- **Project Name**: dawn
- **Description**: VITE, VUE3, Pinia, 自动导入， Tauri等一众主流技术构建的脚手架。
- **Primary Language**: JavaScript
- **License**: MIT
- **Default Branch**: ruoyi
- **Homepage**: https://gitee.com/Kunoky/dawn
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 2
- **Created**: 2023-02-27
- **Last Updated**: 2026-04-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Dawn - 现代化 Vue 3 项目模板

## 设计思想

写的更少，做的更多。这是 react 的哲学，也是我想做的。
OOCSS、自动导入、众多逻辑的封装、以及没有使用 ts 都是为了实现这一点，是为了让我们在开发过程中关注逻辑即可，
而不需要开发时在文件内或文件之间来回切换，耗费过多与逻辑无关的精力。

## 实例

demo: 默认 develop，基于 indexeddb 模拟了一个项目，如果数据改乱了，请删除缓存的 indexeddb 数据

ruoyi：请切换至 ruoyi 分支

## 特点

1. **Vite 7** - 极速的前端构建工具
2. **Vue 3.5** - 渐进式 JavaScript 框架
3. **文件路由** - 基于文件系统的路由
4. **API 自动引入** - 无需手动 import
5. **组件自动引入** - 组件按需自动导入
6. **图标自动引入** - 图标按需自动导入
7. **VueUse 支持** - 丰富的组合式 API
8. **OOCSS** - 原子化 CSS 框架
9. **暗黑模式支持** - 主题切换功能
10. **Pinia 3** - 现代状态管理
11. **Alova** - 轻量级请求库
12. **Vitest 3** - 快速单元测试
13. **路径别名支持** - 简化导入路径
14. **i18n 国际化支持** - 多语言支持
15. **JSX 支持** - 灵活的模板语法
16. **环境变量配置** - 灵活的配置管理
17. **代码规范与风格** - ESLint + Prettier
18. **ECharts 5** - 数据可视化
19. **Tauri 2** - 跨平台桌面应用
20. **通用业务组件** - CTable 等高级组件
21. **Composables 封装** - 可复用的逻辑函数
22. **IndexedDB 支持** - 本地数据存储
23. **Mock 数据支持** - 开发环境数据模拟

## 使用

使用 `pnpm` 包管理器 👉 [安装教程](https://pnpm.io/zh/installation)

1. 安装依赖

```shell
pnpm install
```

2. 开发

```shell
pnpm dev
```

3. 打包

```shell
pnpm build

# 打包体积分析
pnpm build:stats
```

4. 单元测试

```shell
pnpm test
```

5. 单元测试报告生成

```shell
pnpm coverage
```

6. 代码规范校验

```shell
# pnpm lint [path]
pnpm lint src

# 代码格式化 pnpm format [path]
pnpm format src
```

<br />

## 详情

### [1. Vite 7](https://cn.vitejs.dev/)

采用 **[Vite7](https://cn.vitejs.dev/)** 作为构建工具，提供极速的开发体验和构建性能。你可以在根目录下的
`vite.config.js` 对项目的构建进行配置。

**主要特性：**

- 基于 ESM 的快速冷启动
- 热模块替换 (HMR)
- 优化的生产构建
- 丰富的插件生态

<br />

### [2. Vue 3.5](https://cn.vuejs.org/)

采用 **[Vue 3.5](https://cn.vuejs.org/)** 作为前端框架，提供现代化的响应式开发体验。

**主要特性：**

- Composition API
- 更好的 TypeScript 支持
- 更小的包体积
- 更好的性能

### [3. 文件路由](https://github.com/posva/unplugin-vue-router)

目录结构即路由。

eg:

- `src/pages/index.vue` => `/`
- `src/pages/about.vue` => `/about`
- `src/pages/users/index.vue` => `/users`
- `src/pages/users/profile.vue` => `/users/profile`
- `src/pages/users/[id].vue` => `/users/:id`
- `src/pages/[user]/settings.vue` => `/:user/settings`
- `src/pages/[...path].vue` => 404 路由

具体可见 👉 [unplugin-vue-router](https://github.com/posva/unplugin-vue-router)

### [4. API 自动引入](https://github.com/antfu/unplugin-auto-import)

基于 `unplugin-auto-import` 实现 API 的自动引入，无需手动 `import`。

**原本需要手动引入：**

```js
import { computed, ref } from 'vue'
import { useRouter } from 'vue-router'
import { ElMessage } from 'element-plus'
const count = ref(0)
const router = useRouter()
```

**现在可以直接使用：**

```js
const count = ref(0)
const router = useRouter()
ElMessage.success('操作成功')
```

**支持的自动引入库：**

- `vue` - Vue 3 API
- `vue-router` - 路由 API
- `vue-i18n` - 国际化 API
- `pinia` - 状态管理 API
- `@vueuse/core` - VueUse 工具库
- `alova/client` - 请求库 API
- `dayjs` - 日期处理库
- `element-plus` - UI 组件库

**项目内自动引入：**

1. `src/composables` 目录下的导出
2. `src/store` 目录下的导出
3. `@/utils/common` 工具函数
4. `@/utils/dict` 字典函数
5. `@/utils/request` 请求实例

**示例：**

```js
// src/composables/useTheme.js
export const useTheme = () => {
  const isDark = ref(false)
  const toggle = () => {
    isDark.value = !isDark.value
  }
  return { isDark, toggle }
}

// 在组件中直接使用，无需 import
const { isDark, toggle } = useTheme()
```

### [5. 组件自动引入](https://github.com/antfu/unplugin-vue-components)

基于 `unplugin-vue-components` 实现组件的自动引入，无需手动 `import`。

**原本需要手动引入：**

```html
<!-- src/pages/index.vue -->
<script setup lang="js">
  import Hello from '../components/Hello.vue'
  import { ElButton, ElInput } from 'element-plus'
</script>

<template>
  <Hello />
  <ElButton>按钮</ElButton>
  <ElInput v-model="value" />
</template>
```

**现在可以直接使用：**

```html
<!-- src/pages/index.vue -->
<template>
  <Hello />
  <ElButton>按钮</ElButton>
  <ElInput v-model="value" />
</template>
```

**支持的组件库：**

- **Element Plus** - 主要 UI 组件库
- **VueUse Components** - 实用组件
- **项目组件** - `src/components` 目录下的所有组件

**组件命名规则：**

- `src/components/Hello.vue` → `<Hello />`
- `src/components/foo/bar.vue` → `<FooBar />`
- `src/components/CTable.vue` → `<CTable />`

**图标自动引入：**

```html
<template>
  <!-- 直接使用图标，无需 import -->
  <i-ep-user />
  <i-ep-setting />
  <i-ep-search />
</template>
```

### [6. VueUse 支持](https://vueuse.org/)

`VueUse` 是一个功能强大的组合式 API 工具库，提供 200+ 个实用的 hooks。

**常用功能示例：**

```html
<script setup lang="js">
  // 鼠标位置跟踪
  const { x, y } = useMouse()

  // 本地存储
  const count = useLocalStorage('count', 0)

  // 网络状态
  const { isOnline } = useOnline()

  // 窗口大小
  const { width, height } = useWindowSize()

  // 防抖
  const debouncedValue = useDebounce(ref(''), 500)
</script>

<template>
  <div>鼠标位置: {{x}}, {{y}}</div>
  <div>计数: {{count}}</div>
  <div>网络状态: {{isOnline ? '在线' : '离线'}}</div>
  <div>窗口大小: {{width}} x {{height}}</div>
</template>
```

**主要特性：**

- 200+ 实用 hooks
- 自动按需引入
- TypeScript 支持
- 响应式设计
- 浏览器兼容性好

### [7. OOCSS 原子化 CSS](https://www.npmjs.com/package/oocss)

`OOCSS` 是一个轻量级的原子化 CSS 框架，通过组合简单的类名实现复杂样式。

**预定义变量：**

```css
:root {
  --primary-color: #1890ff;
  --success-color: #52c41a;
  --warning-color: #faad14;
  --error-color: #f5222d;
  --gray-1: #ffffff;
  --gray-2: #fafafa;
  --gray-3: #f5f5f5;
  --gray-4: #e8e8e8;
  --gray-5: #d9d9d9;
  --gray-6: #bfbfbf;
  --gray-7: #8c8c8c;
  --gray-8: #595959;
  --gray-9: #262626;
  --gray-10: #000000;
  --size-s: 8px;
  --size-m: 16px;
  --size-l: 24px;
}
```

**命名规则：**

- 属性简写-值简写-伪类简写
- `margin` → `mg`, `color` → `cl`, `flex` → `fx`
- `background-color` → `bgc`, `text-align` → `ta`

**使用示例：**

```html
<template>
  <!-- 主题色背景 + 白色文字 + 小内边距 + 居中对齐 -->
  <div class="bgc-p cl-1 pd-s ta-c">我是主题色背景白色文本小内边距居中</div>

  <!-- 成功色文字 + 中等外边距 + 右对齐 -->
  <div class="cl-s mg-m ta-r">成功提示信息</div>
</template>
```

**主要优势：**

- 极简的类名设计
- 通过组合实现复杂样式
- 减少 CSS 代码量
- 提高开发效率

### 8. 暗黑模式支持

基于 `useTheme` composable 实现主题切换功能。

```html
<script setup>
  const { isDark, toggle } = useTheme()
</script>

<template>
  <el-button link @click="toggle()">
    <i-ep-sunny v-if="isDark" />
    <i-ep-moon v-else />
  </el-button>
</template>
```

**特性：**

- 自动保存主题偏好
- 支持系统主题检测
- 平滑的主题切换动画
- 与 Element Plus 主题系统集成

### [9. Vitest 3 单元测试支持](https://vitest.dev/)

基于 **Vitest 3** 提供快速的单元测试支持。

**测试文件位置：** `src/test/` 目录

**测试示例：**

```js
import { describe, expect, it } from 'vitest'

describe('用户管理', () => {
  it('应该正确计算用户年龄', () => {
    const birthYear = 1990
    const currentYear = new Date().getFullYear()
    const age = currentYear - birthYear
    expect(age).toBeGreaterThan(0)
  })

  it('应该验证邮箱格式', () => {
    const email = 'user@example.com'
    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
    expect(emailRegex.test(email)).toBe(true)
  })

  it('快照测试', () => {
    const user = { name: 'John', age: 30 }
    expect(user).toMatchSnapshot()
  })
})
```

**运行测试：**

```shell
# 运行所有测试
pnpm test

# 生成覆盖率报告
pnpm coverage

# 监听模式
pnpm test --watch
```

**主要特性：**

- 基于 Vite 的快速测试
- 原生 ESM 支持
- 内置 TypeScript 支持
- 快照测试
- 覆盖率报告
- 并行测试执行

### [10. i18n 国际化支持](https://vue-i18n.intlify.dev/)

基于 **Vue I18n 11** 提供完整的国际化解决方案。

**语言文件位置：** `src/locales/` 目录

**中文配置 (`zh-CN.js`)：**

```js
export default {
  common: {
    confirm: '确认',
    cancel: '取消',
    save: '保存',
    delete: '删除',
    edit: '编辑',
    add: '新增',
    search: '搜索',
    reset: '重置',
  },
  user: {
    name: '用户名',
    email: '邮箱',
    phone: '手机号',
  },
}
```

**英文配置 (`en.js`)：**

```js
export default {
  common: {
    confirm: 'Confirm',
    cancel: 'Cancel',
    save: 'Save',
    delete: 'Delete',
    edit: 'Edit',
    add: 'Add',
    search: 'Search',
    reset: 'Reset',
  },
  user: {
    name: 'Username',
    email: 'Email',
    phone: 'Phone',
  },
}
```

**在组件中使用：**

```html
<script setup>
  const { t } = useI18n()

  const handleClick = () => {
    ElMessage.success(t('common.save'))
  }
</script>

<template>
  <div>
    <h1>{{ $t('user.name') }}</h1>
    <el-button @click="handleClick">{{ $t('common.save') }}</el-button>
  </div>
</template>
```

**主要特性：**

- 支持多语言切换
- 自动按需引入
- 支持插值和复数
- 懒加载语言包
- TypeScript 支持

### 11. 环境变量配置支持

基于 Vite 的环境变量系统，支持多环境配置。

**环境变量文件：**

- `.env` - 所有环境
- `.env.development` - 开发环境
- `.env.production` - 生产环境
- `.env.local` - 本地环境（不提交到版本控制）

**使用示例：**

```js
// 在代码中使用
const apiUrl = import.meta.env.VITE_API_URL
const isDev = import.meta.env.DEV
const isProd = import.meta.env.PROD
```

### 12. 代码规范与风格支持

基于 **ESLint 9** + **Prettier 3** 提供统一的代码规范。

**配置工具：**

- **ESLint 9** - 代码质量检查
- **Prettier 3** - 代码格式化
- **Husky 9** - Git hooks 管理
- **Lint-staged 16** - 暂存文件检查

**自动检查：**

```shell
# 代码检查
pnpm lint

# 代码格式化
pnpm format

# 提交时自动检查
git commit -m "feat: 新功能"
```

### 13. Alova 请求库封装

基于 **Alova 3** 提供轻量级的请求解决方案。

**使用示例：**

```js
// 基础请求
const data = await req.get('/api/users')
const result = await req.post('/api/users', { name: '张三', age: 20 })

// 响应式请求
const { data, loading, error } = useRequest(() => req.get('/api/users'))

// 分页请求
const { data, loading, loadMore } = usePagination((page, pageSize) => req.get('/api/users', { page, pageSize }))
```

**主要特性：**

- 基于 Alova 3
- 自动错误处理
- 请求/响应拦截
- 防重复请求
- 自动 loading 状态
- 支持缓存策略

### 14. Tauri 2 桌面应用支持

基于 **Tauri 2** 构建跨平台的桌面应用程序。

**主要特性：**

- 极小的应用体积（数 MB）
- 基于系统 WebView
- 原生性能
- 跨平台支持（Windows、macOS、Linux）
- 安全性高

**开发命令：**

```shell
# 启动 Tauri 开发模式
pnpm dev:tauri

# 构建 Tauri 应用
pnpm build:tauri

# 调试构建
pnpm build:tauri_debug
```

**配置说明：**

- 应用配置：`src-tauri/tauri.conf.json`
- 构建目标：根据平台自动选择
- 最小化：生产环境自动压缩

### 15. 强大的业务组件封装

项目提供了一系列高度封装的业务组件，显著提高开发效率。

#### CTable 通用表格组件

基于 **Element Plus Table** 的高级封装，提供开箱即用的表格解决方案。

**核心功能：**

- ✅ **自动分页与数据加载** - 基于 action 属性自动处理数据请求和分页
- ✅ **智能搜索表单** - 支持条件筛选，可展开/收起
- ✅ **列配置管理** - 显示/隐藏、拖拽排序、固定设置（左/右）
- ✅ **丰富工具栏** - 全屏、导出、尺寸调整、列设置
- ✅ **场景管理** - 保存和切换不同的表格配置场景
- ✅ **单元格编辑** - 支持自定义编辑器和数据校验
- ✅ **行选择功能** - 单选/多选，支持自定义选择条件
- ✅ **状态持久化** - 基于 IndexedDB 保存搜索条件、列设置、分页大小
- ✅ **自适应高度** - 根据容器自动调整表格高度
- ✅ **数据导出** - 支持 Excel 导出，可自定义导出逻辑
- ✅ **排序功能** - 支持自定义排序字段和排序方式

**其他业务组件：**

- **CDialog** - 通用对话框组件
- **CUpload** - 文件上传组件
- **CSelect** - 增强选择器组件
- **CEcharts** - 图表组件封装
- **CIcon** - 图标组件
- **CLoading** - 加载状态组件

##### Props

| 参数名          | 说明                                         | 类型                                                                | 默认值                              |
| --------------- | -------------------------------------------- | ------------------------------------------------------------------- | ----------------------------------- |
| action          | 数据加载方法或接口地址，支持 function/string | `Function/String`                                                   | 必填                                |
| model-value     | 选中数据数组                                 | `Array`                                                             | -                                   |
| full-value      | 是否返回完整行数据，false 时仅返回 row-key   | `Boolean`                                                           | `false`                             |
| default-size    | 默认分页尺寸                                 | `Number`                                                            | `10`                                |
| params          | 额外的请求参数                               | `Object`                                                            | -                                   |
| form-props      | 查询表单配置                                 | `Object`                                                            | -                                   |
| delay           | 防抖延时                                     | `Number`                                                            | -                                   |
| default-sort    | 默认排序字段                                 | `Object`                                                            | -                                   |
| order-key       | 排序字段键名                                 | `({ column, prop, order }) => ({ orderBy: '' })/String`             | `orderByColumn`                     |
| order-v-key     | 排序方向键名                                 | `String`                                                            | `isAsc`                             |
| sort-orders     | 排序方式选项数组                             | `Array`                                                             | `['ascending', 'descending', null]` |
| size            | 表格大小                                     | `String`                                                            | `small`                             |
| id              | 组件 ID，用于状态持久化                      | `String`                                                            | -                                   |
| tool-status     | 工具栏显示状态配置                           | `Object`                                                            | 见下方说明                          |
| default-form    | 表单默认值                                   | `Object`                                                            | `{}`                                |
| on-export       | 导出方法或接口                               | `(params) => Promise<void>/String`                                  | -                                   |
| export-name     | 导出文件名                                   | `String`                                                            | 当前页面标题                        |
| export-page     | 是否分页导出                                 | `Boolean`                                                           | `true`                              |
| selectable      | 行是否可选择的回调                           | `(row, index) => boolean`                                           | -                                   |
| editable        | 单元格是否可编辑                             | `(row, column, cell) => boolean/Boolean`                            | `false`                             |
| cell-validator  | 单元格编辑校验函数                           | `({  value, prop, row, column, cell }) =>  error message/undefined` | -                                   |
| search-props    | 搜索框属性                                   | `Object`                                                            | `{}`                                |
| hide-pager      | 隐藏分页                                     | `Boolean`                                                           | `false`                             |
| justify-content | 分页水平位置                                 | `String`                                                            | `right`                             |

###### tool-status 配置项说明

```js
{
  bar: 1,          // 是否显示工具栏，1显示，0隐藏
  search: 1,       // 是否显示搜索框
  filter: 1,       // 是否显示筛选按钮
  scene: 1,        // 是否显示场景管理
  download: 1,     // 是否显示导出按钮
  size: 1,         // 是否显示表格尺寸调整按钮
  save: 1,         // 是否显示保存按钮
  setting: 1,      // 是否显示列设置按钮
  fullscreen: 1    // 是否显示全屏按钮
}
```

##### Events

| 事件名             | 说明           | 参数                             |
| ------------------ | -------------- | -------------------------------- |
| update:model-value | 选中数据变化   | `(value: Array)`                 |
| query              | 查询条件变化   | `(params: Object)`               |
| reset              | 重置查询表单   | -                                |
| cell-click         | 单元格点击     | `(row, column, cell)`            |
| save               | 单元格编辑保存 | `({ prop, row, value, column })` |

##### Slots

| 插槽名      | 说明               | 参数                                 |
| ----------- | ------------------ | ------------------------------------ |
| default     | 表格列配置         | -                                    |
| form        | 查询表单内容       | `{ form, query }`                    |
| search      | 自定义搜索框       | `{ form, query }`                    |
| actions     | 自定义工具栏按钮   | -                                    |
| append      | 表格追加内容       | -                                    |
| empty       | 空数据显示内容     | -                                    |
| cell-editor | 自定义单元格编辑器 | `{ value, prop, row, column, cell }` |

##### Methods

| 方法名           | 说明           | 参数 |
| ---------------- | -------------- | ---- |
| refresh          | 刷新表格数据   | -    |
| refreshCurrent   | 刷新当前页数据 | -    |
| handleQuery      | 触发查询       | -    |
| handleQueryReset | 重置查询条件   | -    |
| handleSave       | 保存当前配置   | -    |
| handleExport     | 导出数据       | -    |
| toggleFullscreen | 切换全屏显示   | -    |

```html
<template>
  <CTable
    action="user/list"
    :search-props="{
      prop: 'nickname'
    }"
    ref="tableRef"
    id="userTable"
  >
    <el-table-column label="昵称" prop="nickname" />
    <el-table-column label="邮箱" prop="email" />
    <el-table-column label="创建时间" prop="createTime" />

    <template #form="{ form }">
      <el-form-item label="昵称" prop="nickname">
        <el-input v-model="form.nickname" placeholder="请输入昵称" clearable />
      </el-form-item>
      <el-form-item label="邮箱" prop="email">
        <el-input v-model="form.email" placeholder="请输入邮箱" clearable />
      </el-form-item>
    </template>

    <template #actions>
      <el-button type="primary" @click="handleAdd">
        <i-ep-plus />
        新增用户
      </el-button>
    </template>
  </CTable>
</template>
```

### 16. 丰富的图标系统

基于 **unplugin-icons** 提供海量图标支持。

**图标源：**

- **Element Plus Icons** - 主要图标库
- **Iconify** - 海量图标集合
- **自定义图标** - 支持本地 SVG

**使用示例：**

```html
<template>
  <!-- Element Plus 图标 -->
  <i-ep-user />
  <i-ep-setting />
  <i-ep-search />

  <!-- 使用 CIcon 组件 -->
  <CIcon icon="ep:user" />
  <CIcon icon="mdi:home" />
  <CIcon icon="lucide:heart" />
</template>
```

**主要特性：**

- 按需自动引入
- 支持多种图标库
- 自动优化 SVG
- 支持图标组件化

### 17. Composables 函数封装

项目提供了丰富的 Composables 函数，提高代码复用性。

**核心 Composables：**

- **useAsync** - 异步数据管理
- **useTheme** - 主题切换
- **useStorage** - 本地存储
- **useMitt** - 事件总线
- **usePermi** - 权限管理
- **useCacheData** - 数据缓存

**使用示例：**

```js
// 异步数据管理
const data = useAsync(() => req.get('/api/users'))
data.data
data.loading
data.run()
data.error

// 主题切换
const { isDark, toggle } = useTheme()

// 本地存储
const userInfo = useStorage('userInfo', {})
```

### 18. IndexedDB 本地存储

基于 IndexedDB 提供强大的本地数据存储能力。

**主要用途：**

- 表格状态持久化
- 用户偏好设置
- 离线数据缓存
- 场景配置保存

### 19. 项目结构

```text
src/
├── components/          # 通用组件
├── composables/         # 组合式函数
├── layouts/            # 布局组件
├── locales/            # 国际化文件
├── plugins/            # 插件配置
├── router/             # 路由配置
├── store/              # 状态管理
├── styles/             # 样式文件
├── utils/              # 工具函数
├── views/              # 页面组件
└── test/               # 测试文件
```

## 技术栈版本

| 技术         | 版本    | 说明       |
| ------------ | ------- | ---------- |
| Vue          | 3.5.21  | 渐进式框架 |
| Vite         | 5.4.20  | 构建工具   |
| Element Plus | 2.11.2  | UI 组件库  |
| Pinia        | 3.0.3   | 状态管理   |
| Vue Router   | 4.5.1   | 路由管理   |
| Vue I18n     | 11.1.12 | 国际化     |
| Alova        | 3.3.4   | 请求库     |
| Vitest       | 3.2.4   | 测试框架   |
| Tauri        | 2.8.4   | 桌面应用   |
| ECharts      | 6.0.0   | 图表库     |

## License

Made with ❤️

Published under [MIT License](./LICENSE).

<br />