Vue 3 组合式函数

中文 | English

Vue 3 组合式 API 钩子函数集合。

安装

pnpm add @feutopia/vue-hooks

钩子函数

useInterval

用于设置和管理定时器的钩子函数。

const { pause, resume, isActive } = useInterval(
  () => {
    // 你的回调函数
  },
  1000, // 间隔时间（毫秒）
  { immediate: false } // 配置项
);

参数：

• callback: 每个间隔需要执行的回调函数
• interval: 间隔时间，单位为毫秒（默认：1000）
• options:
  • immediate: 是否立即执行回调函数（默认：false）

返回值：

• pause: 暂停定时器的函数
• resume: 恢复定时器的函数
• isActive: 表示定时器是否激活的响应式引用

useRefExpose

一个用于更便捷地访问组件 ref 属性的钩子函数。

参数：

• ref: 包含组件实例的 Vue ref，可以是 undefined 或 null

返回值：

• 一个代理对象，允许直接访问 ref 值的属性

特性：

• 访问属性时自动解包 .value
• 安全处理 null/undefined 的 ref 值
• 支持使用 in 运算符检查属性

常见用例：

1. 直接访问组件 ref 的属性

const target = ref<ComponentInstance | null>(null);
const exposed = useRefExpose(target);
// 无需使用 .value 直接访问属性
console.log(exposed.someProperty);
console.log(exposed.someMethod());

2. 在封装组件中转发子组件的 ref

<script setup lang="ts">
import { ref } from 'vue'
import ChildComponent from './ChildComponent.vue'
import { useRefExpose } from '@feutopia/vue-hooks'

const childRef = ref<InstanceType<typeof ChildComponent>>()
// 转发子组件的所有方法和属性
defineExpose(useRefExpose(childRef))
</script>

<template>
  <ChildComponent ref="childRef" />
</template>

useResizeObserver

用于观察元素大小变化的钩子函数，基于 ResizeObserver。

const target = ref<HTMLElement | null>(null);
const { isSupported, stop } = useResizeObserver(target, (entries) => {
  // 处理大小变化
});

参数：

• target: 要观察的 HTML 元素的引用
• callback: 当大小变化时调用的函数

返回值：

• isSupported: 表示浏览器是否支持 ResizeObserver 的计算属性
• stop: 停止观察的函数

useRequest

一个用于管理异步请求的 Hook，支持轮询、手动控制和自动错误处理等特性。

const {
  data,
  loading,
  error,
  run,
  cancel,
  refresh,
  cancelled
  } = useRequest<TData, TParams>(
  (params: TParams) => Promise<TData>, // service 函数
  {
  // 配置项
  manual?: boolean | Ref<boolean>,
  pollingInterval?: number | Ref<number>,
  ready?: boolean | Ref<boolean>,
  refreshDeps?: WatchSource[],
  params?: TParams[],
  cacheKey?: string | symbol | Ref<string | symbol>,
  cacheTime?: number | Ref<number>,
  // 回调函数
  onBefore?: () => void,
  onSuccess?: (data: TData, params: TParams[]) => void,
  onError?: (error: Error) => void,
  onFinally?: () => void,
  }
);

参数：

• service: (params: TParams) => Promise<TData>

  • 执行异步请求的函数
  • 泛型类型：
    • TData: service 返回的数据类型
    • TParams: service 接收的参数类型

• options:

  • manual: 是否手动触发请求（默认：false）
  • pollingInterval: 轮询间隔时间（毫秒）（默认：0，表示不轮询）
  • ready: 控制请求是否应该执行（默认：true）
  • refreshDeps: 依赖数组，当依赖变化时触发请求刷新
  • params: service 函数的初始参数
  • cacheKey: 缓存请求结果的唯一键
  • cacheTime: 缓存持续时间（毫秒）（默认：0，表示不缓存）
  • onBefore: 请求开始前的回调
  • onSuccess: 请求成功时的回调，参数为响应数据和请求参数
  • onError: 请求失败时的回调，参数为错误对象
  • onFinally: 请求完成时的回调

返回值：

• data: Ref<TData | undefined> - 响应数据
• loading: Ref<boolean> - 加载状态
• error: Ref<Error | undefined> - 请求失败时的错误对象
• run: (...params: TParams[]) => Promise<FetchState<TData>> - 手动触发请求的函数
• cancel: () => void - 取消当前请求的函数
• refresh: () => Promise<FetchState<TData>> - 使用上次的参数刷新请求的函数
• cancelled: Ref<boolean> - 请求是否被取消

示例：

interface User {
  id: number;
  name: string;
}
const { data, loading, run } = useRequest<User, [number]>(
  (id) => fetchUser(id),
  {
    manual: true,
    onSuccess: (data) => {
      console.log("用户加载成功:", data.name);
    },
  }
);
// 手动触发请求并传入参数
run(1);

useDate

用于管理和格式化日期/时间的钩子函数，支持自动更新。

const { dateInfo, formatTime, formatDate } = useDate();

返回值：

• dateInfo: 当前日期信息的响应式引用，每秒自动更新
• formatTime: 格式化当前时间的函数（HH:MM:SS）
• formatDate: 格式化当前日期的函数（YYYY-MM-DD）

示例：

const { dateInfo, formatTime, formatDate } = useDate();

// 使用默认分隔符":"获取格式化时间
console.log(formatTime()); // "14:30:45"

// 使用自定义分隔符获取格式化时间
console.log(formatTime("-")); // "14-30-45"

// 使用默认分隔符"-"获取格式化日期
console.log(formatDate()); // "2024-03-20"

// 使用自定义分隔符获取格式化日期
console.log(formatDate("/")); // "2024/03/20"

// 访问原始日期信息
console.log(dateInfo.value.year);  // 2024
console.log(dateInfo.value.month); // 3
console.log(dateInfo.value.day);   // 20

许可证

MIT