vue-best-practices

Vue 最佳实践工作流

将此技能用作一组指令。除非用户明确要求采用不同顺序，否则请按顺序遵循此工作流。

核心原则

• **保持状态可预测：**只有一个真实数据源，其他内容均由此派生。
• **明确数据流：**大多数情况下，Props 向下传递，Events 向上传递。
• **优先使用小型、专注的组件：**更易于测试、复用和维护。
• **避免不必要的重新渲染：**合理使用计算属性和侦听器。
• **重视可读性：**编写清晰、易于理解的代码。

1) 编码前确认架构（必需）

• 默认技术栈：Vue 3 + Composition API + <script setup lang="ts">。
• 如果项目明确使用 Options API，且 vue-options-api-best-practices 技能可用，请加载该技能。
• 如果项目明确使用 JSX，且 vue-jsx-best-practices 技能可用，请加载该技能。

1.1 必须阅读的核心参考资料（必需）

• 实施任何 Vue 任务前，请务必阅读并应用以下核心参考资料：
  • references/reactivity.md
  • references/sfc.md
  • references/component-data-flow.md
  • references/composables.md
• 在整个任务期间，将这些参考资料保留在当前工作上下文中，而不仅仅是在出现特定问题时才参考。

1.2 编码前规划组件边界（必需）

对于任何非简单功能，实施前都要创建简要的组件关系图。

• 用一句话定义每个组件的单一职责。
• 默认将入口／根组件和路由级视图组件作为组合界面。
• 除非任务特意要求制作一个非常小的单文件演示，否则应将功能 UI 和功能逻辑从入口／根组件／视图组件中移出。
• 在关系图中定义每个子组件的 Props／emits 契约。
• 添加多个组件时，优先采用功能目录布局（components/<feature>/...、composables/use<Feature>.ts）。

2) 应用 Vue 基础要点（必需）

这些是必不可少、必须掌握的基础知识。使用第 1.1 节中已加载的核心参考资料，在每个 Vue 任务中应用以下所有要点。

响应性

• 必须阅读第 1.1 节中的参考资料：响应性
• 尽量精简源状态（ref／reactive），尽可能使用 computed 派生所有内容。
• 如有需要，使用侦听器处理副作用。
• 避免在模板中重复计算开销较大的逻辑。

SFC 结构和模板安全

• 必须阅读第 1.1 节中的参考资料：SFC
• SFC 各部分按以下顺序排列：<script> → <template> → <style>。
• 让 SFC 职责保持专注；拆分大型组件。
• 保持模板声明式；将分支判断／派生逻辑移到脚本中。
• 遵循 Vue 模板安全规则（v-html、列表渲染、条件渲染选项）。

保持组件职责聚焦

当组件承担多个明确职责时（例如，数据编排 + UI，或多个相互独立的 UI 区块），应将其拆分。

• 优先使用较小的组件 + 组合式函数，而非一个“巨型组件”
• 将 UI 区块移到子组件中（传入 props，向外触发事件）。
• 将状态/副作用移到组合式函数中（useXxx()）。

根据客观的拆分条件进行判断。满足任意一项时，就拆分组件：

• 它既管理编排/状态，又包含多个区块的大量展示标记。
• 它包含 3 个或更多不同的 UI 区块（例如：表单、筛选器、列表、页脚/状态）。
• 模板区块重复出现，或可以复用（项目行、卡片、列表条目）。

入口/根组件和路由视图规则：

• 入口/根组件和路由视图组件应保持精简：应用外壳/布局、提供器接线和功能组合。
• 当某项功能包含相互独立的部分时，不要将完整的功能实现放在入口/根组件或视图组件中。
• 对于 CRUD/列表功能（待办事项、表格、目录、收件箱），至少拆分为：
  • 功能容器组件
  • 输入/表单组件
  • 列表（和/或项目）组件
  • 页脚/操作或筛选/状态组件
• 仅对非常小的一次性演示允许采用单文件实现；如果选择这种方式，必须明确说明为何无需拆分。

组件数据流

• 必须阅读 1.1 中的参考文档：component-data-flow
• 主要采用 props 向下传递、事件向上触发的模式。
• 仅在组件契约确实需要双向绑定时使用 v-model。
• 仅在深层树依赖或共享上下文中使用 provide/inject。
• 根据需要使用 defineProps、defineEmits 和 InjectionKey，保持契约明确且类型化。

组合式函数

• 必须阅读 1.1 中的参考文档：composables
• 当逻辑需要复用、有状态或副作用较多时，将其提取到组合式函数中。
• 保持组合式函数 API 精简、类型明确且行为可预测。
• 将功能逻辑与展示组件分离。

3) 仅在需求要求时考虑可选功能

3.1 标准可选功能

不要默认添加这些功能。仅在存在相应需求时，才加载匹配的参考文档。

• 插槽：父组件需要控制子组件的内容/布局 -> component-slots
• 属性透传：包装器/基础组件必须安全地转发 attrs/events -> component-fallthrough-attrs
• 内置组件 <KeepAlive>，用于有状态的视图缓存 -> component-keep-alive
• 内置组件 <Teleport>，用于覆盖层/传送门 -> component-teleport
• 内置组件 <Suspense>，用于异步子树的回退边界 -> component-suspense
• 动画相关功能：选择与所需动态效果相符的最简单方案。
  • 内置组件 <Transition>，用于进入/离开效果 -> transition
  • 内置组件 <TransitionGroup>，用于列表变更动画 -> transition-group
  • 基于类的动画，用于非进入/离开效果 -> animation-class-based-technique
  • 状态驱动的动画，用于由用户输入驱动的动画 -> animation-state-driven-technique

3.2 不太常见的可选功能

仅在有明确的产品或技术需求时使用。

• 指令：行为特定于 DOM，且不适合组合式 API/组件 -> 指令
• 异步组件：应对体积较大或很少使用的 UI 进行延迟加载 -> 异步组件
• 仅在模板无法表达需求时使用渲染函数 -> 渲染函数
• 当行为必须在整个应用中安装时使用插件 -> 插件
• 状态管理模式：应用范围内的共享状态跨越功能边界 -> 状态管理

4）在行为正确后进行性能优化

性能优化应在功能实现后进行。核心行为实现并验证之前，不要进行优化。

• 大型列表渲染瓶颈 -> 大型列表虚拟化
• 静态子树不必要地重新渲染 -> v-once 与 v-memo 指令的性能优化
• 热门列表路径中过度抽象 -> 避免在列表中进行组件抽象
• 过于频繁地触发开销较大的更新 -> updated 钩子的性能优化

5）完成前的最终自检

• 核心行为正常，并符合要求。
• 已阅读并应用所有必读参考资料。
• 响应式模型精简且可预测。
• 遵循 SFC 结构和模板规则。
• 组件职责明确、划分合理，并在必要时拆分。
• 入口/根组件和路由视图组件仍作为组合层，除非明确属于小型演示的例外情况。
• 组件拆分决策明确且有理有据（职责边界清晰）。
• 数据流契约明确且有类型定义。
• 在复用或复杂度足以构成理由时使用组合式函数。
• 如适用，将状态/副作用移至组合式函数中
• 仅在需求要求时使用可选功能。
• 仅在功能完整后应用性能优化。