create-adaptable-composable

创建可适配的可组合函数

可适配的可组合函数是可以接受响应式和非响应式输入的可复用函数。这使得开发者可以在各种上下文中使用该可组合函数，而无需担心输入的响应性。

在 Vue.js 中设计可适配的可组合函数的步骤：

1. 确认可组合函数的用途、API 设计以及预期的输入/输出。
2. 识别应该为响应式的输入参数（MaybeRef / MaybeRefOrGetter）。
3. 在响应式副作用内部使用 toValue() 或 toRef() 规范化输入。
4. 使用 Vue 的响应式 API 实现可组合函数的核心逻辑。

核心类型概念

类型工具

/**
 * 值或可写 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);

策略与规则

• 只读、计算友好的输入：使用 MaybeRefOrGetter
• 需要可写/双向输入：使用 MaybeRef
• 参数可能是函数值（回调/谓词/比较器）：不要使用 MaybeRefOrGetter，否则可能会意外将其作为 getter 调用。
• DOM/元素目标：如果需要计算/派生的目标，使用 MaybeRefOrGetter。

当使用 MaybeRefOrGetter 或 MaybeRef 时：

• 使用 toRef() 解析响应式值（例如，作为 watcher 源）
• 使用 toValue() 解析非响应式值

示例

可适配的 useDocumentTitle 可组合函数：只读的 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 可组合函数：双向可写的 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 }
}