2.9 KiB
2.9 KiB
description, globs, alwaysApply
| description | globs | alwaysApply | |
|---|---|---|---|
| TypeScript / Vue3 通用编码规范，适用于所有 .ts / .vue / .scss 文件 |
|
true |
编码规范
TypeScript
- 禁止
any。不确定类型用unknown后收窄，或定义显式类型；实在无法确定的第三方数据用Record<string, unknown>。 - 业务数据结构必须有 显式 interface，统一放在
src/types/，命名XxxVO / XxxForm / XxxQuery，不内联在组件里。 - 使用
import type { Xxx } from '@/types/xxx'导入纯类型，避免运行时冗余引入。 - 枚举统一定义在
src/enums/，使用const对象 +as const或enum，禁止散落的魔法字符串/数字。 - 空值处理优先用可选链
?.与空值合并??，避免多层&&嵌套。 - 不允许使用
// @ts-ignore、eslint-disable掩盖问题；确有必要的必须写清原因。
Vue 组件
- 组件一律
<script setup lang="ts">，禁止 Options API。 defineProps/defineEmits必须带类型：const props = defineProps<{ modelValue: string; disabled?: boolean }>() const emit = defineEmits<{ (e: 'update:modelValue', v: string): void }>()- Props 命名 camelCase，模板中绑定用 kebab-case；禁止在子组件内直接修改 props。
- 单向数据流：子组件通过 emit 或
defineExpose暴露方法，父组件通过ref调用。 - 响应式选择：基础数据用
ref，对象表单用reactive；禁止对reactive整体重新赋值，需要重置时用Object.assign。 - 副作用统一写在
watch/watchEffect/onMounted，并注意在onUnmounted清理定时器与事件监听。 - 计算属性必须无副作用；有副作用的逻辑放到方法或 watch。
v-if与v-for不得同处一个元素；v-for必须提供稳定:key（禁止用 index）。- 组件文件超过 300 行必须拆分；表单弹窗拆成独立子组件。
模板与样式
- 模板保持简洁，复杂判断抽成 computed，禁止在模板里写长表达式。
- 样式必须
<style scoped lang="scss">；覆盖 Element Plus 内部样式用:deep()，且必须限定父级作用域，禁止全局裸写。 - 颜色、圆角、间距等使用
src/styles/variables.scss中的变量，禁止硬编码色值。 - 布局优先使用 Element Plus 的
el-row/el-col与 flex 工具类，不写魔法margin-top: 17px。
注释与命名
- 注释只解释"为什么"，不解释"做了什么"。禁止无意义注释、禁止注释掉的代码块。
- 函数/变量命名见名知意，布尔值用
is/has/can前缀，事件处理用handleXxx，接口调用用fetchXxx / createXxx / updateXxx / deleteXxx。 - 代码中不得出现
console.log、调试代码与 TODO 之外的临时标记。
Git 提交
使用 Conventional Commits：feat|fix|refactor|perf|style|docs|chore|test(scope): subject，一次提交只做一件事。