create-adaptable-composable

建立可適應的 Composable

可適應的 composable 是可重複使用的函式，能同時接受響應式與非響應式輸入。這讓開發者可以在各種情境下使用 composable，而不必擔心輸入的響應性。

在 Vue.js 中設計可適應 composable 的步驟：

1. 確認 composable 的目的、API 設計以及預期的輸入/輸出。
2. 識別應該具有響應性的輸入參數（MaybeRef / MaybeRefOrGetter）。
3. 在 reactive 效果中使用 toValue() 或 toRef() 正規化輸入。
4. 使用 Vue 的響應式 API 實作 composable 的核心邏輯。

核心型別概念

型別工具

/**
 * 值或可寫入的 ref（value/ref/shallowRef/writable computed）
 */
export type MaybeRef<T = any> = T | Ref<T> | ShallowRef<T> | WritableComputedRef<T>;

/**
 * MaybeRef<T> + ComputedRef<T> + () => T
 */
export type MaybeRefOrGetter<T = any> = MaybeRef<T> | ComputedRef<T> | (() => T);

原則與規則

• 唯讀、適合 computed 的輸入：使用 MaybeRefOrGetter
• 需要可寫入 / 雙向輸入：使用 MaybeRef
• 參數可能是函式值（回呼、斷言、比較器）：不要使用 MaybeRefOrGetter，否則可能會意外將其作為 getter 呼叫。
• DOM/元素目標：如果需要 computed/衍生的目標，使用 MaybeRefOrGetter。

當使用 MaybeRefOrGetter 或 MaybeRef 時：

• 使用 toRef() 解析響應式值（例如作為 watcher 的來源）
• 使用 toValue() 解析非響應式值

範例

可適應的 useDocumentTitle Composable：唯讀的 title 參數

import { watch, toRef } from 'vue'
import type { MaybeRefOrGetter } from 'vue'

export function useDocumentTitle(title: MaybeRefOrGetter<string>) {
  watch(toRef(title), (t) => {
    document.title = t
  }, { immediate: true })
}

可適應的 useCounter Composable：雙向可寫入的 count 參數

import { watch, toRef } from 'vue'
import type { MaybeRef } from 'vue'

function useCounter(count: MaybeRef<number>) {
  const countRef = toRef(count)
  function add() {
    countRef.value++
  }
  return { add }
}