前端开发模式

本技能提供前端开发的最佳实践和模式，支持多框架按需加载。

快速参考

核心职责: 提供前端开发最佳实践——组件设计、状态管理、性能优化、无障碍开发
框架支持: Vue 3 / React 18 / Svelte / Angular 17+（根据 package.json 按需加载）
性能目标: LCP < 2.5s, FID < 100ms, CLS < 0.1, TTI < 3.8s
设计原则: 单一职责、Props 向下、Events 向上、组合优于继承
子文件引用:
- vue.md / react.md / svelte.md / angular.md — 框架专属模式
- performance.md — Core Web Vitals 优化
- tailwind.md — Tailwind 最佳实践 + v4 迁移
- design-guide.md — 设计方法论与审查清单

触发条件

创建或修改前端组件
设计 UI/UX 交互
实现状态管理
性能优化
无障碍开发

框架专属模式

根据项目技术栈，加载对应的框架专属文件：

技术栈	加载文件	框架
Vue	`vue.md`	Vue 3, Nuxt 3
React	`react.md`	React 18, Next.js
Svelte	`svelte.md`	Svelte, SvelteKit
Angular	`angular.md`	Angular 17+

加载方式: 检测项目中的 package.json 依赖确定技术栈。

通用组件模式

组件分类

┌─────────────────────────────────────────────────────┐
│                    组件金字塔                         │
├─────────────────────────────────────────────────────┤
│  页面组件 (Pages/Views)                              │
│  ├─ 负责路由和布局                                   │
│  ├─ 组合多个功能组件                                 │
│  └─ 管理页面级状态                                   │
├─────────────────────────────────────────────────────┤
│  功能组件 (Features/Containers)                      │
│  ├─ 包含业务逻辑                                     │
│  ├─ 连接状态管理                                     │
│  └─ 调用 API                                        │
├─────────────────────────────────────────────────────┤
│  UI 组件 (UI/Presentational)                        │
│  ├─ 纯展示，无业务逻辑                               │
│  ├─ 通过 props 接收数据                              │
│  └─ 通过 events 通知父组件                           │
├─────────────────────────────────────────────────────┤
│  基础组件 (Base/Primitives)                         │
│  ├─ Button, Input, Card 等                          │
│  ├─ 高度可复用                                       │
│  └─ 设计系统基础                                     │
└─────────────────────────────────────────────────────┘

组件设计原则

原则	说明
单一职责	一个组件只做一件事
Props 向下	数据从父组件流向子组件
Events 向上	事件从子组件通知父组件
组合优于继承	使用 slot/children 组合组件
可预测	相同 props 产生相同输出

命名规范

components/
├── ui/                    # 基础组件（PascalCase）
│   ├── Button.vue/tsx
│   ├── Input.vue/tsx
│   └── Card.vue/tsx
├── feature/               # 功能组件（PascalCase）
│   ├── UserCard.vue/tsx
│   └── OrderList.vue/tsx
└── layout/                # 布局组件（PascalCase）
    ├── Header.vue/tsx
    └── Sidebar.vue/tsx

状态管理模式

状态分层

层级	范围	存储方式	示例
组件状态	单个组件	useState/ref	表单输入、UI 状态
共享状态	多个组件	Context/Store	用户信息、主题
服务器状态	来自 API	Query Cache	列表数据、详情
URL 状态	路由参数	Router	页码、筛选条件
持久状态	跨会话	localStorage	用户偏好

状态管理选择

简单共享状态 → Context/Provide
  ↓ 复杂度增加
中等应用 → Pinia/Zustand
  ↓ 复杂度增加
大型应用 → Redux/Vuex + 规范化

服务器状态管理

API 请求 → Query Library（TanStack Query）
  ├─ 自动缓存
  ├─ 重新验证
  ├─ 乐观更新
  └─ 错误重试

性能优化模式

渲染优化

技术	用途	框架实现
Memoization	避免重复计算	useMemo/computed
Lazy Loading	延迟加载组件	lazy/defineAsyncComponent
Virtual List	大列表渲染	react-window/vue-virtual-scroller
Code Splitting	按需加载代码	动态 import

资源优化

图片优化:
├─ 响应式图片（srcset）
├─ 懒加载（loading="lazy"）
├─ 现代格式（WebP/AVIF）
└─ 图片 CDN

脚本优化:
├─ Tree Shaking
├─ Bundle 分析
├─ 预加载关键资源
└─ 延迟非关键脚本

性能指标

指标	目标	说明
LCP	< 2.5s	最大内容绘制
FID	< 100ms	首次输入延迟
CLS	< 0.1	累积布局偏移
TTI	< 3.8s	可交互时间

无障碍模式 (a11y)

基础清单

语义化 HTML - 使用正确的元素（button, nav, main...）
键盘可访问 - 所有交互可用键盘完成
焦点管理 - 焦点顺序合理，焦点可见
ARIA 标签 - 为动态内容添加适当标签
颜色对比 - 符合 WCAG 2.1 AA 标准（4.5:1）
替代文本 - 图片有 alt，图标有 aria-label

常见 ARIA 模式

<!-- 按钮 -->
<button aria-label="关闭菜单" aria-expanded="false">
  <Icon name="close" aria-hidden="true" />
</button>

<!-- 表单 -->
<input
  aria-labelledby="label-id"
  aria-describedby="hint-id error-id"
  aria-invalid="true"
/>

<!-- 动态内容 -->
<div aria-live="polite" aria-busy="false">加载完成</div>

<!-- 对话框 -->
<div role="dialog" aria-modal="true" aria-labelledby="dialog-title">
  <h2 id="dialog-title">对话框标题</h2>
</div>

键盘交互

元素	按键	行为
按钮	Enter/Space	激活
链接	Enter	导航
菜单	↑↓	移动焦点
对话框	Esc	关闭
Tab列表	←→	切换标签

表单模式

表单验证

客户端验证:
├─ 实时验证（onChange）
├─ 提交验证（onSubmit）
├─ 字段级错误
└─ 表单级错误

验证库:
├─ React: react-hook-form + zod
├─ Vue: vee-validate + zod
└─ 通用: yup/zod

表单状态

{
  values: {},        // 字段值
  errors: {},        // 验证错误
  touched: {},       // 字段已交互
  isSubmitting: false,
  isValid: true
}

错误处理

<!-- 字段错误 -->
<div class="field">
  <label for="email">邮箱</label>
  <input id="email" aria-invalid="true" aria-describedby="email-error" />
  <span id="email-error" role="alert" class="error">
    请输入有效的邮箱地址
  </span>
</div>

<!-- 表单级错误 -->
<div role="alert" class="form-error">提交失败：网络错误，请重试</div>

动画模式

动画类型

类型	用途	实现
进入/退出	元素出现/消失	CSS Transition
状态变化	hover/active	CSS Transition
列表动画	添加/删除/排序	FLIP 动画
页面切换	路由过渡	路由动画
复杂动画	多阶段动画	Framer Motion/GSAP

动画原则

有意义 - 动画应该传达信息
快速 - 持续时间 150-300ms
可禁用 - 尊重 prefers-reduced-motion
不阻塞 - 不影响用户操作

减少动画

@media (prefers-reduced-motion: reduce) {
  *,
  *::before,
  *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
  }
}

设计美学（避免 AI Slop）

详见 design-guide.md — AI 通用审美定义、设计思维方向矩阵、反模式清单与审查清单。

测试模式

前端测试策略详见 rules/frontend/frontend-testing.md 和 rules/frontend/frontend-e2e.md（按文件类型自动加载）。

框架专属内容

详细的框架专属实现请参考：

Vue: vue.md - Vue 3 + Composition API
React: react.md - React 18 + Hooks
Svelte: svelte.md - Svelte/SvelteKit
Angular: angular.md - Angular 17+

专项优化

性能优化: performance.md - Core Web Vitals (LCP/INP/CLS)
Tailwind CSS: tailwind.md - Tailwind 最佳实践 + v4 迁移指南
设计指南: design-guide.md - Designer 角色设计方法论与审查清单

Maintenance

Sources: MDN, WCAG 2.1, web.dev, 各框架官方文档
Last updated: 2025-01-22
Pattern: 通用清单 + 按需加载框架专属

记住: 前端开发的核心是用户体验——性能、无障碍、交互细节缺一不可，独特的设计比通用模板更有价值。

frontend

前端开发模式

快速参考

目录

触发条件

框架专属模式

通用组件模式

组件分类

组件设计原则

命名规范

状态管理模式

状态分层

状态管理选择

服务器状态管理

性能优化模式

渲染优化

资源优化

性能指标

无障碍模式 (a11y)

基础清单

常见 ARIA 模式

键盘交互

表单模式

表单验证

表单状态

错误处理

动画模式

动画类型

动画原则

减少动画

设计美学（避免 AI Slop）

测试模式

框架专属内容

专项优化

Maintenance