vue3-frontend

Vue 3 前端开发技能

全面的 Vue 3 前端开发技能，提供组件模板、最佳实践指南、迁移协助和常见模式。

核心能力

1. 组件开发

使用 <script setup> 语法和 Composition API 创建新的 Vue 3 组件。

可用模板：

• assets/component-templates/BasicComponent.vue - 基本组件模板
• assets/component-templates/FormComponent.vue - 完整的表单组件（含验证）
• assets/component-templates/DataTable.vue - 数据表格组件（含排序、分页、搜索）
• assets/component-templates/Modal.vue - 模态框组件（含完整功能）

用法：

# 複製範本到專案
cp assets/component-templates/BasicComponent.vue src/components/YourComponent.vue

2. Composable 开发

创建可复用的逻辑抽象。

可用模板：

• assets/composable-templates/useFetch.js - API 请求封装
• assets/composable-templates/useLocalStorage.js - localStorage 同步状态

用法：

# 複製到專案
cp assets/composable-templates/useFetch.js src/composables/

3. 从 Vue 2 迁移到 Vue 3

协助将 Vue 2 项目迁移到 Vue 3。

迁移工作流：

1. 阅读 references/migration-guide.md，了解破坏性变更
2. 在现有代码中找出已弃用的 API
3. 应用指南中的迁移模式
4. 进行全面测试

主要迁移内容：

• 全局 API（Vue.use → app.use）
• 响应式系统（Vue.set → 直接赋值）
• v-model 语法（value/input → modelValue/update:modelValue）
• 生命周期钩子（destroyed → unmounted）
• 移除过滤器（改用 computed/methods）
• 替换事件总线（改用 mitt/Pinia）

4. 代码审查与优化

检查并优化 Vue 3 代码质量。

审查清单：

• 使用 <script setup> 以提升性能
• 正确使用 ref/reactive
• 区分 computed 与 methods
• 区分 v-show 与 v-if
• 在 v-for 中使用 key
• 拆分组件
• 验证 Props
• 错误处理

参考文档

核心参考资料

处理特定任务时，请务必阅读以下文档：

迁移任务：

• references/migration-guide.md - 完整的 Vue 2 到 Vue 3 迁移指南，涵盖所有破坏性变更

Composition API 用法：

• references/composition-api.md - 全面的 Composition API 参考（ref、reactive、computed、watch、生命周期等）

最佳实践：

• references/best-practices.md - Vue 3 最佳实践，涵盖组件设计、响应式、性能、代码组织、错误处理和 TypeScript

常见模式：

• references/common-patterns.md - 表单处理、数据获取、列表渲染、模态框、状态管理、路由和 i18n

何时阅读各参考资料

编写任何组件之前：

1. 查看 best-practices.md 中的组件设计模式
2. 查看 common-patterns.md 中的相关模式

迁移之前：

1. 通读 migration-guide.md
2. 参考 composition-api.md 中的新 API 语法

实现功能时：

• 表单 → common-patterns.md 的 Form Handling 部分
• 数据获取 → common-patterns.md 的 Data Fetching 部分
• 状态管理 → common-patterns.md 的 State Management 部分
• i18n → common-patterns.md 的 i18n 部分

常见开发工作流

工作流 1：创建新组件

# 1. Choose appropriate template
view assets/component-templates/

# 2. Read best practices
view references/best-practices.md

# 3. Copy and customize template
cp assets/component-templates/BasicComponent.vue src/components/MyComponent.vue

# 4. Follow naming conventions (PascalCase)
# 5. Define props with validation
# 6. Use <script setup> syntax
# 7. Keep component focused and small

工作流 2：将 Vue 2 代码迁移到 Vue 3

# 1. Read migration guide first
view references/migration-guide.md

# 2. Identify patterns to migrate
# - Options API → Composition API
# - this.$set → direct assignment
# - filters → computed/methods
# - Event Bus → mitt/Pinia

# 3. Apply changes systematically
# 4. Test each change
# 5. Update dependencies

工作流 3：实现数据获取

# 1. Review data fetching patterns
view references/common-patterns.md
# Look for "Data Fetching Patterns" section

# 2. Choose approach:
# - Custom composable (useFetch template)
# - VueUse (@vueuse/core)
# - TanStack Query

# 3. Implement with error handling and loading states

工作流 4：优化性能

# 1. Review performance section
view references/best-practices.md
# Look for "Performance Optimization" section

# 2. Check for issues:
# - Using methods instead of computed
# - Unnecessary v-if usage
# - Missing keys in v-for
# - Large components without splitting
# - No lazy loading

# 3. Apply optimizations:
# - Use computed for derived data
# - v-show for frequent toggles
# - defineAsyncComponent for heavy components
# - Virtual scrolling for large lists

工作流 5：表单开发

# 1. Use form template or VeeValidate pattern
view assets/component-templates/FormComponent.vue
view references/common-patterns.md
# Look for "Form Handling Patterns" section

# 2. Implement validation
# 3. Handle errors and loading states
# 4. Add success/error feedback

快速参考命令

组件模板

# List all templates
ls -la assets/component-templates/

# Copy specific template
cp assets/component-templates/[TemplateName].vue src/components/

Composable 模板

# List all composables
ls -la assets/composable-templates/

# Copy specific composable
cp assets/composable-templates/[composableName].js src/composables/

阅读文档

# Migration guide
view references/migration-guide.md

# Composition API reference
view references/composition-api.md

# Best practices
view references/best-practices.md

# Common patterns
view references/common-patterns.md

最佳实践摘要

组件设计

• 始终使用 <script setup>，以提升性能和开发体验
• 完整验证 Props
• 使用 composables 实现可复用逻辑
• 保持组件小巧且专注（< 200 行）
• 将复杂逻辑提取到 composables 中

响应式

• 对基本类型使用 ref()
• 对对象使用 reactive()
• 对派生数据使用 computed()
• 需要旧值时使用 watch()
• 使用 watchEffect() 自动追踪依赖

性能

• 模板计算使用 computed()，而非 methods
• 频繁切换时使用 v-show
• 初始渲染条件使用 v-if
• 在 v-for 中始终使用唯一的 key
• 使用 defineAsyncComponent() 延迟加载较重的组件
• 对大型列表使用虚拟滚动

代码组织

src/
├── assets/          # Static resources
├── components/      # Reusable components
│   ├── common/      # Base components
│   ├── layout/      # Layout components
│   └── features/    # Feature components
├── composables/     # Reusable logic
├── stores/          # Pinia stores
├── router/          # Router config
├── views/           # Page components
├── utils/           # Utility functions
└── services/        # API services

TypeScript 支持

使用 TypeScript 时：

• 使用接口定义 prop 类型
• 在组合式函数中使用泛型
• 正确声明 emits 的类型
• 必要时使用 defineComponent

详情请参阅 best-practices.md 中的 TypeScript 集成部分。

常见注意事项

1. 解构响应式对象会丢失响应性

   • 使用 toRefs() 或直接访问属性

2. 以 Vue 2 风格直接修改数组／对象

   • Vue 3 不需要 $set，可以直接修改

3. 忘记在 ref 中使用 .value

   • 请记住：在 <script> 中，ref 需要 .value；在 <template> 中则不需要

4. 对基本类型使用 reactive()

   • 基本类型使用 ref()，对象使用 reactive()

5. 未清理副作用

   • 始终在 onBeforeUnmount() 中清理，或使用 watchEffect() 的清理函数

其他资源

• Vue 3 官方文档：https://vuejs.org/
• Vue 3 迁移指南：https://v3-migration.vuejs.org/
• Composition API 常见问题：https://vuejs.org/guide/extras/composition-api-faq.html
• VueUse：https://vueuse.org/（实用组合式函数）
• Pinia：https://pinia.vuejs.org/（状态管理）

使用此技能的提示

1. 始终从参考资料开始：编码前阅读相关文档
2. 以模板为起点：如果已有模板，就不要从头编写
3. 遵循工作流：它们体现了最佳实践
4. 定期查看最佳实践：将这些模式内化
5. 遇到困难时：查看 common-patterns.md 中的类似示例