English |简体中文

🚀 特性一览

📁 目录结构

src/├── apis/                # API 接口│   ├── modules/        # 按模块组织的API│   │   ├── user.ts     # 用户相关API│   │   └── script.ts   # 脚本相关API│   ├── types/          # API类型定义│   └── index.ts        # 统一导出├── assets/             # 静态资源│   └── icons/          # 图标资源├── components/         # 公共组件│   ├── SvgIcon/       # SVG图标组件│   ├── InconFent/     # Iconfront图标组件│   └── ThemeSwitch/   # 主题切换组件├── hooks/              # 自定义Hooks│   ├── useNProgress.ts # 进度条Hook│   └── useThemeTransition.ts # 主题切换过渡动画Hook├── router/             # 路由配置│   ├── home/          # 首页路由模块│   ├── login/         # 登录路由模块│   └── index.ts       # 路由主文件├── stores/             # 状态管理│   ├── theme.ts       # 主题状态│   ├── token.ts       # Token管理│   ├── user.ts        # 用户信息│   └── login.ts       # 登录状态├── styles/             # 全局样式│   ├── themes/        # 主题相关│   │   └── variables.scss # 主题变量定义│   ├── transitions/   # 过渡动画│   │   └── theme.scss # 主题切换动画│   └── mixins/        # 样式混入├── utils/             # 工具函数│   ├── http/         # HTTP请求封装│   ├── device.ts     # 设备信息│   └── index.ts      # 工具统一导出└── views/            # 页面组件    ├── login/        # 登录页面    ├── home/         # 首页    ├── settings/     # 设置页面    └── error/        # 错误页面

📚 项目规范指南

1. 项目介绍规范

2. 项目结构规范

3. API 使用规范

4. 代码注释规范

5. 核心 Hooks 与方法

6. 新增模块规范

7. 代码风格规范

🛠️ 快速开始

安装依赖

pnpm install

开发环境

# PC端开发pnpm dev# H5端开发pnpm dev:h5

生产环境

# PC端生产环境pnpm pro# H5端生产环境pnpm proH5

构建项目

# PC端构建(开发环境)pnpm build:dev# H5端构建(开发环境)pnpm build:dev:h5# PC端构建(生产环境)pnpm build:prod# H5端构建(生产环境)pnpm build:prod:h5

📘 开发指南

主题系统

1. 主题配置

// 基础变量定义$themes: (light: (// 亮色主题--primary-color:#409eff,--bg-color:#ffffff,--text-primary:#303133,// 更多变量...  ),dark: (// 暗色主题--primary-color:#409eff,--bg-color:#141414,--text-primary:#ffffff,// 更多变量...  ),// 可以添加更多自定义主题...red:    (--primary-color:#f56c6c,// 红色主题的其他变量...    ),);

2. 使用主题切换组件

<template>  <divclass="container"><!-- 主题切换按钮-->    <ThemeSwitch /><!-- 页面内容-->  </div></template><script setup lang="ts">importThemeSwitchfrom"@/components/ThemeSwitch/index.vue";import {useThemeStore }from"@/stores/theme";// 获取主题状态管理实例const themeStore=useThemeStore();// 在组件挂载时初始化主题onMounted(()=> {themeStore.initTheme();});</script>

3. 在父容器中应用主题

<template>  <divclass="app-container"><!-- 页面内容-->  </div></template><style lang="scss">// 导入主题过渡动画样式@import"@/styles/transitions/theme.scss";.app-container {// 使用主题混入@includeuseTheme;// 使用主题变量background:var(--bg-color);color:var(--text-primary);}</style>

4. 主题状态管理

import{useThemeStore}from"@/stores/theme";constthemeStore=useThemeStore();// 切换到暗色主题themeStore.setTheme("dark");// 切换到亮色主题themeStore.setTheme("light");// 切换到自定义主题themeStore.setTheme("red");// 切换暗黑/亮色模式themeStore.toggleDarkMode();// 获取当前主题console.log(themeStore.currentTheme);// 检查是否为暗黑模式console.log(themeStore.isDarkMode);

5. 主题过渡动画

import{useThemeTransition}from"@/hooks/useThemeTransition";const{ handleThemeChange}=useThemeTransition();// 切换主题并应用过渡动画// 参数1: 目标主题// 参数2: 触发元素 (可选，用于动画起点)// 参数3: 动画选项 (可选)handleThemeChange("dark",triggerElement,{duration:500,easing:"cubic-bezier(0.4, 0, 0.2, 1)",});

6. 自定义主题

$themes: (light: (/* 亮色主题变量*/  ),dark: (/* 暗色主题变量*/  ),// 添加新主题purple:    (--primary-color:#722ed1,--bg-color:#f9f0ff,--text-primary:#333333,// 其他变量...    ),);

API 请求

1. 创建 API 模块

// src/apis/modules/product.tsimportaxiosInstancefrom"@/utils/http";importtype{RequestData}from"../types/common";interfaceProductParams{id:string;name:string;}// 获取产品列表exportconstgetProducts=(params:ProductParams)=>{constrequestData:RequestData<ProductParams>={parameter:params,};returnaxiosInstance.post("/api/products",requestData);};

2. 导出 API 模块

// src/apis/index.tsexport*asuserApifrom"./modules/user";export*asscriptApifrom"./modules/script";export*asproductApifrom"./modules/product";// 新增

3. 使用 API

// 方式1: 直接导入import{getProducts}from"@/apis/modules/product";// 方式2: 通过统一导出使用import{productApi}from"@/apis";constfetchData=async()=>{try{// 方式1constres1=awaitgetProducts({id:"1",name:"test"});// 方式2constres2=awaitproductApi.getProducts({id:"1",name:"test"});console.log(res1,res2);}catch(error){console.error(error);}};

状态管理

1. 创建 Store

// src/stores/product.tsimport{defineStore}from"pinia";interfaceProduct{id:string;name:string;price:number;}interfaceProductState{products:Product[];loading:boolean;}exportconstuseProductStore=defineStore("productStore",{state:():ProductState=>({products:[],loading:false,}),getters:{totalProducts:(state)=>state.products.length,totalPrice:(state)=>state.products.reduce((sum,product)=>sum+product.price,0),},actions:{setProducts(products:Product[]){this.products=products;},addProduct(product:Product){this.products.push(product);},asyncfetchProducts(){this.loading=true;try{// 使用API获取数据const{ data}=awaitproductApi.getProducts({});this.setProducts(data);}catch(error){console.error(error);}finally{this.loading=false;}},},// 持久化配置persist:true,});

2. 使用 Store

import{useProductStore}from"@/stores/product";// 在setup中使用constproductStore=useProductStore();// 读取状态console.log(productStore.products);console.log(productStore.totalProducts);// getter// 修改状态productStore.setProducts([...]);productStore.addProduct({id:"1",name:"Product 1",price:99});// 调用异步actionproductStore.fetchProducts();

路由管理

1. 创建页面组件

<!-- src/views/product/index.vue--><template>  <divclass="product-container">    <h1>产品列表</h1>    <divv-if="loading">加载中...</div>    <ulv-else>      <liv-for="item in products":key="item.id">        {{ item.name }} - {{ item.price }}      </li>    </ul>  </div></template><script setup lang="ts">import {onMounted,ref }from"vue";import {productApi }from"@/apis";const products=ref([]);const loading=ref(false);const fetchProducts=async ()=> {loading.value=true;try {const { data }=awaitproductApi.getProducts({});products.value=data;  }catch (error) {console.error(error);  }finally {loading.value=false;  }};onMounted(()=> {fetchProducts();});</script>

2. 创建路由模块

// src/router/product/productRouter.tsconstproductRouter=[{path:"/products",name:"Products",component:()=>import("@/views/product/index.vue"),meta:{requiresAuth:true,title:"产品列表",},},{path:"/products/:id",name:"ProductDetail",component:()=>import("@/views/product/detail.vue"),meta:{requiresAuth:true,title:"产品详情",},},];exportdefaultproductRouter;

3. 注册路由模块

// src/router/index.tsimport{createRouter,createWebHistory}from"vue-router";importhomeRouterfrom"./home/homeRouter";importloginRouterfrom"./login/loginRouter";importproductRouterfrom"./product/productRouter";// 新增constroutes=[// 其他路由...  ...homeRouter,  ...loginRouter,  ...productRouter,// 注册产品路由];constrouter=createRouter({history:createWebHistory(),  routes,});exportdefaultrouter;

环境变量配置

# .env.developmentVITE_NODE_ENV=developmentVITE_API_BASE_URL=/apiVITE_TEST_URL=http://dev-api.example.comVITE_PRO_URL=http://api.example.com

// 使用环境变量constapiUrl=import.meta.env.VITE_API_BASE_URL;console.log(`当前环境:${import.meta.env.VITE_NODE_ENV}`);

Vite 配置解析

1. 自动导入

// 自动导入Vue API、Element Plus和Vant组件AutoImport({imports:["vue"],// 自动导入Vue APIresolvers:[ElementPlusResolver(),VantResolver()],});// 自动导入组件Components({resolvers:[ElementPlusResolver(),VantResolver()],});

2. 全局样式注入

css:{  preprocessorOptions:{    scss:{      additionalData:`        @import "@/styles/themes/variables.scss";        @import "@/styles/mixins/theme.scss";        @import "@/styles/mixins/common.scss";      `;}}}

3. SVG 图标系统

createSvgIconsPlugin({iconDirs:[path.join(__dirname,"src/assets/icons/svg")],symbolId:"icon-[name]",});

4. 构建优化

build:{minify:"terser",rollupOptions:{output:{manualChunks(id){// 不同依赖库提取到独立的文件if(id.includes('node_modules')){returnid.toString().split('node_modules/')[1].split('/')[0].toString();}}}}}

5. 路径别名

resolve:{alias:{'@':path.resolve(__dirname,'src'),'@c':path.resolve(__dirname,'src/components'),'@u':path.resolve(__dirname,'src/utils')}}

🧩 最佳实践

组件开发规范

<!-- 推荐的组件结构--><template>  <divclass="product-card"><!-- 组件内容-->  </div></template><script setup lang="ts">// Props定义interfaceProps {  product: {    id:string;    name:string;    price:number;  };  showDetails?:boolean;}// 默认值const props=withDefaults(defineProps<Props>(), {  showDetails:false,});// 事件const emit=defineEmits<{  (e:"select",id:string):void;  (e:"delete",id:string):void;}>();</script><style lang="scss" scoped>.product-card {@includeflex(column,flex-start,stretch);// 使用主题变量color:var(--text-primary);background-color:var(--bg-color);}</style>

API 开发规范

状态管理规范

📝 许可证

👨‍💻 作者