Vue3 Mobile

--- name: vue3-mobile-starter description: 快速搭建 Vue3 移动端应用（TS、Router、Pinia、SCSS、Vant、Vite、Axios、px-to-viewport）。当用户创建新的 Vue3 移动端项目时调用。 --- # 技能详细说明用于快速初始化 Vue3 移动端项目骨架，内置 TypeScript、Vue Router、Pinia、SCSS、Vant、Vite、Axios、postcss-px-to-viewport-8-plugin。遵循本项目规范输出文件模板与执行步骤，确保以 pnpm 安装与运行。 ## 1. 核心规范 - 技术栈：Vue 3 + TypeScript + Vite + Pinia + Vue Router + Axios + SCSS + Vant - 构建工具：Vite（包含 PostCSS 配置，使用 postcss-px-to-viewport-8-plugin） - 包管理器：pnpm（必须使用 pnpm 安装与运行脚本） - 移动端适配：vw 转换（viewportWidth 推荐 375），附加完整可调参数 - 目录结构：清晰分层（router、store、styles、utils、views、components） - 代码要求：函数需具备 JSDoc 注释，包含参数、返回值、异常；变量需添加用途注释 ## 2. 代码结构模板以下模板可直接复制到新工程中使用。按需调整命名与路径。 ### 2.1 package.json（片段）说明：确保使用 pnpm 脚本与常用命令。 ```json { "name": "vue3-mobile-starter", "private": true, "version": "0.0.1", "type": "module", "scripts": { "dev": "vite", "build": "vite build", "preview": "vite preview --port 5173" }, "dependencies": { "axios": "^1.6.8", "pinia": "^2.1.7", "vant": "^4.8.0", "vue": "^3.4.0", "vue-router": "^4.3.0" }, "devDependencies": { "autoprefixer": "^10.4.18", "postcss": "^8.4.35", "postcss-px-to-viewport-8-plugin": "^1.2.0", "sass": "^1.71.1", "typescript": "^5.3.3", "vite": "^5.1.0", "@types/node": "^20.11.25" } } ``` ### 2.2 tsconfig.json（基础） ```json { "compilerOptions": { "target": "ES2020", "useDefineForClassFields": true, "module": "ESNext", "moduleResolution": "Bundler", "strict": true, "jsx": "preserve", "resolveJsonModule": true, "isolatedModules": true, "esModuleInterop": true, "lib": ["ES2020", "DOM", "DOM.Iterable"], "baseUrl": ".", "paths": { "@/*": ["src/*"] } }, "include": ["src/**/*.ts", "src/**/*.d.ts", "src/**/*.tsx", "src/**/*.vue"] } ``` ### 2.3 vite.config.ts（含 PostCSS 与别名） ```ts import { defineConfig } from "vite"; import vue from "@vitejs/plugin-vue"; import path from "node:path"; import pxToViewport from "postcss-px-to-viewport-8-plugin"; export default defineConfig({ plugins: [vue()], resolve: { alias: { "@": path.resolve(__dirname, "src"), }, }, css: { preprocessorOptions: { scss: { additionalData: `@use "@/styles/variables.scss" as *;`, }, }, postcss: { plugins: [ pxToViewport({ unitToConvert: "px", viewportWidth: 375, unitPrecision: 6, propList: ["*"], viewportUnit: "vw", fontViewportUnit: "vw", selectorBlackList: [".ignore", ".hairlines"], minPixelValue: 1, mediaQuery: false, replace: true, exclude: [], landscape: false, }), ], }, }, server: { port: 5173, open: true, }, }); ``` ### 2.4 postcss.config.js（可选，若不在 Vite 中内联） ```js /* eslint-disable @typescript-eslint/no-var-requires */ const pxToViewport = require("postcss-px-to-viewport-8-plugin"); module.exports = { plugins: [ pxToViewport({ unitToConvert: "px", viewportWidth: 375, unitPrecision: 6, propList: ["*"], viewportUnit: "vw", fontViewportUnit: "vw", selectorBlackList: [".ignore", ".hairlines"], minPixelValue: 1, mediaQuery: false, replace: true, exclude: [], landscape: false, }), ], }; ``` ### 2.5 index.html（视口） ```html Vue3 Mobile

``` ### 2.6 src/main.ts（应用入口） ```ts import { createApp } from "vue"; import { createPinia } from "pinia"; import { router } from "@/router"; import App from "./App.vue"; import "vant/lib/index.css"; import "@/styles/index.scss"; import { Button } from "vant"; // app: 应用实例 const app = createApp(App); // store: 全局状态管理 const store = createPinia(); /** * 初始化应用 * @throws Error 初始化过程中抛出的未捕获异常 * @returns void 无返回值 */ function bootstrap(): void { // 注册 Pinia app.use(store); // 注册路由 app.use(router); // 注册基础 Vant 组件（示例） app.use(Button); // 挂载应用 app.mount("#app"); } bootstrap(); ``` ### 2.7 src/router/index.ts（路由） ```ts import { createRouter, createWebHistory, RouteRecordRaw } from "vue-router"; // routes: 路由表 const routes: RouteRecordRaw[] = [ { path: "/", name: "home", component: () => import("@/views/Home.vue"), }, ]; /** * 创建并导出路由实例 * @returns 路由实例 * @throws Error 当路由初始化失败时抛出 */ export const router = createRouter({ history: createWebHistory(import.meta.env.BASE_URL), routes, }); ``` ### 2.8 src/store/index.ts（Pinia） ```ts import { createPinia } from "pinia"; /** * 创建 Pinia 实例（在 main.ts 中使用） * @returns Pinia 实例 */ export function setupStore() { // pinia: 全局状态实例 const pinia = createPinia(); return pinia; } ``` ### 2.9 src/store/modules/app.ts（示例 Store） ```ts import { defineStore } from "pinia"; // AppState: 应用状态类型 interface AppState { // title: 应用标题 title: string; } /** * 应用级 Store * @param 无 * @returns Store 实例 * @throws Error 无特别异常 */ export const useAppStore = defineStore("app", { state: (): AppState => ({ title: "Vue3 Mobile", }), actions: { /** * 设置标题 * @param newTitle 新标题 * @returns void 无返回值 * @throws Error 当 newTitle 非法时可能抛出 */ setTitle(newTitle: string): void { this.title = newTitle; }, }, }); ``` ### 2.10 src/utils/request.ts（Axios 封装） ```ts import axios, { AxiosInstance, AxiosRequestConfig, AxiosResponse } from "axios"; // BASE_TIMEOUT: 基础超时时间（毫秒） const BASE_TIMEOUT = 15000; /** * 创建 Axios 实例 * @returns Axios 实例 * @throws Error 创建实例失败 */ function createService(): AxiosInstance { // service: Axios 实例 const service = axios.create({ baseURL: import.meta.env.VITE_API_BASE_URL || "/", timeout: BASE_TIMEOUT, }); // 请求拦截 service.interceptors.request.use( (config: AxiosRequestConfig) => { // token: 鉴权令牌 const token = ""; if (token) { config.headers = config.headers || {}; config.headers.Authorization = `Bearer ${token}`; } return config; }, (error) => { return Promise.reject(error); }, ); // 响应拦截 service.interceptors.response.use( (response: AxiosResponse) => { return response.data; }, (error) => { return Promise.reject(error); }, ); return service; } // http: 全局复用的 Axios 实例 export const http = createService(); /** * 通用请求方法 * @template T 返回数据类型 * @param config Axios 请求配置 * @returns Promise 响应数据 * @throws Error 网络错误或业务异常 */ export function request(config: AxiosRequestConfig): Promise { return http.request(config); } ``` ### 2.11 src/styles/variables.scss（变量示例） ```scss // $primary-color: 主题色 $primary-color: #1989fa; ``` ### 2.12 src/styles/index.scss（全局样式） ```scss /* 基础重置与通用样式 */ html, body, #app { height: 100%; } body { margin: 0; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, "Noto Sans", "Apple Color Emoji", "Segoe UI Emoji"; -webkit-font-smoothing: antialiased; -moz-osx-font-smoothing: grayscale; background-color: #fff; } .text-primary { color: $primary-color; } ``` ### 2.13 src/views/Home.vue（示例页面） ```vue ``` ### 2.14 src/App.vue（应用根组件） ```vue ``` ### 2.15 环境变量（.env.development 示例） ```env VITE_API_BASE_URL=/api ``` ## 3. 注意事项 1. 统一使用 pnpm：安装与运行脚本均使用 pnpm（避免 npm/yarn）。 2. Vant 引入：示例仅展示按钮组件按需注册，实际项目请按需引入其他组件。 3. px-to-viewport：推荐 viewportWidth=375；若视觉稿为 750，可设置 750，并据此调整设计规范。 4. 字体与 1px 细线：如需对特定选择器禁用转换，使用 `.ignore` 前缀或设置 selectorBlackList。 5. Axios 封装：根据后端返回结构调整响应拦截与错误处理逻辑；谨慎处理 token。 6. 样式组织：建议使用 SCSS 模块与变量管理主题；按需覆盖 Vant 样式变量。 ## 4. 执行步骤 1. 创建模板工程（Vue + TS）： - pnpm create vite my-app --template vue-ts 2. 进入目录并安装依赖： - cd my-app - pnpm add vue-router pinia axios vant - pnpm add -D sass postcss autoprefixer postcss-px-to-viewport-8-plugin 3. 配置 Vite 与 PostCSS： - 复制 2.3 的 vite.config.ts（或使用 2.4 的 postcss.config.js） 4. 建立目录与文件： - src/router、src/store、src/utils、src/styles、src/views - 复制 2.6～2.15 示例文件 5. 运行与预览： - pnpm dev - pnpm build && pnpm preview 6. 可选优化： - 引入按需自动导入（unplugin-auto-import/unplugin-vue-components）进一步简化 Vant 使用 - 接入 ESLint/Prettier/Husky 保障代码质量当用户需要从零创建新的 Vue3 移动端项目且要求集成 TypeScript、Vue Router、Pinia、SCSS、Vant、Vite、Axios 与 postcss-px-to-viewport-8-plugin 时，调用本技能以生成模板与步骤清单。