建立 2026-09-15 更新 2026-09-15

Composables

Composable 是用組合式 API 寫成的可重用函式，慣例以 use 開頭，例如 useMouse()、useFetch()。它不是元件，不會渲染 UI；它回傳狀態與方法，讓很多元件共用同一套邏輯。官方：Composables。

最小例子

// useMouse.js
import { ref, onMounted, onUnmounted } from 'vue'

export function useMouse() {
  const x = ref(0)
  const y = ref(0)

  function update(event) {
    x.value = event.pageX
    y.value = event.pageY
  }

  onMounted(() => window.addEventListener('mousemove', update))
  onUnmounted(() => window.removeEventListener('mousemove', update))

  return { x, y }
}

<script setup>
import { useMouse } from './useMouse'

const { x, y } = useMouse()
</script>

<template>游標：{{ x }}, {{ y }}</template>

每個呼叫 useMouse() 的元件都有自己的 x／y。若要跨元件共享同一份狀態，那是 Pinia 的工作，不是把 ref 做成模組單例（SSR 與測試會很痛）。

寫 composable 的習慣

• 只在 <script setup> 或 setup() 的同步範圍呼叫，這樣生命週期 hook 才綁得到目前元件。
• 回傳響應式物件（ref）或用 toRefs，讓呼叫端可以解構仍保持追蹤。
• 輸入用參數（也許是 ref 或 getter），不要在 composable 裡偷偷讀全域單例。
• 官方內建像 useTemplateRef、以及 VueUse 這類社群庫；先會自己寫一個，再用庫會比較知道它在做什麼。

元件負責畫面，composable 負責邏輯。分清楚之後，檔案會短很多。

推薦影音

Build your own Custom Composables in Vue

來源：Vue Mastery

用官方文件同款的 useMouse() 示範：ref、生命週期、回傳值，以及參數怎麼設計。對應本頁最小例子。

Vue JS 3 Tutorial #11 — The Composition API (part 2)

來源：Net Ninja　約 43 分鐘

後半段把 fetch 邏輯抽成可重用函式，並示範 onMounted。對應本頁「寫 composable 的習慣」。