Vue3 Composable 设计模式：可复用组合式函数的 10 个高级技巧#

Composition API 是 Vue3 最核心的变革。而 Composable（组合式函数）则是 Composition API 的灵魂——它是 Vue3 实现逻辑复用的标准方式，取代了 Vue2 时代的 Mixins、高阶组件等模式。

一个设计良好的 Composable 应该是独立的、可组合的、类型安全的。本文将通过 10 个高级技巧和大量实战代码，帮你掌握 Composable 的设计精髓。

技巧一：自动清理副作用#

一个优秀的 Composable 必须管理好自己的生命周期，在组件卸载时自动清理所有副作用。

useEventListener#

1
import { onMounted, onUnmounted, watch, unref, type Ref } from 'vue'
2

3
type MaybeRef<T> = T | Ref<T>
4

5
export function useEventListener<K extends keyof WindowEventMap>(
6
  target: MaybeRef<Window | null>,
7
  event: K,
8
  handler: (e: WindowEventMap[K]) => void,
9
  options?: AddEventListenerOptions
10
): void
11
export function useEventListener<K extends keyof HTMLElementEventMap>(
12
  target: MaybeRef<HTMLElement | null>,
13
  event: K,
14
  handler: (e: HTMLElementEventMap[K]) => void,
15
  options?: AddEventListenerOptions
16
): void
17
export function useEventListener(
18
  target: MaybeRef<EventTarget | null>,
19
  event: string,
20
  handler: EventListenerOrEventListenerObject,
21
  options?: AddEventListenerOptions
22
) {
23
  let cleanup: (() => void) | undefined
24

25
  function bindListener() {
26
    // 先清理旧的
27
    cleanup?.()
28

29
    const el = unref(target)
30
    if (!el) return
31

32
    el.addEventListener(event, handler, options)
33
    cleanup = () => {
34
      el.removeEventListener(event, handler, options)
35
    }
36
  }
37

38
  // 如果 target 是 ref，监听变化
39
  if (isRef(target)) {
40
    watch(target, bindListener, { immediate: true })
41
  } else {
42
    onMounted(bindListener)
43
  }
44

45
  // 组件卸载时自动清理
46
  onUnmounted(() => {
47
    cleanup?.()
48
  })
49
}

使用：

1
<script setup>
2
import { ref } from 'vue'
3
import { useEventListener } from '@/composables/useEventListener'
4

5
const buttonRef = ref<HTMLElement | null>(null)
6

7
// 不需要手动清理，组件卸载时自动移除监听
8
useEventListener(window, 'resize', () => {
9
  console.log('Window resized')
10
})
11

12
useEventListener(buttonRef, 'click', () => {
13
  console.log('Button clicked')
14
})
15
</script>
16

17
<template>
18
  <button ref="buttonRef">Click me</button>
19
</template>

useInterval 和 useTimeout#

1
import { ref, onUnmounted, watch, type Ref } from 'vue'
2

3
export function useInterval(
4
  callback: () => void,
5
  interval: Ref<number> | number,
6
  options: { immediate?: boolean } = {}
7
) {
8
  const isActive = ref(false)
9
  let timer: ReturnType<typeof setInterval> | null = null
10

11
  function start() {
12
    stop()
13
    isActive.value = true
14
    if (options.immediate) callback()
15
    timer = setInterval(callback, unref(interval))
16
  }
17

18
  function stop() {
19
    if (timer !== null) {
20
      clearInterval(timer)
21
      timer = null
22
    }
23
    isActive.value = false
24
  }
25

26
  // 如果 interval 是 ref，监听变化自动重启
27
  if (isRef(interval)) {
28
    watch(interval, () => {
29
      if (isActive.value) start()
30
    })
31
  }
32

33
  start()
34

35
  onUnmounted(stop)
36

37
  return { isActive, start, stop }
38
}

技巧二：接受 Ref 和普通值作为参数（MaybeRef 模式）#

一个灵活的 Composable 应该同时接受响应式引用和普通值：

1
import { computed, unref, type Ref } from 'vue'
2

3
type MaybeRef<T> = T | Ref<T>
4
type MaybeRefOrGetter<T> = MaybeRef<T> | (() => T)
5

6
// 统一解包工具
7
function toValue<T>(source: MaybeRefOrGetter<T>): T {
8
  if (typeof source === 'function') {
9
    return (source as () => T)()
10
  }
11
  return unref(source)
12
}

useTitle#

1
import { watch, ref, type MaybeRefOrGetter } from 'vue'
2

3
export function useTitle(
4
  newTitle?: MaybeRefOrGetter<string | null | undefined>,
5
  options: { restoreOnUnmount?: boolean } = {}
6
) {
7
  const title = ref(document.title)
8
  const originalTitle = document.title
9

10
  if (newTitle !== undefined) {
11
    watch(
12
      () => toValue(newTitle),
13
      (val) => {
14
        if (val != null) {
15
          document.title = val
16
          title.value = val
17
        }
18
      },
19
      { immediate: true }
20
    )
21
  }
22

23
  if (options.restoreOnUnmount) {
24
    onUnmounted(() => {
25
      document.title = originalTitle
26
    })
27
  }
28

29
  return title
30
}

使用：

1
<script setup>
2
import { ref, computed } from 'vue'
3
import { useTitle } from '@/composables/useTitle'
4

5
const count = ref(0)
6

7
// 传入 ref —— 标题会自动更新
8
useTitle(computed(() => `(${count.value}) 我的应用`))
9

10
// 传入普通字符串
11
useTitle('静态标题')
12

13
// 传入 getter
14
useTitle(() => `当前计数: ${count.value}`)
15
</script>

技巧三：返回值设计——对象 vs 数组#

对象解构（推荐大多数场景）#

1
export function useMouse() {
2
  const x = ref(0)
3
  const y = ref(0)
4
  const sourceType = ref<'mouse' | 'touch'>('mouse')
5

6
  // 返回对象，支持按需解构
7
  return { x, y, sourceType }
8
}
9

10
// 使用时可以只取需要的
11
const { x, y } = useMouse()

数组解构（适合简单的状态 + 操作模式）#

1
export function useToggle(initialValue = false) {
2
  const state = ref(initialValue)
3
  const toggle = (value?: boolean) => {
4
    state.value = value !== undefined ? value : !state.value
5
  }
6

7
  // 返回数组，允许自定义变量名
8
  return [state, toggle] as const
9
}
10

11
// 使用时可以自由命名
12
const [isOpen, toggleOpen] = useToggle()
13
const [isDark, toggleDark] = useToggle(true)

混合模式#

1
export function useFetch<T>(url: MaybeRefOrGetter<string>) {
2
  const data = ref<T | null>(null)
3
  const error = ref<Error | null>(null)
4
  const isLoading = ref(false)
5

6
  async function execute() {
7
    isLoading.value = true
8
    error.value = null
9
    try {
10
      const response = await fetch(toValue(url))
11
      if (!response.ok) throw new Error(`HTTP ${response.status}`)
12
      data.value = await response.json()
13
    } catch (e) {
14
      error.value = e instanceof Error ? e : new Error(String(e))
15
    } finally {
16
      isLoading.value = false
17
    }
18
  }
19

20
  // 返回对象 + 暴露方法
21
  return {
22
    data: readonly(data),
23
    error: readonly(error),
24
    isLoading: readonly(isLoading),
25
    execute,
26
    // 支持 await
27
    then(resolve: Function) {
28
      return execute().then(() => resolve({ data, error, isLoading }))
29
    }
30
  }
31
}

技巧四：useFetch——完整的数据请求 Composable#

1
import {
2
  ref, readonly, watch, shallowRef, computed,
3
  onUnmounted, type MaybeRefOrGetter
4
} from 'vue'
5

6
interface UseFetchOptions<T> {
7
  immediate?: boolean
8
  initialData?: T
9
  refetch?: boolean // URL 变化时是否自动重新请求
10
  timeout?: number
11
  beforeFetch?: (ctx: { url: string; options: RequestInit }) => void
12
  afterFetch?: (ctx: { data: T; response: Response }) => T
13
  onFetchError?: (ctx: { error: Error; data: T | null }) => void
14
}
15

16
export function useFetch<T = any>(
17
  url: MaybeRefOrGetter<string>,
18
  fetchOptions: RequestInit = {},
19
  options: UseFetchOptions<T> = {}
20
) {
21
  const {
22
    immediate = true,
23
    initialData = null as T,
24
    refetch = true,
25
    timeout = 30000
26
  } = options
27

28
  const data = shallowRef<T | null>(initialData)
29
  const error = ref<Error | null>(null)
30
  const isLoading = ref(false)
31
  const isFinished = ref(false)
32
  const abortController = ref<AbortController | null>(null)
33
  const statusCode = ref<number | null>(null)
34
  const response = shallowRef<Response | null>(null)
35

36
  // 计算属性
37
  const canAbort = computed(() => isLoading.value)
38

39
  function abort() {
40
    abortController.value?.abort()
41
    abortController.value = null
42
    isLoading.value = false
43
  }
44

45
  async function execute(throwOnFailed = false): Promise<any> {
46
    // 取消之前的请求
47
    abort()
48

49
    const controller = new AbortController()
50
    abortController.value = controller
51

52
    isLoading.value = true
53
    isFinished.value = false
54
    error.value = null
55

56
    const resolvedUrl = toValue(url)
57
    const mergedOptions: RequestInit = {
58
      ...fetchOptions,
59
      signal: controller.signal
60
    }
61

62
    // beforeFetch 钩子
63
    options.beforeFetch?.({ url: resolvedUrl, options: mergedOptions })
64

65
    // 超时处理
66
    const timeoutId = setTimeout(() => controller.abort(), timeout)
67

68
    try {
69
      const res = await fetch(resolvedUrl, mergedOptions)
70
      response.value = res
71
      statusCode.value = res.status
72

73
      if (!res.ok) {
74
        throw new Error(`HTTP Error: ${res.status} ${res.statusText}`)
75
      }
76

77
      let result = await res.json() as T
78

79
      // afterFetch 钩子
80
      if (options.afterFetch) {
81
        result = options.afterFetch({ data: result, response: res })
82
      }
83

84
      data.value = result
85
    } catch (e) {
86
      if ((e as Error).name === 'AbortError') return
87

88
      const fetchError = e instanceof Error ? e : new Error(String(e))
89
      error.value = fetchError
90
      options.onFetchError?.({ error: fetchError, data: data.value })
91

92
      if (throwOnFailed) throw fetchError
93
    } finally {
94
      clearTimeout(timeoutId)
95
      isLoading.value = false
96
      isFinished.value = true
97
      abortController.value = null
98
    }
99

100
    return { data, error, response }
101
  }
102

103
  // URL 变化时自动重新请求
104
  if (refetch) {
105
    watch(() => toValue(url), (newUrl) => {
106
      if (newUrl) execute()
107
    })
108
  }
109

110
  // 立即执行
111
  if (immediate) {
112
    execute()
113
  }
114

115
  // 组件卸载时取消请求
116
  onUnmounted(abort)
117

118
  return {
119
    data: readonly(data),
120
    error: readonly(error),
121
    isLoading: readonly(isLoading),
122
    isFinished: readonly(isFinished),
123
    statusCode: readonly(statusCode),
124
    response: readonly(response),
125
    canAbort,
126
    execute,
127
    abort
128
  }
129
}

使用示例：

1
<script setup>
2
import { ref, computed } from 'vue'
3
import { useFetch } from '@/composables/useFetch'
4

5
const page = ref(1)
6
const apiUrl = computed(() => `/api/posts?page=${page.value}&limit=10`)
7

8
const { data: posts, isLoading, error, execute: refresh } = useFetch(apiUrl, {}, {
9
  afterFetch({ data }) {
10
    // 转换数据
11
    return data.map(post => ({
12
      ...post,
13
      createdAt: new Date(post.createdAt)
14
    }))
15
  },
16
  onFetchError({ error }) {
17
    console.error('请求失败:', error.message)
18
  }
19
})
20

21
function nextPage() {
22
  page.value++ // URL 自动变化，自动重新请求
23
}
24
</script>
25

26
<template>
27
  <div>
28
    <div v-if="isLoading">加载中...</div>
29
    <div v-else-if="error">错误: {{ error.message }}</div>
30
    <div v-else>
31
      <article v-for="post in posts" :key="post.id">
32
        <h2>{{ post.title }}</h2>
33
      </article>
34
      <button @click="nextPage">下一页</button>
35
      <button @click="refresh()">刷新</button>
36
    </div>
37
  </div>
38
</template>

技巧五：useLocalStorage——持久化状态#

1
import { ref, watch, type Ref } from 'vue'
2

3
interface UseStorageOptions<T> {
4
  serializer?: {
5
    read: (raw: string) => T
6
    write: (value: T) => string
7
  }
8
  listenToStorageChanges?: boolean
9
  deep?: boolean
10
  onError?: (error: Error) => void
11
}
12

13
export function useLocalStorage<T>(
14
  key: string,
15
  initialValue: T,
16
  options: UseStorageOptions<T> = {}
17
): Ref<T> {
18
  const {
19
    serializer = {
20
      read: JSON.parse,
21
      write: JSON.stringify
22
    },
23
    listenToStorageChanges = true,
24
    deep = true,
25
    onError = console.error
26
  } = options
27

28
  // 从 localStorage 读取初始值
29
  function readFromStorage(): T {
30
    try {
31
      const raw = localStorage.getItem(key)
32
      if (raw !== null) {
33
        return serializer.read(raw)
34
      }
35
    } catch (e) {
36
      onError(e as Error)
37
    }
38
    return initialValue
39
  }
40

41
  // 写入 localStorage
42
  function writeToStorage(value: T) {
43
    try {
44
      if (value === null || value === undefined) {
45
        localStorage.removeItem(key)
46
      } else {
47
        localStorage.setItem(key, serializer.write(value))
48
      }
49
    } catch (e) {
50
      onError(e as Error)
51
    }
52
  }
53

54
  const data = ref(readFromStorage()) as Ref<T>
55

56
  // 监听变化，自动写入
57
  watch(
58
    data,
59
    (newValue) => writeToStorage(newValue),
60
    { deep }
61
  )
62

63
  // 监听其他标签页的 storage 变化
64
  if (listenToStorageChanges) {
65
    useEventListener(window, 'storage', (e: StorageEvent) => {
66
      if (e.key === key && e.newValue !== null) {
67
        try {
68
          data.value = serializer.read(e.newValue)
69
        } catch (err) {
70
          onError(err as Error)
71
        }
72
      }
73
    })
74
  }
75

76
  return data
77
}

使用：

1
<script setup>
2
import { useLocalStorage } from '@/composables/useLocalStorage'
3

4
// 自动持久化到 localStorage
5
const theme = useLocalStorage('app-theme', 'light')
6
const userPrefs = useLocalStorage('user-prefs', {
7
  fontSize: 14,
8
  language: 'zh-CN',
9
  sidebarCollapsed: false
10
})
11

12
function toggleTheme() {
13
  theme.value = theme.value === 'light' ? 'dark' : 'light'
14
  // 自动保存到 localStorage
15
}
16
</script>

技巧六：组合 Composable（Composable 的组合）#

Composable 最强大的地方在于它们可以互相组合：

useDark#

1
import { computed } from 'vue'
2
import { useLocalStorage } from './useLocalStorage'
3
import { useMediaQuery } from './useMediaQuery'
4

5
export function useDark() {
6
  // 组合 useLocalStorage
7
  const userPreference = useLocalStorage<'dark' | 'light' | 'auto'>(
8
    'color-scheme', 'auto'
9
  )
10

11
  // 组合 useMediaQuery
12
  const prefersDark = useMediaQuery('(prefers-color-scheme: dark)')
13

14
  const isDark = computed({
15
    get() {
16
      if (userPreference.value === 'auto') {
17
        return prefersDark.value
18
      }
19
      return userPreference.value === 'dark'
20
    },
21
    set(value: boolean) {
22
      userPreference.value = value ? 'dark' : 'light'
23
    }
24
  })
25

26
  // 自动更新 document class
27
  watch(isDark, (dark) => {
28
    document.documentElement.classList.toggle('dark', dark)
29
  }, { immediate: true })
30

31
  return {
32
    isDark,
33
    preference: userPreference,
34
    toggle: () => { isDark.value = !isDark.value }
35
  }
36
}

1
import { ref, onUnmounted } from 'vue'
2

3
export function useMediaQuery(query: string) {
4
  const matches = ref(false)
5

6
  let mediaQuery: MediaQueryList | undefined
7

8
  function update() {
9
    mediaQuery = window.matchMedia(query)
10
    matches.value = mediaQuery.matches
11
  }
12

13
  function handler(e: MediaQueryListEvent) {
14
    matches.value = e.matches
15
  }
16

17
  update()
18
  mediaQuery?.addEventListener('change', handler)
19

20
  onUnmounted(() => {
21
    mediaQuery?.removeEventListener('change', handler)
22
  })
23

24
  return matches
25
}

技巧七：依赖注入与 Composable#

利用 provide/inject 让 Composable 可以在组件树中共享状态：

useSharedState#

1
import { ref, provide, inject, type InjectionKey } from 'vue'
2

3
interface Notification {
4
  id: number
5
  type: 'success' | 'error' | 'warning' | 'info'
6
  message: string
7
  duration?: number
8
}
9

10
interface NotificationContext {
11
  notifications: Ref<Notification[]>
12
  notify: (notification: Omit<Notification, 'id'>) => void
13
  remove: (id: number) => void
14
  clear: () => void
15
}
16

17
const NotificationKey: InjectionKey<NotificationContext> = Symbol('notification')
18

19
let nextId = 0
20

21
// Provider Composable —— 在根组件调用
22
export function provideNotification() {
23
  const notifications = ref<Notification[]>([])
24

25
  function notify(notification: Omit<Notification, 'id'>) {
26
    const id = nextId++
27
    const item: Notification = { ...notification, id }
28
    notifications.value.push(item)
29

30
    // 自动移除
31
    const duration = notification.duration ?? 3000
32
    if (duration > 0) {
33
      setTimeout(() => remove(id), duration)
34
    }
35
  }
36

37
  function remove(id: number) {
38
    const index = notifications.value.findIndex(n => n.id === id)
39
    if (index !== -1) {
40
      notifications.value.splice(index, 1)
41
    }
42
  }
43

44
  function clear() {
45
    notifications.value = []
46
  }
47

48
  const context: NotificationContext = {
49
    notifications,
50
    notify,
51
    remove,
52
    clear
53
  }
54

55
  provide(NotificationKey, context)
56

57
  return context
58
}
59

60
// Consumer Composable —— 在任何子组件调用
61
export function useNotification(): NotificationContext {
62
  const context = inject(NotificationKey)
63
  if (!context) {
64
    throw new Error('useNotification() must be used inside a component tree with provideNotification()')
65
  }
66
  return context
67
}

使用：

1
<script setup>
2
import { provideNotification } from '@/composables/useNotification'
3
import NotificationContainer from './NotificationContainer.vue'
4

5
const { notifications } = provideNotification()
6
</script>
7

8
<template>
9
  <div id="app">
10
    <router-view />
11
    <NotificationContainer :notifications="notifications" />
12
  </div>
13
</template>

1
<!-- 任何子组件 -->
2
<script setup>
3
import { useNotification } from '@/composables/useNotification'
4

5
const { notify } = useNotification()
6

7
async function handleSave() {
8
  try {
9
    await saveData()
10
    notify({ type: 'success', message: '保存成功！' })
11
  } catch (e) {
12
    notify({ type: 'error', message: '保存失败: ' + e.message })
13
  }
14
}
15
</script>

技巧八：useVModel——双向绑定的优雅封装#

1
import { computed, getCurrentInstance } from 'vue'
2

3
export function useVModel<
4
  P extends Record<string, any>,
5
  K extends keyof P
6
>(
7
  props: P,
8
  key: K,
9
  emit?: (event: string, ...args: any[]) => void
10
) {
11
  const vm = getCurrentInstance()
12
  const _emit = emit || vm?.emit
13

14
  if (!_emit) {
15
    throw new Error('useVModel: emit function is required')
16
  }
17

18
  return computed({
19
    get() {
20
      return props[key]
21
    },
22
    set(value) {
23
      _emit(`update:${String(key)}`, value)
24
    }
25
  })
26
}

使用：

1
<script setup>
2
import { useVModel } from '@/composables/useVModel'
3

4
const props = defineProps<{
5
  modelValue: boolean
6
  title: string
7
}>()
8

9
const emit = defineEmits<{
10
  'update:modelValue': [value: boolean]
11
  'update:title': [value: string]
12
}>()
13

14
// 直接当 ref 用，修改时自动 emit
15
const isOpen = useVModel(props, 'modelValue', emit)
16
const dialogTitle = useVModel(props, 'title', emit)
17

18
function close() {
19
  isOpen.value = false  // 自动触发 emit('update:modelValue', false)
20
}
21
</script>
22

23
<template>
24
  <Teleport to="body">
25
    <div v-if="isOpen" class="modal-overlay" @click.self="close">
26
      <div class="modal-dialog">
27
        <input v-model="dialogTitle" />
28
        <slot />
29
        <button @click="close">关闭</button>
30
      </div>
31
    </div>
32
  </Teleport>
33
</template>

技巧九：useAsyncState——异步状态管理#

1
import { ref, shallowRef, readonly, type Ref } from 'vue'
2

3
interface UseAsyncStateOptions<T> {
4
  immediate?: boolean
5
  resetOnExecute?: boolean
6
  onError?: (e: Error) => void
7
  onSuccess?: (data: T) => void
8
  delay?: number
9
}
10

11
export function useAsyncState<T, Args extends any[] = []>(
12
  promise: (...args: Args) => Promise<T>,
13
  initialState: T,
14
  options: UseAsyncStateOptions<T> = {}
15
) {
16
  const {
17
    immediate = true,
18
    resetOnExecute = false,
19
    onError,
20
    onSuccess,
21
    delay = 0
22
  } = options
23

24
  const state = shallowRef<T>(initialState)
25
  const isReady = ref(false)
26
  const isLoading = ref(false)
27
  const error = ref<Error | null>(null)
28

29
  async function execute(...args: Args) {
30
    if (resetOnExecute) {
31
      state.value = initialState
32
    }
33
    error.value = null
34
    isReady.value = false
35
    isLoading.value = true
36

37
    if (delay > 0) {
38
      await new Promise(r => setTimeout(r, delay))
39
    }
40

41
    try {
42
      const result = await promise(...args)
43
      state.value = result
44
      isReady.value = true
45
      onSuccess?.(result)
46
    } catch (e) {
47
      const err = e instanceof Error ? e : new Error(String(e))
48
      error.value = err
49
      onError?.(err)
50
    } finally {
51
      isLoading.value = false
52
    }
53

54
    return state.value
55
  }
56

57
  if (immediate) {
58
    execute(...([] as unknown as Args))
59
  }
60

61
  return {
62
    state: readonly(state) as Readonly<Ref<T>>,
63
    isReady: readonly(isReady),
64
    isLoading: readonly(isLoading),
65
    error: readonly(error),
66
    execute
67
  }
68
}

使用：

1
<script setup>
2
import { useAsyncState } from '@/composables/useAsyncState'
3

4
interface User {
5
  id: number
6
  name: string
7
  email: string
8
}
9

10
const { state: users, isLoading, error, execute: fetchUsers } = useAsyncState<User[]>(
11
  async () => {
12
    const res = await fetch('/api/users')
13
    return res.json()
14
  },
15
  [], // 初始值
16
  {
17
    onError(e) {
18
      console.error('获取用户失败:', e)
19
    },
20
    onSuccess(data) {
21
      console.log(`获取到 ${data.length} 个用户`)
22
    }
23
  }
24
)
25
</script>
26

27
<template>
28
  <div>
29
    <button @click="fetchUsers()" :disabled="isLoading">
30
      {{ isLoading ? '加载中...' : '刷新' }}
31
    </button>
32
    <p v-if="error" class="error">{{ error.message }}</p>
33
    <ul>
34
      <li v-for="user in users" :key="user.id">
35
        {{ user.name }} - {{ user.email }}
36
      </li>
37
    </ul>
38
  </div>
39
</template>

技巧十：useInfiniteScroll——无限滚动#

这个 Composable 组合了多个底层 Composable，展示了复杂 Composable 的设计模式：

1
import { ref, computed, watch, type Ref } from 'vue'
2
import { useEventListener } from './useEventListener'
3
import { useThrottle } from './useThrottle'
4

5
interface UseInfiniteScrollOptions {
6
  distance?: number         // 距离底部多少像素触发加载
7
  direction?: 'top' | 'bottom'
8
  preserveScrollPosition?: boolean
9
  canLoadMore?: Ref<boolean> | (() => boolean)
10
}
11

12
export function useInfiniteScroll(
13
  container: Ref<HTMLElement | null>,
14
  loadMore: () => Promise<void>,
15
  options: UseInfiniteScrollOptions = {}
16
) {
17
  const {
18
    distance = 100,
19
    direction = 'bottom',
20
    preserveScrollPosition = false,
21
  } = options
22

23
  const isLoading = ref(false)
24
  const isComplete = ref(false) // 没有更多数据了
25

26
  const canLoadMore = computed(() => {
27
    if (isComplete.value) return false
28
    if (isLoading.value) return false
29
    if (options.canLoadMore) {
30
      return typeof options.canLoadMore === 'function'
31
        ? options.canLoadMore()
32
        : options.canLoadMore.value
33
    }
34
    return true
35
  })
36

37
  async function handleLoad() {
38
    if (!canLoadMore.value) return
39

40
    isLoading.value = true
41
    const el = container.value
42
    const previousScrollHeight = el?.scrollHeight || 0
43

44
    try {
45
      await loadMore()
46
    } catch (e) {
47
      console.error('加载更多失败:', e)
48
    } finally {
49
      isLoading.value = false
50

51
      // 向上加载时保持滚动位置
52
      if (preserveScrollPosition && direction === 'top' && el) {
53
        const newScrollHeight = el.scrollHeight
54
        el.scrollTop += newScrollHeight - previousScrollHeight
55
      }
56
    }
57
  }
58

59
  function checkShouldLoad() {
60
    const el = container.value
61
    if (!el || !canLoadMore.value) return
62

63
    if (direction === 'bottom') {
64
      const { scrollTop, scrollHeight, clientHeight } = el
65
      if (scrollTop + clientHeight >= scrollHeight - distance) {
66
        handleLoad()
67
      }
68
    } else {
69
      if (el.scrollTop <= distance) {
70
        handleLoad()
71
      }
72
    }
73
  }
74

75
  // 节流滚动检查
76
  const throttledCheck = useThrottle(checkShouldLoad, 200)
77

78
  // 监听滚动事件
79
  useEventListener(container, 'scroll', throttledCheck)
80

81
  // 容器变化时检查一次
82
  watch(container, () => {
83
    if (container.value) checkShouldLoad()
84
  })
85

86
  function done() {
87
    isComplete.value = true
88
  }
89

90
  function reset() {
91
    isComplete.value = false
92
    isLoading.value = false
93
  }
94

95
  return {
96
    isLoading: readonly(isLoading),
97
    isComplete: readonly(isComplete),
98
    done,
99
    reset,
100
    check: checkShouldLoad
101
  }
102
}

1
export function useThrottle(fn: Function, delay: number) {
2
  let lastCall = 0
3
  let timer: ReturnType<typeof setTimeout> | null = null
4

5
  return function throttled(...args: any[]) {
6
    const now = Date.now()
7
    const remaining = delay - (now - lastCall)
8

9
    if (remaining <= 0) {
10
      if (timer) {
11
        clearTimeout(timer)
12
        timer = null
13
      }
14
      lastCall = now
15
      fn(...args)
16
    } else if (!timer) {
17
      timer = setTimeout(() => {
18
        lastCall = Date.now()
19
        timer = null
20
        fn(...args)
21
      }, remaining)
22
    }
23
  }
24
}

使用：

1
<script setup>
2
import { ref } from 'vue'
3
import { useInfiniteScroll } from '@/composables/useInfiniteScroll'
4

5
const listContainer = ref<HTMLElement | null>(null)
6
const items = ref<any[]>([])
7
const page = ref(1)
8

9
const { isLoading, isComplete, done } = useInfiniteScroll(
10
  listContainer,
11
  async () => {
12
    const res = await fetch(`/api/items?page=${page.value}`)
13
    const data = await res.json()
14

15
    if (data.length === 0) {
16
      done() // 没有更多数据
17
      return
18
    }
19

20
    items.value.push(...data)
21
    page.value++
22
  }
23
)
24
</script>
25

26
<template>
27
  <div ref="listContainer" class="scroll-container" style="height: 500px; overflow-y: auto;">
28
    <div v-for="item in items" :key="item.id" class="item">
29
      {{ item.name }}
30
    </div>
31
    <div v-if="isLoading" class="loading">加载中...</div>
32
    <div v-if="isComplete" class="complete">没有更多了</div>
33
  </div>
34
</template>

Composable 设计原则总结#

经过以上 10 个技巧的实践，我们可以总结出几条 Composable 设计原则：

1. 命名规范#

1
// ✅ 以 use 开头
2
export function useCounter() {}
3
export function useFetch() {}
4

5
// ✅ provide 系列以 provide/create 开头
6
export function provideTheme() {}
7
export function createSharedComposable() {}
8

9
// ❌ 不要省略 use 前缀
10
export function counter() {}
11
export function fetchData() {}

2. 输入灵活性#

1
// ✅ 接受 MaybeRefOrGetter
2
function useFetch(url: MaybeRefOrGetter<string>) {
3
  const resolvedUrl = computed(() => toValue(url))
4
}
5

6
// 这样调用方可以传入任何形式
7
useFetch('/api/users')           // 字符串
8
useFetch(urlRef)                  // Ref
9
useFetch(() => `/api/users/${id}`) // Getter

3. 输出只读性#

1
// ✅ 返回 readonly ref
2
return {
3
  data: readonly(data),
4
  isLoading: readonly(isLoading),
5
  execute  // 方法不需要 readonly
6
}
7

8
// ❌ 直接暴露可写 ref
9
return {
10
  data,      // 外部可以直接修改，破坏数据一致性
11
  isLoading
12
}

4. 副作用自清理#

1
export function useXxx() {
2
  const timer = setInterval(/* ... */)
3
  const handler = () => { /* ... */ }
4
  window.addEventListener('resize', handler)
5

6
  // ✅ 必须在 onUnmounted 中清理
7
  onUnmounted(() => {
8
    clearInterval(timer)
9
    window.removeEventListener('resize', handler)
10
  })
11
}

5. SSR 兼容性#

1
export function useLocalStorage(key: string, initialValue: any) {
2
  // ✅ 检查环境
3
  if (typeof window === 'undefined') {
4
    return ref(initialValue) // SSR 环境返回默认值
5
  }
6
  // 浏览器环境的逻辑...
7
}

掌握这些设计模式和技巧，你就能写出真正可复用、可组合、可测试的 Vue3 Composable，构建出更优雅的前端架构。

音乐

音乐