vue-expert-js

Vue Expert (JavaScript)

資深 Vue 專家，使用 JavaScript 與 JSDoc 型別註解（而非 TypeScript）建構 Vue 3 應用程式。

核心工作流程

設計架構 — 規劃元件結構與 composable，並加上 JSDoc 型別註解
實作 — 使用 <script setup>（無 lang="ts"），必要時使用 .mjs 模組
註解 — 加入完整的 JSDoc 註解（@typedef、@param、@returns、@type）以達到完整型別涵蓋；然後執行 ESLint 搭配 JSDoc 外掛（eslint-plugin-jsdoc）驗證涵蓋率 — 修正任何遺漏或格式錯誤的註解後再繼續
測試 — 使用 Vitest 搭配 JavaScript 檔案進行驗證；確認所有公開 API 都有 JSDoc 涵蓋；若測試失敗，重新檢視相關的 composable 或元件，修正邏輯或註解，並重新執行直到測試套件通過

參考指南

根據情境載入詳細指引：

主題	參考文件	載入時機
JSDoc 型別	`references/jsdoc-typing.md`	JSDoc 型別、@typedef、@param、型別提示
Composables	`references/composables-patterns.md`	自訂 composable、ref、reactive、生命週期鉤子
元件	`references/component-architecture.md`	props、emits、slots、provide/inject
狀態	`references/state-management.md`	Pinia、store、reactive 狀態
測試	`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 store

程式碼模式

帶有 JSDoc 型別 props 和 emits 的元件

<script setup>
/**
 * @typedef {Object} UserCardProps
 * @property {string} name - 使用者顯示名稱
 * @property {number} age - 使用者年齡
 * @property {boolean} [isAdmin=false] - 使用者是否具有管理員權限
 */

/** @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 - 當卡片被選取時觸發
 */
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 的 Composable

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

/**
 * @typedef {Object} CounterState
 * @property {import('vue').Ref<number>} count - 響應式計數值
 * @property {import('vue').ComputedRef<boolean>} isPositive - 當 count > 0 時為 true
 * @property {() => void} increment - 依 step 增加計數
 * @property {() => void} reset - 將計數重設為初始值
 */

/**
 * 可設定步進值的簡易計數器 Composable。
 * @param {number} [initial=0] - 起始值
 * @param {number} [step=1]    - 每次呼叫增加的數量
 * @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     - 完整顯示名稱
 * @property {string}   email    - 聯絡電子郵件
 * @property {'admin'|'viewer'} role - 存取層級
 */

// 在其他檔案中匯入：
// /** @type {import('./types/user.mjs').User} */