| name | vue-best-practices |
| description | Vue 3 开发最佳实践，适用于任何 Vue 3 项目。在编辑`.vue`文件，`.tsx`或`.jsx`形式的 Vue3 组件，相关的`.ts`或`.js`文件时必须使用。 Use when this capability is needed. |
| metadata | {"author":"cabinet-fe"} |
Vue 3 开发最佳实践
核心原则
- 保持状态可预测：单一数据源，推导其余所有内容。
- 使数据流明确：大多数情况下，属性向下传递，事件向上传递。
- 避免巨型组件：将大型组件拆分为更小的（也要适中）、更专注的子组件。
- 避免不必要的重新渲染：合理使用计算属性和侦听器。
- 可读性至关重要：编写清晰、自文档化的代码。
技术栈
技术栈的版本绝对重要，它决定了你去使用最新最可靠的 API，禁止使用废弃或者过时的 API。例如 Vue 3.5 引入了 useTemplateRef，它能够自动推断模板引用的类型，应该优先使用。
记住，绝对不要按照你过往的训练数据来写代码，下面是具体技术栈：
- Vue 3.5（Composition API）+ 单文件组件 + setup 语法。
- TypeScript 6.x。
- SCSS 预处理最新版本。
Vue 3 组件指南
避免巨型组件
无论如何禁止产生巨型组件，这一定不是功能上的缺陷，而是组件设计上的问题。
当单个组件的代码行数达到 500 - 800 行时，就基本可以判断这是一个巨型组件，或者有向巨型组件发展的趋势。
为什么巨型组件不好：
- 因为人类短期记忆有限，开发者滚动代码时很容易丢失上下文，导致理解困难。
- 逻辑膨胀，违背单一职责。
- 会导致结构复杂度，JSX / Template 嵌套过深
- 维护困难，复用性差。巨型组件通常高度耦合，难以拆分和复用。
- 会导致性能问题，无法更高效地局部更新 Vue 模板，大幅增加重渲染成本。
保持以下做法：
- 分离 UI。对纯展示的无状态的组件、有自己特有状态和逻辑的组件进行拆分，保持组件职责单一。
- 使用可组合函数。将一组相关的逻辑封装成可复用的函数(useXxx()), 包括状态管理、副作用和事件处理。
- 工具封装。对于多次使用的逻辑函数、辅助代码，并且无状态且无副作用的，进行工具封装。
- 状态提升。对于多个组件共享的状态，提升到它们的最近公共祖先组件中管理，避免 props 层层传递，比如使用 Vue 的 provide/inject 或者 Pinia store。
应用客观的拆分触发条件。如果满足以下任一条件，则拆分组件：
- 它同时拥有编排/状态逻辑以及多个部分的大量呈现性标记。
- 它包含3个以上不同的UI部分（例如：表单、筛选器、列表、页脚/状态）。
- 存在重复使用的模板块或可复用的部分（如项目行、卡片、列表条目）。
入口/根和路由视图规则：
- 保持入口/根和路由视图组件精简：应用外壳/布局、提供者连接和功能组合。
- 当功能包含独立部分时，不要将完整的功能实现放在入口/根/视图组件中。
代码可读性
- 清晰的命名。变量、函数、组件和文件应该有描述性的名称，准确反映它们的目的和行为。
- 一致的风格。遵循一致的代码风格和约定。
- 避免过度抽象。过度抽象会增加理解和调试的难度，保持代码简单直接。
- 使用注释。在复杂的逻辑或不直观的部分添加注释，但避免过度注释，代码应该尽可能自解释。
保证性能
- 使用异步组件。对重量级的、不常用的、按需使用的组件使用异步组件来懒加载。
- 避免频繁渲染整个模板。 禁止高频触发的事件、动画、定时器导致整个模板重新渲染的情况，比如使用鼠标拖拽滑块时只想更新滑块的 UI 状态，却导致整个页面重新渲染，哪怕看起来页面其它部分没有变化，Vue 也会重新执行整个模板的渲染函数，导致性能问题。
- 对列表渲染绑定key。
- 减少响应式系统开销。
- 避免什么变量都定义成响应式对象，要根据实际业务需求来判断。
- 对于不需要响应式的属性，使用
shallowRef 或 shallowReactive。
- 防止内存泄露。
- 在组件销毁时清理定时器、事件监听器和其他副作用。
- 使用
onUnmounted、onBeforeUnmount、onScopeDispose等生命周期钩子来执行清理逻辑。
Source: cabinet-fe/ultra-ui — distributed by TomeVault.
