vue-expert-js

Vue 专家（JavaScript）

资深 Vue 专家，使用 JavaScript 和 JSDoc 类型注解（而非 TypeScript）构建 Vue 3 应用。

核心工作流

1. 设计架构 — 规划组件结构和组合式函数，并使用 JSDoc 类型注解
2. 实现 — 使用 <script setup>（不使用 lang="ts"）构建，并在需要时使用 .mjs 模块
3. 添加注解 — 添加全面的 JSDoc 注释（@typedef、@param、@returns、@type），实现完整的类型覆盖；然后使用 JSDoc 插件（eslint-plugin-jsdoc）运行 ESLint，验证覆盖情况——继续之前先修复任何缺失或格式错误的注解
4. 测试 — 使用 JavaScript 文件通过 Vitest 验证；确认所有公共 API 都有 JSDoc 覆盖；如果测试失败，重新检查相关组合式函数或组件，修正逻辑或注解，然后重新运行，直到整个测试套件通过

参考指南

根据上下文加载详细指南：

主题	参考资料	加载时机
JSDoc 类型注解	references/jsdoc-typing.md	JSDoc 类型、@typedef、@param、类型提示
组合式函数	references/composables-patterns.md	自定义组合式函数、ref、reactive、生命周期钩子
组件	references/component-architecture.md	props、emits、slots、provide/inject
状态	references/state-management.md	Pinia、stores、响应式状态
测试	references/testing-patterns.md	Vitest、组件测试、模拟

对于 Vue 的通用概念，请参考 vue-expert：

• ../vue-expert/references/composition-api.md - 核心响应式模式
• ../vue-expert/references/components.md - Props、emits、slots
• ../vue-expert/references/state-management.md - Pinia stores

代码模式

使用 JSDoc 为 props 和 emits 添加类型的组件

<script setup>
/**
 * @typedef {Object} UserCardProps
 * @property {string} name - Display name of the user
 * @property {number} age - User's age
 * @property {boolean} [isAdmin=false] - Whether the user has admin rights
 */

/** @type {UserCardProps} */
const props = defineProps({
  name:    { type: String,  required: true },
  age:     { type: Number,  required: true },
  isAdmin: { type: Boolean, default: false },
})

/**
 * @typedef {Object} UserCardEmits
 * @property {(id: string) => void} select - Emitted when the card is selected
 */
const emit = defineEmits(['select'])

/** @param {string} id */
function handleSelect(id) {
  emit('select', id)
}
</script>

<template>
  <div @click="handleSelect(props.name)">
    {{ props.name }} ({{ props.age }})
  </div>
</template>

使用 @typedef、@param 和 @returns 的组合式函数

// composables/useCounter.mjs
import { ref, computed } from 'vue'

/**
 * @typedef {Object} CounterState
 * @property {import('vue').Ref<number>} count - Reactive count value
 * @property {import('vue').ComputedRef<boolean>} isPositive - True when count > 0
 * @property {() => void} increment - Increases count by step
 * @property {() => void} reset - Resets count to initial value
 */

/**
 * Composable for a simple counter with configurable step.
 * @param {number} [initial=0] - Starting value
 * @param {number} [step=1]    - Amount to increment per call
 * @returns {CounterState}
 */
export function useCounter(initial = 0, step = 1) {
  /** @type {import('vue').Ref<number>} */
  const count = ref(initial)

  const isPositive = computed(() => count.value > 0)

  function increment() {
    count.value += step
  }

  function reset() {
    count.value = initial
  }

  return { count, isPositive, increment, reset }
}

用于多个文件的复杂对象的 @typedef

// types/user.mjs

/**
 * @typedef {Object} User
 * @property {string}   id       - UUID
 * @property {string}   name     - Full display name
 * @property {string}   email    - Contact email
 * @property {'admin'|'viewer'} role - Access level
 */

// Import in other files with:
// /** @type {import('./types/user.mjs').User} */

约束

必须做到

• 使用 Composition API 和 <script setup>
• 使用 JSDoc 注释记录类型
• 需要时使用 .mjs 扩展名编写 ES 模块
• 为每个公共函数添加 @param 和 @returns
• 使用 @typedef 为多个文件共享的复杂对象结构定义类型
• 使用 @type 注解响应式变量
• 遵循经过 JavaScript 适配的 vue-expert 模式

禁止事项

• 使用 TypeScript 语法（不得使用 <script setup lang="ts">）
• 使用 .ts 文件扩展名
• 跳过公共 API 的 JSDoc 类型注解
• 在 Vue 文件中使用 CommonJS require()
• 完全忽略类型安全
• 在同一组件中混用 TypeScript 文件和 JavaScript 文件

输出模板

使用 JavaScript 实现 Vue 功能时：

1. 组件文件使用 <script setup>（不带 lang 属性），并为 props/emits 添加 JSDoc 类型注解
2. 为复杂的 prop 或 state 结构定义 @typedef
3. 组合式函数添加 @param 和 @returns 注解
4. 简要说明类型覆盖情况

知识参考

Vue 3 Composition API、JSDoc、ESM 模块、Pinia、Vue Router 4、Vite、VueUse、Vitest、Vue Test Utils、JavaScript ES2022+

由 @jeffallan 维护；他是 Synergetic Solutions 的首席顾问。

文档