feat: add docs

2026-01-29 22:44:36 +08:00
parent 110aec7d5f
commit c214c11244
10 changed files with 573 additions and 7 deletions
--- a/docs/.vitepress/config.ts
+++ b/docs/.vitepress/config.ts
@@ -0,0 +1,49 @@
+import { defineConfig } from "vitepress";
+import {
+  groupIconMdPlugin,
+  groupIconVitePlugin,
+} from "vitepress-plugin-group-icons";
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+  title: "Hucky 操作指南",
+  description: "帮助您快速入门",
+  themeConfig: {
+    // https://vitepress.dev/reference/default-theme-config
+    nav: [
+      { text: "首页", link: "/" },
+      { text: "文档", link: "/quick_start/dependencies" },
+    ],
+
+    sidebar: [
+      {
+        text: "快速上手",
+        items: [{ text: "依赖项介绍", link: "/quick_start/dependencies" }],
+      },
+      {
+        text: "脚手架特色",
+        items: [{ text: "自动路由", link: "/cli_feature/auto_router" }],
+      },
+    ],
+
+    socialLinks: [
+      {
+        icon: "github",
+        link: "https://github.com/gushen610140/template-vue-hucky",
+      },
+      {
+        icon: "gitea",
+        link: "http://113.46.158.62:3000/gushen/template-vue-hucky",
+      },
+    ],
+  },
+  markdown: {
+    config: (md) => {
+      // 使用插件为代码块丰富样式
+      md.use(groupIconMdPlugin);
+    },
+  },
+  vite: {
+    plugins: [groupIconVitePlugin()],
+  },
+});
--- a/docs/.vitepress/theme/index.ts
+++ b/docs/.vitepress/theme/index.ts
@@ -0,0 +1,8 @@
+// .vitepress/theme/index.ts
+import DefaultTheme from "vitepress/theme";
+
+import "virtual:group-icons.css"; //代码组样式
+
+export default {
+  extends: DefaultTheme,
+};
--- a/docs/.vitepress/theme/style/index.css
+++ b/docs/.vitepress/theme/style/index.css
@@ -0,0 +1,2 @@
+/* .vitepress/theme/style/index.css */
+@import './vp-code-title.css';
--- a/docs/.vitepress/theme/style/vp-code-title.css
+++ b/docs/.vitepress/theme/style/vp-code-title.css
@@ -0,0 +1,68 @@
+/* .vitepress/theme/style/vp-code-title.css */
+
+/* 整体容器样式（带阴影和圆角） */
+.vp-code-block-title {
+  background-color: var(--vp-code-block-bg);
+  margin-bottom: 20px;
+  border-radius: 8px;
+  box-shadow: 0 10px 30px 0 rgba(0, 0, 0, 0.4); /* 添加阴影 */
+  overflow: hidden;
+  position: relative; /* 确保小圆点定位 */
+}
+
+/* Mac 风格的小圆点，放在容器顶部 */
+.vp-code-block-title::before {
+  content: '';
+  position: absolute;
+  top: 12px; /* 圆点距离容器顶部的距离 */
+  left: 12px;
+  width: 12px;
+  height: 12px;
+  background-color: #fc625d; /* 红色圆点 */
+  border-radius: 50%;
+  box-shadow: 20px 0 #fdbc40, 40px 0 #35cd4b; /* 黄色和绿色圆点 */
+  z-index: 1;
+}
+
+/* 标题栏样式 */
+.vp-code-block-title .vp-code-block-title-bar {
+  color: var(--vp-c-text-1);
+  font-size: 14px;
+  font-weight: bold;
+}
+
+/* 代码块标题：修正倒角、阴影、边距 */
+.vp-code-block-title div[class*="language-"].vp-adaptive-theme.line-numbers-mode {
+  border-radius: 8px;
+  box-shadow: none;
+  padding-top: 0px;
+  margin-bottom: 0px;
+}
+
+/* 代码块标题：隐藏小圆点 */
+.vp-code-block-title div[class*="language-"].vp-adaptive-theme.line-numbers-mode::before {
+  display: none;
+}
+
+/* 代码块标题：修正行号位置 */
+.vp-code-block-title .line-numbers-mode .line-numbers-wrapper {
+  padding-top: 20px;
+}
+
+/* 代码块标题：修正行号右侧竖线位置 */
+.vp-code-block-title .line-numbers-mode .line-numbers-wrapper::after {
+  top: 20px;
+  height: calc(100% - 40px);
+}
+
+/* 代码块标题（无行号）：修正倒角、阴影、边距 */
+.vp-code-block-title div[class*="language-"].vp-adaptive-theme {
+  border-radius: 8px;
+  box-shadow: none;
+  padding-top: 0px;
+}
+
+/* 代码块标题（无行号）：隐藏小圆点 */
+.vp-code-block-title div[class*="language-"].vp-adaptive-theme::before {
+  display: none;
+}
--- a/docs/cli_feature/auto_router.md
+++ b/docs/cli_feature/auto_router.md
@@ -0,0 +1,86 @@
+# 自动路由系统
+
+## 背景
+
+前端路由的出现，主要是为了解决 **单页应用（SPA）** 在用户体验和开发模式上的核心痛点，它已经成为现代前端开发的基础能力之一。
+
+单页应用（SPA）的核心特点是只有一个 HTML 文件，所有页面内容都通过 JavaScript 动态切换。如果没有前端路由：
+
+- 用户在不同页面间切换时，浏览器的 URL 不会变化。
+- 刷新页面会直接回到应用初始状态，之前的操作和页面状态全部丢失。
+- 无法通过浏览器的「前进 / 后退」按钮导航，也不能用书签保存当前页面。
+
+前端路由通过监听 URL 变化（如 /#/home 或 /home），动态渲染对应的组件，让 URL 和页面内容保持同步，彻底解决了这个问题。
+
+## 开启 SPA
+
+脚手架默认自动启用
+
+```vue [App.vue] {5}
+<script lang="ts" setup></script>
+
+<template>
+  <div>
+    <router-view /> // 使用 vue router 依赖作为支持
+  </div>
+</template>
+
+<style scoped></style>
+```
+
+## 常规注册路由
+
+:::tip
+注意在 hucky 中不使用常规注册方法
+:::
+
+路由器实例是通过调用 `createRouter()` 函数创建的
+
+```ts {7-10}
+import { createMemoryHistory, createRouter } from 'vue-router'
+
+import HomeView from './HomeView.vue'
+import AboutView from './AboutView.vue'
+
+// 通过手动编写 path 和引入 vue 文件来配置路由
+const routes = [
+  { path: '/', component: HomeView },
+  { path: '/about', component: AboutView },
+]
+
+const router = createRouter({
+  history: createMemoryHistory(),
+  routes,
+})
+```
+
+## 组织页面文件
+
+在 Hucky 中，按照文件资源路径自动渲染为路由路径
+
+```plain {7-12}
+.
+├─ src
+│  ├─ apis
+│  ├─ assets
+│  ├─ components
+│  ├─ ...
+│  ├─ pages
+│  │  ├─ index.vue --> /
+│  │  ├─ user
+│  │  │  │─ index.vue --> /user
+│  │  │  │─ account.vue --> /user/account
+│  │  └─ └─ change-password.vue --> /user/change-password
+│  ├─ ...
+│  └─ App.vue
+├─ index.html
+└─ package.json
+```
+
+::: warning
+页面文件统一使用小写+中划线方式命名
+:::
+
+## 特殊规则
+
+在 `/src/router/rules` 中通过字符串匹配的方式为 router 中的某个路径添加规则
--- a/docs/index.md
+++ b/docs/index.md
@@ -0,0 +1,25 @@
+---
+# https://vitepress.dev/reference/default-theme-home-page
+layout: home
+
+hero:
+  name: "Hucky 操作指南"
+  text: "帮助您快速入门"
+  tagline: 标准化的开发规范脚手架
+  actions:
+    - theme: brand
+      text: 熟悉依赖项
+      link: /quick_start/dependencies
+    - theme: alt
+      text: 自动路由
+      link: /cli_feature/auto_router
+
+features:
+  - title: 样式规范化
+    details: 统一组件库选择与组件封装模式
+  - title: 常用 util 封装
+    details: 涵盖 axios 封装到函数式 toast 一站式解决方案
+  - title: 检查代码格式
+    details: 规范的 prettier 和 eslint 检查
+---
+
--- a/docs/quick_start/dependencies.md
+++ b/docs/quick_start/dependencies.md
@@ -0,0 +1,64 @@
+# 项目依赖项介绍文档
+
+## 一、生产依赖 (dependencies)
+
+生产依赖是项目运行时必须的核心依赖，保障应用在生产环境正常工作。
+
+### 1. 核心框架
+
+- **vue**: Vue.js 3.x 核心库，用于构建用户界面的渐进式 JavaScript 框架，提供响应式数据绑定、组件化开发等能力，是整个项目的基础。
+
+### 2. 状态管理
+
+- **pinia**: Vue 官方推荐的状态管理库，支持 Vue 2 和 Vue 3，采用模块化设计，提供简洁的 API 来管理应用全局状态，替代了传统的 Vuex。
+- **pinia-plugin-persistedstate**: Pinia 的持久化插件，可将 Pinia 中的状态持久化到本地存储（如 `localStorage`），页面刷新后状态不丢失，提升用户体验。
+
+### 3. 路由管理
+
+- **vue-router**: Vue 官方路由管理器，用于构建单页应用的路由系统，实现组件之间的导航、参数传递和路由守卫等功能。
+
+### 4. 网络请求
+
+- **axios**: 基于 Promise 的 HTTP 客户端，支持浏览器和 Node.js，用于发送异步请求、拦截请求/响应、统一处理错误等，是前后端数据交互的核心工具。
+
+### 5. UI 组件与样式
+
+- **daisyui**: 基于 Tailwind CSS 的组件库，提供丰富的预定义 UI 组件（如按钮、卡片、模态框等），简化页面开发，支持主题定制和响应式设计。
+
+### 6. 工具库
+
+- **@vueuse/core**: Vue 组合式 API 的实用工具集，封装了大量常用功能（如防抖、节流、本地存储、事件监听等），开箱即用，提升开发效率。
+- **radash**: 现代 JavaScript 实用工具库，提供函数式编程风格的工具函数，简化数组、对象、异步操作等场景的处理，补充原生 JS 能力。
+- **motion-v**: Vue 3 的动画库，基于 Web Animations API，用于创建流畅的过渡和动画效果，支持组件级别的动画控制，让交互更生动。
+
+## 二、开发依赖 (devDependencies)
+
+开发依赖仅在开发阶段使用，用于提升开发效率、保障代码质量、辅助构建与测试等。
+
+### 1. 构建工具
+
+- **vite**: 下一代前端构建工具，基于 ES 模块，提供极速的热更新和构建速度，支持 Vue、React 等框架，是项目的核心构建引擎。
+- **vitepress**: 基于 Vite 和 Vue 的静态站点生成器，用于构建文档网站，支持 Markdown 编写和自定义主题，适合项目文档维护。
+- **@vitejs/plugin-vue** / **@vitejs/plugin-vue-jsx**: Vite 官方插件，分别用于支持 Vue 单文件组件（SFC）和 Vue 中的 JSX 语法，扩展 Vite 对 Vue 的支持能力。
+- **@vue/babel-plugin-jsx**: Babel 插件，用于在 Vue 项目中支持 JSX 语法，增强组件的灵活性和表达力。
+- **unplugin-auto-import**: 自动导入插件，可自动导入 Vue、Vue Router、Pinia 等 API，无需手动编写 `import` 语句，减少样板代码。
+
+### 2. CSS 框架与工具
+
+- **tailwindcss**: 实用优先的 CSS 框架，通过原子化类名快速构建自定义 UI，支持响应式设计和主题定制，是现代前端开发的流行选择。
+- **@tailwindcss/vite**: Tailwind CSS 的 Vite 插件，实现 Tailwind 的热更新和按需编译，提升开发体验，确保样式开发的高效性。
+
+### 3. 类型检查
+
+- **typescript**: 静态类型检查的 JavaScript 超集，增强代码的可维护性和可读性，支持 Vue 3 的类型推导，是大型项目的必备工具。
+- **vue-tsc**: Vue 项目的 TypeScript 类型检查工具，基于 TypeScript 编译器，对 Vue 单文件组件进行类型校验，保障类型安全。
+- **@vue/tsconfig**: Vue 官方提供的 TypeScript 配置文件模板，包含 Vue 项目的最佳实践配置，简化 TS 配置流程。
+- **@types/node**: Node.js 的类型定义文件，为 Node.js API 提供类型提示，提升 Node.js 相关代码的开发体验。
+
+### 4. 代码规范
+
+- **eslint**: 可扩展的 JavaScript 代码检查工具，用于发现代码中的语法错误、风格问题和潜在 Bug，保障代码质量。
+- **eslint-plugin-vue**: ESLint 插件，针对 Vue 单文件组件提供特定的代码规则检查，如模板语法、组件生命周期等，是 Vue 项目规范的核心工具。
+- **eslint-plugin-react** / **eslint-plugin-react-hooks**: ESLint 插件，用于检查 React 代码和 React Hooks 的使用规范（注：若项目以 Vue 为主，可能为遗留配置或多框架支持场景）。
+- **typescript-eslint**: ESLint 与 TypeScript 集成的工具集，提供 TypeScript 代码的检查规则，保障 TS 代码质量。
+- **prettier**: 代码格式化工具，支持多种语言，自动统一代码风格，与 ESLint 配合使用可实现“检查+格式化”的完整工作流，提升团队协作效率。