@uni-helper/uni-use

uni-app (vue3) 组合式工具集。要求 node>=18。

@uni-helper/uni-use

安装依赖

npm install @uni-helper/uni-use @vueuse/core@9

yarn v2+

请参考文档设置 nodeLinker 为 node_modules。

pnpm

请参考文档设置 shamefully-hoist 为 true。

目前没有支持 uni_modules 的计划，但欢迎 PR 贡献。

使用

tryOnHide

安全的 onHide。如果是在组件生命周期内，就调用 onHide()；如果不是，就直接调用函数。

import { tryOnHide } from '@uni-helper/uni-use'

tryOnHide(() => {
  ...
});

tryOnInit

安全的 onInit。如果是在组件生命周期内，就调用 onInit()；如果不是，就直接调用函数。

import { tryOnInit } from '@uni-helper/uni-use'

tryOnInit(() => {
  ...
});

tryOnLoad

安全的 onLoad。如果是在组件生命周期内，就调用 onLoad()；如果不是，就直接调用函数。

import { tryOnLoad } from '@uni-helper/uni-use'

tryOnLoad(() => {
  ...
});

tryOnReady

安全的 onReady。如果是在组件生命周期内，就调用 onReady()；如果不是，就直接调用函数。

import { tryOnReady } from '@uni-helper/uni-use'

tryOnReady(() => {
  ...
});

tryOnShow

安全的 onShow。如果是在组件生命周期内，就调用 onShow()；如果不是，就直接调用函数。

import { tryOnShow } from '@uni-helper/uni-use'

tryOnShow(() => {
  ...
});

tryOnUnload

安全的 onUnload。如果是在组件生命周期内，就调用 onUnload()；如果不是，就直接调用函数。

import { tryOnUnload } from '@uni-helper/uni-use'

tryOnUnload(() => {
  ...
});

useActionSheet

返回一个方法，调用后从底部向上弹出操作菜单。

import { useActionSheet } from '@uni-helper/uni-use';

const showActionSheet = useActionSheet({
  /* 传入配置 */
});
showActionSheet(); // 从底部向上弹出操作菜单

调用方法时，可以传入一个对象来更新已有配置，这样会使用扩展运算符来确认最终配置。

showActionSheet({
  /* 新传入配置 */
});

useClipboardData

获取和设置剪切板数据。你需要将默认值作为第一个参数传入。

import { useClipboardData } from '@uni-helper/uni-use';

const clipboardData = useClipboardData('');

// 查看剪切板数据
console.log('clipboardData', clipboardData.value);
// 设置剪切板数据
clipboardData.value = 'abc';

为了在操作数据后不显示消息提示框，你可以传递第二个参数。

import { useClipboardData } from '@uni-helper/uni-use';

const clipboardData = useClipboardData('', { showToast: false });

默认使用 console.error 输出错误信息，你也可以自定义错误处理。

import { useClipboardData } from '@uni-helper/uni-use';

const clipboardData = useClipboardData('', { onError: (error) => { ... } });

useDownloadFile

uni.downloadFile 的封装。使用方法参见 https://vueuse.org/integrations/useAxios/。

返回值中含有 task，可自行操作。

useGlobalData

获取和设置当前应用实例的 globalData。你需要将默认值作为第一个参数传入。

import { useGlobalData } from '@uni-helper/uni-use';

const globalData = useGlobalData({});

如果你需要使用 shallowRef，需要在第二个参数中指明。如果你需要设置一个很大的数据，shallowRef 会很有用。

useGlobalData({}, { shallow: true });

我们建议直接使用 pinia 作为状态管理工具。

useInterceptor

设置拦截器。

import { useInterceptor } from '@uni-helper/uni-use';

const event = 'request';

// 设置拦截器
const stop = useInterceptor(event, {
  invoke: (args) => {
    args.url = 'https://www.example.com/' + args.url;
  },
  success: (response) => {
    console.log('interceptor-success', response);
    response.data.code = 1;
  },
  fail: (error) => {
    console.log('interceptor-fail', error);
  },
  complete: (result) => {
    console.log('interceptor-complete', result);
  },
});

// 删除拦截器
stop(event);

useLoading

返回一个方法，调用后显示加载提示框。

import { useLoading } from '@uni-helper/uni-use';

const showLoading = useLoading({
  /* 传入配置 */
});
const hideLoading = showLoading(); // 显示加载提示框
hideLoading(); // 隐藏加载提示框

可以传入一个对象来更新已有配置，这样会使用扩展运算符来确认最终配置。

showLoading({
  /* 新传入配置 */
});

useModal

返回一个方法，调用后显示模态弹窗。

import { useModal } from '@uni-helper/uni-use';

const showModal = useModal({
  /* 传入配置 */
});
showModal(); // 显示模态弹窗

可以传入一个对象来更新已有配置，这样会使用扩展运算符来确认最终配置。

showModal({
  /* 新传入配置 */
});

useNetwork

获取网络信息。

import { useNetwork } from '@uni-helper/uni-use';

const { type, isWifi, is2g, is3g, is4g, is5g, isEthernet, isUnknown, isOnline, isOffline } =
  useNetwork();

useOnline

获取是否在线。基于 useNetwork。

import { useOnline } from '@uni-helper/uni-use';

const isOnline = useOnline();

usePage

获取当前页信息。

import { usePage } from '@uni-helper/uni-use';

const page = usePage();

usePages

获取当前页面栈信息。

import { usePages } from '@uni-helper/uni-use';

const pages = usePages();

usePageScroll

控制与监听页面滚动。

import { usePageScroll } from '@uni-helper/uni-use';

const { scrollTop } = usePageScroll({
  onPageScroll: true,
});

usePreferredDark

响应式的暗黑主题偏好。

import { usePreferredDark } from '@uni-helper/uni-use';

const prefersDark = usePreferredDark();

usePreferredLanguage

响应式的语言偏好。

import { usePreferredLanguage } from '@uni-helper/uni-use';

const language = usePreferredLanguage();

usePrevPage

获取前一页信息。

import { usePrevPage } from '@uni-helper/uni-use';

const prevPage = usePrevPage();

usePrevRoute

获取前一页面路由信息。

import { usePrevRoute } from '@uni-helper/uni-use';

const prevRoute = usePrevRoute();

useProvider

设置服务供应商参数，调用返回方法获取服务供应商。

import { useProvider } from '@uni-helper/uni-use';

const getProvider = useProvider({
  /* 传入配置 */
});
getProvider(); // 获取服务供应商

可以传入一个对象来更新已有配置，这样会使用扩展运算符来确认最终配置。

getProvider({
  /* 新传入配置 */
});

useRequest

uni.request 的封装。使用方法参见 https://vueuse.org/integrations/useAxios/。

返回值中含有 task，可自行操作。

useRoute

获取当前页路由信息。

import { useRoute } from '@uni-helper/uni-use';

const route = useRoute();

useRouter

获取路由相关。

import { useRouter } from '@uni-helper/uni-use';

const { pages, page, prevPage, route, prevRoute } = useRouter();

useScanCode

返回一个方法，调用后调起客户端扫码界面。

import { useScanCode } from '@uni-helper/uni-use';

const scan = useScanCode({
  /* 传入配置 */
});
scan(); // 调起扫码

可以传入一个对象来更新已有配置，这样会使用扩展运算符来确认最终配置。

scan({
  /* 新传入配置 */
});

useScreenBrightness

获取和设置屏幕亮度。你需要将默认值作为第一个参数传入。

import { useScreenBrightness } from '@uni-helper/uni-use';

const screenBrightness = useScreenBrightness(1);

// 查看屏幕亮度
console.log('screenBrightness', screenBrightness.value);
// 设置屏幕亮度
screenBrightness.value = 0;

默认使用 console.error 输出错误信息，你也可以自定义错误处理。

import { useScreenBrightness } from '@uni-helper/uni-use';

const screenBrightness = useScreenBrightness('', { onError: (error) => { ... } });

useSelectorQuery

uni.createSelectorQuery 的封装。

import { useSelectorQuery } from '@uni-helper/uni-use';

const { select, getBoundingClientRect, getFields, getScrollOffset, getContext } =
  useSelectorQuery();

// 获取 NodeRef
const node = select('#id');

// 获取单个 rect
const rect = await getBoundingClientRect('#id');

// 获取所有 .selector 的 rect，返回值为 UniApp.NodeInfo[]
const rects = await getBoundingClientRect('.selector', true);

// getFields，getScrollOffset，getContext 使用方式和 getBoundingClientRect 一致

useSocket

uni-app 关于 socket 的封装。使用方法参见 https://vueuse.org/core/useWebSocket/。

返回值中含有 task，可自行操作。

useStorageAsync

uni-app 关于 storage 的封装，使用方法参见 https://vueuse.org/core/useStorageAsync/。

useToast

返回一个方法，调用后显示消息提示框。

import { useToast } from '@uni-helper/uni-use';

const showToast = useToast({
  /* 传入配置 */
});
const hideToast = showToast(); // 显示消息提示框
hideToast(); // 隐藏消息提示框

可以传入一个对象来更新已有配置，这样会使用扩展运算符来确认最终配置。

showToast({
  /* 新传入配置 */
});

useUploadFile

uni.uploadFile 的封装。使用方法参见 https://vueuse.org/integrations/useAxios/。

返回值中含有 task，可自行操作。

useVisible

获取当前页面显隐状态。

import { useVisible } from '@uni-helper/uni-use';

const isVisible = useVisible();

其它

限制

在小程序和移动应用环境下有如下无法避开的限制：

缺失某些全局变量（如 window、navigator 等）
必须使用 uni-app 提供的 API 实现功能（如拦截器、存储等），API 不支持的也就无法支持，比如拦截同步 API、监听其它地方引起的剪切板变化等
无法使用顶层 await

在开发网页时，建议直接使用 vue，避免过多的环境判断代码，同时也能享受更好的生态，如 vueuse 的完整支持。

构建

目前 @uni-helper/uni-use 会使用 unbuild 将 uni API 之外的部分转译到 ES2017（即 ES8）。uni API 需要在项目构建时由 uni-app 官方提供的插件处理。

对于 vite + vue3 项目，请先设置 build.target 为 ES6。

import { defineConfig } from 'vite';
import uni from '@dcloudio/vite-plugin-uni';

// https://vitejs.dev/config/
export default defineConfig({
  build: {
    target: 'es6',
    cssTarget: 'chrome61', // https://cn.vitejs.dev/config/build-options.html#build-csstarget
  },
  optimizeDeps: {
    exclude: ['vue-demi'],
  },
  plugins: [
    ...,
    uni(),
    ...,
  ],
});

然后在 src/main.ts 或 src/main.js 处自行添加 polyfill。以下是使用 core-js 的示例（需要自行安装 core-js），你也可以使用 es-shims。

import 'core-js/actual/array/iterator';
import 'core-js/actual/promise';
import 'core-js/actual/object/assign';
import 'core-js/actual/promise/finally';
// 你可以根据需要自行添加额外的 polyfills
// import 'core-js/actual/object/values'
import { createSSRApp } from 'vue';
import App from './App.vue';

export function createApp() {
  const app = createSSRApp(App);
  return {
    app,
  };
}

微信小程序的 JavaScript 支持度见 wechat-miniprogram/miniprogram-compat。微信小程序要支持 vue3，需设置基础库最低版本为 2.11.2 或以上，2.11.2 对应 chrome>=53,ios>=10。

和 `unplugin-auto-import` 结合使用

// vite.config.ts
import { fileURLToPath } from 'node:url';
import { defineConfig } from 'vitest/config';
import autoImport from 'unplugin-auto-import/vite';
import { UniUseAutoImports } from '@uni-helper/uni-use';
import uni from '@dcloudio/vite-plugin-uni';

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [
    autoImport({
      imports: [
        '@vueuse/core',
        UniUseAutoImports, // 放在 @vueuse/core 之后以覆盖同名方法
      ],
    }),
    uni({ ... }),
  ],
});

EventBus

如果你想使用 EventBus，请考虑使用 VueUse - useEventBus、mitt 或 tiny-emitter。这个库不再重复提供类似功能。

TypeScript

@uni-helper/uni-use 本身使用 TypeScript 开发，拥有类型提示。

资源

改动日志

@uni-helper/uni-use

安装依赖

使用

tryOnHide

tryOnInit

tryOnLoad

tryOnReady

tryOnShow

tryOnUnload

useActionSheet

useClipboardData

useDownloadFile

useGlobalData

useInterceptor

useLoading

useModal

useNetwork

useOnline

usePage

usePages

usePageScroll

usePreferredDark

usePreferredLanguage

usePrevPage

usePrevRoute

useProvider

useRequest

useRoute

useRouter

useScanCode

useScreenBrightness

useSelectorQuery

useSocket

useStorageAsync

useToast

useUploadFile

useVisible

其它

限制

构建

和 unplugin-auto-import 结合使用

EventBus

TypeScript

资源

致谢

和 `unplugin-auto-import` 结合使用