SuperAPI AI 工具集

vue-best-practices

编程与开发

查看项目

更新于 10-16 14:58

技能介绍

用途

vue-best-practices 是一个面向 Vue.js 任务的技能(skill),以“指令集 + 工作流”的形式提供。资料说明:凡是 Vue.js 任务都必须使用该技能。它强烈推荐将 Composition API 配合 <script setup> 与 TypeScript 作为标准做法,内容覆盖 Vue 3、SSR、Volar 等。使用时应把该技能当作一套指令按顺序遵循,除非用户明确要求不同的顺序。

核心原则

资料列出以下核心原则:

  • 保持状态可预测:单一数据来源,其余一切由此派生。
  • 让数据流显式化:多数情况下采用 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 编码前规划组件边界(必需)

对任何非平凡功能,在实现前创建简要的组件地图;用一句话定义每个组件的单一职责;默认让入口/根组件与路由级视图组件作为组合表面(composition surfaces);把功能 UI 与功能逻辑移出入口/根/视图组件,除非任务本身就是故意为之的极小单文件示例;在组件地图中为每个子组件定义 props/emits 契约;当新增多于一个组件时,优先采用功能文件夹布局(components/<feature>/...、composables/use<Feature>.ts)。

2) 应用 Vue 基础要点(必需)

以下为必需掌握的基础,每个 Vue 任务都应结合 1.1 的核心参考全部应用。

响应式:参考 reactivity.md;保持源状态最小(ref/reactive),尽可能用 computed 派生一切;如需副作用用侦听器;避免在模板中重复计算昂贵逻辑。

SFC 结构与模板安全:参考 sfc.md;SFC 各段顺序保持 <script> → <template> → <style>;保持 SFC 职责聚焦,拆分大组件;保持模板声明式,把分支/派生移到脚本;应用 Vue 模板安全规则(v-html、列表渲染、条件渲染选择)。

保持组件专注:当组件有一个以上清晰职责(如数据编排 + UI,或多个独立 UI 区域)时拆分;优先小而多的组件 + composables,而非一个“巨型组件”;把 UI 区块移入子组件(props 入、events 出);把状态/副作用移入 composables(useXxx())。资料给出客观拆分触发条件,满足任一即拆分:组件同时拥有编排/状态与多个区块的大量展示标记;具有 3+ 个不同 UI 区块(如表单、过滤器、列表、页脚/状态);某个模板块被重复或可能变为可复用(条目行、卡片、列表项)。

入口/根与路由视图规则:保持入口/根与路由视图组件轻量,仅包含应用外壳/布局、provider 接线与功能组合;当功能含独立部分时,不要把完整功能实现放进入口/根/视图组件。对于 CRUD/列表功能(待办、表格、目录、收件箱),至少拆分为:功能容器组件、输入/表单组件、列表(和/或条目)组件、页脚/操作或过滤/状态组件。允许单文件实现仅用于非常小的丢弃型演示;若选择如此,需明确说明为何无需拆分。

组件数据流:参考 component-data-flow.md;以 props 向下、events 向上为主要模型;仅对真正的双向组件契约使用 v-model;仅对深层树依赖或共享上下文使用 provide/inject;按需用 defineProps、defineEmits 与 InjectionKey 保持契约显式且类型化。

组合式函数(composables):参考 composables.md;当逻辑被复用、有状态或副作用较重时抽取为 composables;保持 composable API 小而类型化、可预测;将功能逻辑与展示组件分离。

3) 仅在需求需要时考虑可选特性

3.1 标准可选特性

默认不添加,仅在需求存在时加载对应参考:

  • 插槽(Slots):父级需控制子级内容/布局 → 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 特定相关且不适合 composable/组件时 → directives
  • 异步组件:重型/很少使用的 UI 应懒加载 → component-async
  • 渲染函数:仅当模板无法表达需求时 → render-functions
  • 插件:行为必须在应用级安装时 → plugins
  • 状态管理模式:应用级共享状态跨功能边界时 → state-management

4) 行为正确后再做性能优化

性能是功能完成后的收尾环节。不要在核心行为实现并验证之前优化。涉及的参考包括:大列表渲染瓶颈 → perf-virtualize-large-lists;静态子树不必要地重渲染 → perf-v-once-v-memo-directives;热列表路径中的过度抽象 → perf-avoid-component-abstraction-in-lists;昂贵更新触发过于频繁 → updated-hook-performance。

5) 完成前最终自检

检查项包括:核心行为可用且符合需求;所有必读参考已阅读并应用;响应式模型最小且可预测;遵循 SFC 结构与模板规则;组件专注且良好拆分,必要时拆分;入口/根与路由视图组件保持为组合表面,除非有明确的小型演示例外;组件拆分决策明确且可辩护(职责边界清晰);数据流契约显式且类型化;在复用/复杂度合理处使用了 composables;适用时把状态/副作用移入 composables;仅在需求要求时使用可选特性;性能改动仅在功能完成后应用。

适用场景与限制

适用场景:Vue.js 相关开发任务,特别是采用 Vue 3 + Composition API + <script setup> + TypeScript 的项目。资料提及覆盖 Vue 3、SSR、Volar,但未展开各部分的细节。

限制:资料未提供该技能的收费方式、价格、平台信息或具体效果数据;对于源站 www.skills.sh/cylixlee/cortex/vue-best-practices 的安装命令、仓库细节等内容暂未提供。分类方面,本技能面向 Vue.js 编程与开发实践,归入“编程与开发”。