更新记录

1.0.0（2025-11-09） 下载此版本

• 初始版本

平台兼容性

uni-app(4.16)

oui-composables

一个专为 uni-app 设计的 Vue 3 组合式函数库，提供常用的业务逻辑封装和工具函数。

特性

• Vue 3 组合式 API: 基于最新的 Vue 3 Composition API
• 类型安全: 完整的 TypeScript 类型定义
• 跨平台: 支持 H5、小程序、App 等多端

安装

# 通过 uni_modules 安装
# 将 oui-composables 文件夹放入项目的 uni_modules 目录中

API 概览

• useCounter
• useRequest
• useCreation

快速开始

这里以 <script setup> 展示基础用法：

<script setup lang="ts">
import { useCounter } from '@/uni_modules/oui-composables';

const [count, { inc, dec, set, reset }] = useCounter(0, { min: 0, max: 10 });
</script>

<template>
  <view>当前值：{{ count }}</view>
  <button @click="inc()">+1</button>
  <button @click="dec()">-1</button>
  <button @click="set(5)">设为 5</button>
  <button @click="reset()">重置</button>
</template>

API 文档

useCounter

计数器管理组合式函数，提供数值的增减、设置、重置等操作。

类型定义

function useCounter(initialValue?: number, options?: UseCounterOptions): UseCounterReturn;

interface UseCounterOptions {
  /** 最小值 */
  min?: number;
  /** 最大值 */
  max?: number;
}

interface UseCounterActions {
  /** 增加，默认加 1 */
  inc: (delta?: number) => void;
  /** 减少，默认减 1 */
  dec: (delta?: number) => void;
  /** 设置值 */
  set: (value: number | ((current: number) => number)) => void;
  /** 重置为初始值 */
  reset: () => void;
}

type UseCounterReturn = [DeepReadonly<Ref<number>>, UseCounterActions];

行为说明：

• 值会在 min 和 max 范围内自动约束。
• set 支持直接赋值或传入函数以基于当前值计算。
• 返回的 count 是只读的，使用 actions 更新。

使用示例

import { useCounter } from '@/uni_modules/oui-composables';

export default {
  setup() {
    // 基础用法
    const [count, { inc, dec, set, reset }] = useCounter(0);

    // 带限制的计数器
    const [limitedCount, actions] = useCounter(10, {
      min: 0,
      max: 100,
    });

    const handleIncrement = () => {
      inc(); // 增加 1
      inc(5); // 增加 5
    };

    const handleDecrement = () => {
      dec(); // 减少 1
      dec(3); // 减少 3
    };

    const handleSet = () => {
      set(50); // 设置为 50
      set((current) => current * 2); // 设置为当前值的 2 倍
    };

    return {
      count,
      limitedCount,
      handleIncrement,
      handleDecrement,
      handleSet,
      reset,
    };
  },
};

useCreation

一次性创建且在依赖未变化时复用的工厂函数，避免重复创建带来的性能损耗。

类型定义

function useCreation<T>(factory: () => T, deps: WatchSource<any>[]): T;

行为说明：

• 当依赖 deps 的引用未发生变化时，返回同一个结果；发生变化时重新创建。
• 适用于创建复杂对象或执行昂贵计算的场景。

使用示例

import { computed, ref } from 'vue';
import { useCreation } from '@/uni_modules/oui-composables';

const list = ref<number[]>([]);

// 仅在依赖引用变化时重建
const heavy = useCreation(() => list.value.map((i) => i * 2), [list]);

// 配合 computed 使用
const size = computed(() => list.value.length);
const heavyWithSize = useCreation(() => ({ size: size.value, data: heavy }), [size, list]);

useRequest

异步请求与数据状态管理，内置自动执行、防抖/节流、轮询、错误重试、聚焦刷新、loading 延迟等能力。

类型定义（核心）

function useRequest<TData, TParams extends any[] = any[]>(
  service: (...args: TParams) => Promise<TData>,
  options?: UseRequestOptions<TData, TParams>,
): UseRequestResult<TData, TParams>;

返回值：

• data: 响应数据只读 Ref<TData | undefined>
• error: 错误只读 Ref<Error | undefined>
• loading: 加载状态只读 Ref<boolean>
• run(...params): 手动触发
• runAsync(...params): 异步触发，返回 Promise<TData>
• refresh(): 使用上次参数重新请求
• refreshAsync(): 异步重新请求
• cancel(): 取消当前请求
• mutate(data): 直接修改 data（函数或值）

常用选项：

• 基础：manual 手动触发、ready 请求准备、defaultParams 默认参数、生命周期回调 onBefore/onSuccess/onError/onFinally
• 防抖/节流：debounceWait、debounceOptions（leading/trailing/maxWait）、throttleWait、throttleOptions
• 轮询：pollingInterval、pollingErrorRetryCount（-1 为不限制） 、pollingWhenHidden（页面不可见时是否轮询）
• 重试：retryCount、retryInterval（默认指数退避，封顶 30s）
• 聚焦刷新：refreshOnWindowFocus、focusTimespan（节流间隔）、refreshDeps、refreshDepsAction
• loading 延迟：loadingDelay（延迟显示 loading）

行为说明：

• 默认在 onMounted 自动执行，除非 manual = true 或 ready = false。
• 在组件 onUnmounted 自动 cancel。
• 所有返回的状态都是只读的，使用方法进行更新。

使用示例

自动执行与默认参数：

import { useRequest } from '@/uni_modules/oui-composables';

const getUser = async (id: string) => {
  // 你的服务函数，返回 Promise
  const res = await api.get(`/user/${id}`);
  return res.data;
};

// 自动在 mounted 时执行一次
const { data, loading, error, refresh } = useRequest(getUser, {
  defaultParams: ['1001'], // 对应服务函数参数
});

手动触发 + 防抖：

import { useRequest } from '@/uni_modules/oui-composables';

const search = async (q: string) => api.get('/search', { params: { q } }).then((r) => r.data);

const { data, loading, run } = useRequest(search, {
  manual: true,
  debounceWait: 300,
  debounceOptions: { leading: false, trailing: true },
});

// 调用时会被防抖
run('keyword');

轮询与错误重试：

const { data, loading } = useRequest(fetchStats, {
  pollingInterval: 5000,
  pollingErrorRetryCount: 3,
  retryCount: 2,
  retryInterval: 1000,
});