Cursor Rules - Web 前端开发规范

适用范围

项目目录: web/ (基于 Vue 3 + TypeScript + Element Plus)
开发环境: Node.js 20.15.x+, npm 10.7.x+
前端访问: http://localhost (默认 80 端口)

Web 前端开发规范 (web/)

1. 技术栈规范

核心技术

框架: Vue 3.5.13 + TypeScript 5.8.3
UI 组件库: Element Plus 2.9.8
构建工具: Vite 7.0.9
状态管理: Pinia
路由管理: Vue Router 4
HTTP 客户端: Axios
代码风格: ESLint + Prettier
Node.js: 20.15.x+ (推荐 20.15.0)
npm: 10.7.x+

环境要求

开发环境: 支持本地环境或阿里云测试环境
数据库: MySQL/Redis 支持本机安装或使用阿里云环境
前端访问: http://localhost (默认 80 端口)
后端服务: http://localhost:8080

2. Art Design Pro UI 规范

设计理念

基于 Art Design Pro 的设计语言，追求现代化、精致、用户友好的界面体验。注重细节、动效和用户交互的流畅性。

颜色系统

主色调 (Primary Colors)

--art-primary: 93, 135, 255; /* 主品牌色 - 蓝色 */
--art-secondary: 73, 190, 255; /* 辅助色 - 天蓝色 */
--art-success: 19, 222, 185; /* 成功色 - 绿色 */
--art-warning: 255, 174, 31; /* 警告色 - 橙色 */
--art-error: 250, 137, 107; /* 错误色 - 红色 */
--art-info: 83, 155, 255; /* 信息色 - 蓝色 */
--art-danger: 255, 77, 79; /* 危险色 - 红色 */

背景色系统

/* 浅色主题 */
--art-bg-color: #fafbfc; /* 页面底色 */
--art-main-bg-color: #ffffff; /* 主要内容背景 */
--art-bg-primary: 236, 242, 255; /* 主色背景 */
--art-bg-secondary: 232, 247, 255; /* 辅助背景 */
--art-bg-success: 230, 255, 250; /* 成功背景 */
--art-bg-warning: 254, 245, 229; /* 警告背景 */
--art-bg-error: 253, 237, 232; /* 错误背景 */

/* 暗色主题 */
html.dark {
    --art-bg-color: #070707; /* 页面底色 */
    --art-main-bg-color: #161618; /* 主要内容背景 */
}

轮廓式按钮设计系统

🎨 设计理念

全面采用轮廓式（Outline）按钮设计，提供更加优雅、现代和一致的用户界面体验。

核心规范

Primary 按钮: 轮廓式主色设计，主色边框和文字，5%透明度主色背景
Success 按钮: 轮廓式成功色设计，成功色边框和文字，5%透明度成功色背景
Warning 按钮: 轮廓式警告色设计，警告色边框和文字，5%透明度警告色背景
Danger 按钮: 轮廓式危险色设计，危险色边框和文字，5%透明度危险色背景
Info 按钮: 轮廓式信息色设计，信息色边框和文字，5%透明度信息色背景
Default 按钮: 白色背景，灰色边框，灰色文字

交互效果

悬浮状态: 上移 1px + 背景透明度变为 10% + 边框透明度变为 80% + 彩色阴影
点击状态: 98%缩放 + 0.1s 快速过渡 + 背景透明度变为 15%
禁用状态: 50%透明度，禁用所有交互和变换

3. 组件开发规范

Vue 组件结构标准

<template>
    <div class="component-container">
        <!-- 组件内容 -->
    </div>
</template>

<script setup lang="ts" name="ComponentName">
// 1. 引入依赖
import { ref, reactive, computed, onMounted } from 'vue';
import type { ComponentProps, ComponentEmits } from './types';

// 2. 定义Props和Emits
const props = defineProps<ComponentProps>();
const emits = defineEmits<ComponentEmits>();

// 3. 响应式数据
const loading = ref(false);
const formData = reactive({});

// 4. 计算属性
const computedValue = computed(() => {
    return /* 计算逻辑 */;
});

// 5. 方法定义
const handleClick = () => {
    // 方法实现
};

// 6. 生命周期
onMounted(() => {
    // 组件挂载后的逻辑
});
</script>

<style lang="scss" scoped>
.component-container {
    // 样式实现
}
</style>

页面开发规范

列表页面标准模板

<template>
    <div class="p-2 page-container">
        <!-- 搜索区域 -->
        <transition
            :enter-active-class="proxy?.animate.searchAnimate.enter"
            :leave-active-class="proxy?.animate.searchAnimate.leave"
        >
            <div v-show="showSearch" class="mb-[10px]">
                <el-card shadow="hover">
                    <el-form
                        ref="queryFormRef"
                        :model="queryParams"
                        :inline="true"
                        label-width="100px"
                    >
                        <!-- 搜索表单项 -->
                        <el-form-item>
                            <el-button type="primary" icon="Search" @click="handleQuery">
                                搜索
                            </el-button>
                            <el-button icon="Refresh" @click="resetQuery">重置</el-button>
                        </el-form-item>
                    </el-form>
                </el-card>
            </div>
        </transition>

        <!-- 表格区域 -->
        <el-card shadow="never" class="button-card table-card">
            <template #header>
                <el-row :gutter="10" class="mb8">
                    <el-col :span="1.5">
                        <el-button type="primary" plain icon="Plus" @click="handleAdd">
                            新增
                        </el-button>
                    </el-col>
                    <right-toolbar
                        v-model:showSearch="showSearch"
                        @queryTable="getList"
                    ></right-toolbar>
                </el-row>
            </template>

            <!-- 数据表格 -->
            <el-table v-loading="loading" border :data="dataList" :height="tableHeight">
                <el-table-column type="selection" width="55" align="center" />
                <!-- 数据列 -->
                <el-table-column label="操作" align="center" width="160">
                    <template #default="scope">
                        <!-- 操作按钮 -->
                    </template>
                </el-table-column>
            </el-table>

            <!-- 分页组件 -->
            <pagination
                v-show="total > 0"
                :total="total"
                v-model:page="queryParams.pageNum"
                v-model:limit="queryParams.pageSize"
                @pagination="getList"
            />
        </el-card>
    </div>
</template>

表单页面标准模板

<template>
    <div class="app-container">
        <el-form ref="formRef" :model="form" :rules="rules" label-width="120px">
            <el-card shadow="never">
                <template #header>
                    <span>基本信息</span>
                </template>

                <el-row :gutter="20">
                    <el-col :span="12">
                        <el-form-item label="名称" prop="name">
                            <el-input v-model="form.name" placeholder="请输入名称" />
                        </el-form-item>
                    </el-col>
                    <el-col :span="12">
                        <el-form-item label="状态" prop="status">
                            <el-select v-model="form.status" placeholder="请选择状态">
                                <el-option label="启用" value="0" />
                                <el-option label="禁用" value="1" />
                            </el-select>
                        </el-form-item>
                    </el-col>
                </el-row>

                <el-form-item>
                    <el-button type="primary" @click="submitForm">提交</el-button>
                    <el-button @click="resetForm">重置</el-button>
                </el-form-item>
            </el-card>
        </el-form>
    </div>
</template>

<script setup lang="ts">
import { ref, reactive } from 'vue';
import type { FormInstance, FormRules } from 'element-plus';

// 表单引用
const formRef = ref<FormInstance>();

// 表单数据
const form = reactive({
    name: '',
    status: '0',
});

// 验证规则
const rules = reactive<FormRules>({
    name: [{ required: true, message: '请输入名称', trigger: 'blur' }],
    status: [{ required: true, message: '请选择状态', trigger: 'change' }],
});

// 提交表单
const submitForm = async () => {
    if (!formRef.value) return;
    await formRef.value.validate((valid) => {
        if (valid) {
            // 提交逻辑
            console.log('提交表单:', form);
        }
    });
};

// 重置表单
const resetForm = () => {
    if (!formRef.value) return;
    formRef.value.resetFields();
};
</script>

4. API 开发规范

API 接口定义标准

// api/[module]/index.ts
import request from '@/utils/request';
import type { AxiosPromise } from 'axios';
import type { DataVO, DataForm, DataQuery } from './types';

/**
 * 查询数据列表
 * @param query 查询参数
 */
export const listData = (query?: DataQuery): AxiosPromise<DataVO[]> => {
    return request({
        url: '/api/data/list',
        method: 'get',
        params: query,
    });
};

/**
 * 查询数据详情
 * @param id 数据ID
 */
export const getData = (id: string | number): AxiosPromise<DataVO> => {
    return request({
        url: `/api/data/${id}`,
        method: 'get',
    });
};

/**
 * 新增数据
 * @param data 数据信息
 */
export const addData = (data: DataForm): AxiosPromise<void> => {
    return request({
        url: '/api/data',
        method: 'post',
        data: data,
    });
};

/**
 * 修改数据
 * @param data 数据信息
 */
export const updateData = (data: DataForm): AxiosPromise<void> => {
    return request({
        url: '/api/data',
        method: 'put',
        data: data,
    });
};

/**
 * 删除数据
 * @param ids 数据ID数组
 */
export const delData = (ids: Array<string | number>): AxiosPromise<void> => {
    return request({
        url: `/api/data/${ids}`,
        method: 'delete',
    });
};

TypeScript 类型定义

// api/[module]/types.ts

// 查询参数
export interface DataQuery extends PageQuery {
    name?: string;
    status?: string;
    createTime?: [DateModelType, DateModelType];
}

// 数据表单
export interface DataForm {
    id?: string | number;
    name: string;
    status: string;
    remark?: string;
}

// 数据视图对象
export interface DataVO {
    id: string | number;
    name: string;
    status: string;
    createTime: string;
    updateTime: string;
    remark?: string;
}

5. 状态管理规范

Pinia Store 结构

// stores/modules/[module].ts
import { defineStore } from 'pinia';
import { ref, computed } from 'vue';
import type { DataVO, DataQuery } from '@/api/[module]/types';
import { listData, getData } from '@/api/[module]';

export const useDataStore = defineStore('[module]', () => {
    // 状态
    const dataList = ref<DataVO[]>([]);
    const loading = ref(false);
    const total = ref(0);

    // 计算属性
    const hasData = computed(() => dataList.value.length > 0);

    // 方法
    const getList = async (query: DataQuery) => {
        loading.value = true;
        try {
            const { data } = await listData(query);
            dataList.value = data.rows;
            total.value = data.total;
        } finally {
            loading.value = false;
        }
    };

    const getInfo = async (id: string | number) => {
        const { data } = await getData(id);
        return data;
    };

    const reset = () => {
        dataList.value = [];
        total.value = 0;
    };

    return {
        // 状态
        dataList,
        loading,
        total,
        // 计算属性
        hasData,
        // 方法
        getList,
        getInfo,
        reset,
    };
});

6. 路由管理规范

路由定义标准

// router/modules/[module].ts
import type { RouteRecordRaw } from 'vue-router';
import Layout from '@/layout/index.vue';

const moduleRouter: RouteRecordRaw = {
    path: '/[module]',
    component: Layout,
    redirect: '/[module]/list',
    name: 'Module',
    meta: {
        title: '模块管理',
        icon: 'example',
        alwaysShow: true,
    },
    children: [
        {
            path: 'list',
            component: () => import('@/views/[module]/index.vue'),
            name: 'ModuleList',
            meta: {
                title: '列表管理',
                activeMenu: '/[module]/list',
            },
        },
        {
            path: 'add',
            component: () => import('@/views/[module]/form.vue'),
            name: 'ModuleAdd',
            meta: {
                title: '新增数据',
                activeMenu: '/[module]/list',
            },
            hidden: true,
        },
        {
            path: 'edit/:id(\\d+)',
            component: () => import('@/views/[module]/form.vue'),
            name: 'ModuleEdit',
            meta: {
                title: '编辑数据',
                activeMenu: '/[module]/list',
            },
            hidden: true,
        },
    ],
};

export default moduleRouter;

7. 项目架构规范

目录结构标准

web/src/
├── api/                    # API接口定义
│   ├── [module]/          # 按模块分类
│   │   ├── index.ts       # API接口
│   │   └── types.ts       # 类型定义
│   └── types.ts           # 通用类型定义
├── assets/                 # 静态资源
│   ├── icons/             # SVG图标
│   ├── images/            # 图片资源
│   └── styles/            # 全局样式
├── components/             # 通用组件
│   ├── [ComponentName]/   # 组件目录
│   │   ├── index.vue      # 组件主文件
│   │   └── types.ts       # 组件类型
│   └── index.ts           # 组件导出
├── composables/           # 组合式函数
├── directive/             # 自定义指令
├── hooks/                 # 自定义钩子
├── layout/               # 布局组件
├── plugins/              # 插件配置
├── router/               # 路由配置
│   ├── modules/          # 路由模块
│   └── index.ts          # 路由入口
├── stores/               # 状态管理
│   ├── modules/          # Store模块
│   └── index.ts          # Store入口
├── types/                # 全局类型定义
├── utils/                # 工具函数
│   ├── request.ts        # HTTP请求封装
│   ├── auth.ts           # 认证工具
│   └── index.ts          # 工具导出
├── views/                # 页面视图
│   ├── [module]/         # 按模块分类
│   │   ├── index.vue     # 列表页面
│   │   ├── form.vue      # 表单页面
│   │   └── components/   # 页面组件
│   └── layout/           # 布局页面
├── App.vue               # 应用入口
└── main.ts               # 主入口文件

8. 代码规范

命名规范

文件命名: 使用 kebab-case (如: user-list.vue)
组件命名: 使用 PascalCase (如: UserList)
方法命名: 使用 camelCase (如: getUserList)
常量命名: 使用 UPPER_SNAKE_CASE (如: API_BASE_URL)
CSS 类名: 使用 kebab-case (如: .user-list-container)

ESLint 配置

// .eslintrc.js
module.exports = {
    extends: ['@vue/eslint-config-typescript', '@vue/eslint-config-prettier'],
    rules: {
        // Vue规则
        'vue/multi-word-component-names': 'off',
        'vue/no-v-html': 'off',

        // TypeScript规则
        '@typescript-eslint/no-unused-vars': 'error',
        '@typescript-eslint/no-explicit-any': 'warn',

        // 通用规则
        'no-console': 'warn',
        'no-debugger': 'error',
    },
};

Prettier 配置

{
    "semi": true,
    "singleQuote": true,
    "trailingComma": "none",
    "tabWidth": 2,
    "useTabs": false,
    "printWidth": 100,
    "endOfLine": "lf"
}

9. 性能优化

代码分割

// 路由懒加载
const Home = () => import('@/views/home/index.vue');

// 组件懒加载
const LazyComponent = defineAsyncComponent(() => import('@/components/LazyComponent.vue'));

缓存策略

// HTTP缓存
import { ElMessage } from 'element-plus';

const request = axios.create({
  timeout: 10000,
  headers: {
    'Cache-Control': 'no-cache'
  }
});

// 组件缓存
<router-view v-slot="{ Component }">
  <keep-alive :include="cachedViews">
    <component :is="Component" :key="route.path" />
  </keep-alive>
</router-view>

10. 错误处理

全局错误处理

// main.ts
app.config.errorHandler = (err, vm, info) => {
    console.error('全局错误:', err);
    ElMessage.error('系统异常，请联系管理员');
};

// 请求错误处理
request.interceptors.response.use(
    (response) => {
        const { code, msg } = response.data;
        if (code === 200) {
            return response.data;
        } else {
            ElMessage.error(msg || '请求失败');
            return Promise.reject(new Error(msg));
        }
    },
    (error) => {
        ElMessage.error('网络异常');
        return Promise.reject(error);
    },
);

11. 测试规范

单元测试

// tests/components/UserList.spec.ts
import { mount } from '@vue/test-utils';
import UserList from '@/components/UserList/index.vue';

describe('UserList', () => {
    it('should render correctly', () => {
        const wrapper = mount(UserList, {
            props: {
                users: [],
            },
        });
        expect(wrapper.exists()).toBe(true);
    });
});

E2E 测试

// e2e/user.spec.ts
import { test, expect } from '@playwright/test';

test('用户列表页面', async ({ page }) => {
    await page.goto('/user/list');
    await expect(page.locator('.user-list')).toBeVisible();
});

主题色规范

1. 基础主题色值

Light 主题

// 主色调
--art-primary: 50, 50, 222; // 深蓝色，用于主要按钮、链接等
--art-secondary: 73, 190, 255; // 次要蓝色
--art-success: 0, 167, 58; // 成功色
--art-warning: 142, 91, 0; // 警告色
--art-danger: 255, 77, 79; // 危险色
--art-info: 0, 75, 178; // 信息色
--art-error: 250, 137, 107; // 错误色

// 文本颜色
--art-text-gray-600: #333333; // 主要文本
--art-text-gray-700: #000000; // 强调文本

Dark 主题

// 主色调
--art-primary: 93, 135, 255; // 亮蓝色
--art-bg-color: #070707; // 背景色
--art-main-bg-color: #161618; // 主要背景色

2. 使用规范

变量使用方式

// 正确用法
color: rgb(var(--art-primary));
background-color: rgb(var(--art-bg-primary));

// 错误用法
color: var(--art-primary); // ❌ 缺少rgb()

Element Plus 组件主题

// 全局变量
--el-color-primary: rgb(var(--art-primary)) !important;
--el-text-color-regular: #000000 !important;

菜单组件样式

--el-menu-hover-bg-color: rgb(var(--art-primary)) !important;
--el-menu-active-color: rgb(var(--art-primary)) !important;

3. 主题切换

Light/Dark 主题切换

通过添加/移除 html.dark 类实现
自动继承对应主题的所有变量

响应式设计
所有颜色必须使用 CSS 变量
禁止使用硬编码的颜色值

4. 辅助工具类

// 背景色
.bg-primary {
background-color: rgb(var(--art-bg-primary)) !important;
}
.bg-success {
background-color: rgb(var(--art-bg-success)) !important;
}
.bg-warning {
background-color: rgb(var(--art-bg-warning)) !important;
}
.bg-danger {
background-color: rgb(var(--art-bg-danger)) !important;
}

// 文本颜色
.text-primary {
color: rgb(var(--art-primary)) !important;
}
.text-success {
color: rgb(var(--art-success)) !important;
}
.text-warning {
color: rgb(var(--art-warning)) !important;
}
.text-danger {
color: rgb(var(--art-danger)) !important;
}

5. 注意事项

所有新增组件必须使用主题变量系统
禁止使用硬编码的颜色值
确保 Light/Dark 主题下都有良好的显示效果
Element Plus 组件的主题配置必须通过全局变量覆盖

cursorrules-frontend.md 20 KB 文件历史 原始文件

Cursor Rules - Web 前端开发规范

适用范围

Web 前端开发规范 (web/)

1. 技术栈规范

核心技术

环境要求

2. Art Design Pro UI 规范

设计理念

颜色系统

主色调 (Primary Colors)

背景色系统

轮廓式按钮设计系统

🎨 设计理念

核心规范

交互效果

3. 组件开发规范

Vue 组件结构标准

页面开发规范

列表页面标准模板

表单页面标准模板

4. API 开发规范

API 接口定义标准

TypeScript 类型定义

5. 状态管理规范

Pinia Store 结构

6. 路由管理规范

路由定义标准

7. 项目架构规范

目录结构标准

8. 代码规范

命名规范

ESLint 配置

Prettier 配置

9. 性能优化

代码分割

缓存策略

10. 错误处理

全局错误处理

11. 测试规范

单元测试

E2E 测试

主题色规范

1. 基础主题色值

Light 主题

Dark 主题

2. 使用规范

3. 主题切换

4. 辅助工具类

5. 注意事项

cursorrules-frontend.md 20 KB

文件历史原始文件