Skip to content
On this page

[DEPRECATED] uni-app-use

该依赖已废弃,请迁移到功能一致的 @uni-helper/uni-use

License

npm

uni-app (vue3) 组合式工具集。

安装

使用 npm

shell
npm install uni-app-use @vueuse/core
1

使用 yarn

shell
yarn install uni-app-use @vueuse/core
1

使用 pnpm

shell
pnpm install uni-app-use @vueuse/core
1

使用 cnpm

shell
cnpm install uni-app-use @vueuse/core
1

目前只考虑小程序和移动应用环境。不考虑支持 uni_modules

使用

tryOnHide

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

typescript
import { tryOnHide } from 'uni-app-use'

tryOnHide(() => {
  ...
});
1
2
3
4
5

tryOnInit

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

typescript
import { tryOnInit } from 'uni-app-use'

tryOnInit(() => {
  ...
});
1
2
3
4
5

tryOnLoad

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

typescript
import { tryOnLoad } from 'uni-app-use'

tryOnLoad(() => {
  ...
});
1
2
3
4
5

tryOnReady

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

typescript
import { tryOnReady } from 'uni-app-use'

tryOnReady(() => {
  ...
});
1
2
3
4
5

tryOnShow

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

typescript
import { tryOnShow } from 'uni-app-use'

tryOnShow(() => {
  ...
});
1
2
3
4
5

tryOnUnload

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

typescript
import { tryOnUnload } from 'uni-app-use'

tryOnUnload(() => {
  ...
});
1
2
3
4
5

useAccountInfo

获取当前账号信息。

typescript
import { useAccountInfo } from 'uni-app-use';

const accountInfo = useAccountInfo();
1
2
3

useActionSheet

设置菜单列表参数,调用返回方法显示菜单列表。

typescript
import { useActionSheet } from 'uni-app-use';

const showActionSheet = useActionSheet({
  /* 传入配置 */
});
showActionSheet(); // 实际显示菜单列表
1
2
3
4
5
6

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

typescript
showActionSheet({
  /* 新传入配置 */
});
1
2
3

useAddress

获取地址相关。

typescript
import { useAddress } from 'uni-app-use';

const { chooseAddress, choose } = useAddress();
1
2
3

useApp

获取当前应用实例。如果想要获取 globalData,可以直接使用 useGlobalData

typescript
import { useApp } from 'uni-app-use';

const app = useApp();
1
2
3

useAppBaseInfo

获取应用基础信息。

typescript
import { useAppBaseInfo } from 'uni-app-use';

const appBaseInfo = useAppBaseInfo();
1
2
3

UseAppBaseInfo

useAppBaseInfo 的组件版本。

vue
<script setup lang="ts">
import { UseAppBaseInfo } from 'uni-app-use';
</script>

<template>
  <UseAppBaseInfo v-slot="{ ... }"> ... </UseAppBaseInfo>
</template>
1
2
3
4
5
6
7

useArrayBufferToBase64

获取 ArrayBuffer 对应的 base64。可以直接传入 ref

typescript
import { useArrayBufferToBase64 } from 'uni-app-use';

const base64 = useArrayBufferToBase64(arrayBuffer);
1
2
3

useAudio

获取音频相关。

typescript
import { useAudio } from 'uni-app-use';

const {
  backgroundAudioManager,
  backgroundManager,
  useBackgroundAudioManager,
  useBackgroundManager,
  createInnerAudioContext,
  createInnerContext,
} = useAudio();
1
2
3
4
5
6
7
8
9
10

useAuthorize

获取授权相关。

typescript
import { useAuthorize } from 'uni-app-use';

const { authorize, openSetting, getSetting, openAppAuthorizeSetting, getAppAuthorizeSetting } =
  useAuthorize();
1
2
3
4

useBackground

获取背景设置方法。

typescript
import { useBackground } from 'uni-app-use';

const { setBackgroundColor, setColor, setBackgroundTextStyle, setTextStyle } = useBackground();
1
2
3

useBase64ToArrayBuffer

获取 base64 对应的 ArrayBuffer。可以直接传入 ref

typescript
import { useBase64ToArrayBuffer } from 'uni-app-use';

const arrayBuffer = useBase64ToArrayBuffer(base64);
1
2
3

useCamera

获取相机相关。

typescript
import { useCamera } from 'uni-app-use';

const { createCameraContext, createContext } = useCamera();
1
2
3

useClipboardData

获取和设置剪切板数据。

typescript
import { useClipboardData } from 'uni-app-use';

const { clipboardData, setClipboardData } = useClipboardData();

// 查看剪切板数据
console.log('clipboardData', clipboardData);
// 设置剪切板数据,设置成功后 clipboardData 自动更新
setClipboardData({
  ...
});
1
2
3
4
5
6
7
8
9
10

UseClipboardData

useClipboardData 的组件版本。

vue
<script setup lang="ts">
import { UseClipboardData } from 'uni-app-use';
</script>

<template>
  <UseClipboardData v-slot="{ clipboardData }">
    <p>{{ clipboardData }}</p>
  </UseClipboardData>
</template>
1
2
3
4
5
6
7
8
9

useDeviceInfo

获取设备信息。

typescript
import { useDeviceInfo } from 'uni-app-use';

const deviceInfo = useDeviceInfo();
1
2
3

UseDeviceInfo

useDeviceInfo 的组件版本。

vue
<script setup lang="ts">
import { UseDeviceInfo } from 'uni-app-use';
</script>

<template>
  <UseDeviceInfo v-slot="{ ... }"> ... </UseDeviceInfo>
</template>
1
2
3
4
5
6
7

useDownloadFile

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

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

useEnterOptions

获取启动时的参数。

typescript
import { useEnterOptions } from 'uni-app-use';

const options = useEnterOptions();
1
2
3

useFile

获取文件相关。

typescript
import { useFile } from 'uni-app-use';

const {
  chooseFile,
  choose,
  chooseMessageFile,
  chooseMessage,
  saveFile,
  save,
  getSavedFileList,
  getSavedList,
  getSavedFileInfo,
  getSavedInfo,
  removeSavedFile,
  removeSaved,
  getFileInfo,
  getInfo,
  openDocument,
  open,
  fileSystemManager,
  manager,
  useFileSystemManager,
  useManager,
} = useFile();
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

useGlobalData

获取和设置当前应用实例的 globalData

typescript
import { useGlobalData } from 'uni-app-use';

const { globalData, setGlobalData } = useGlobalData();
1
2
3

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

typescript
setGlobalData({ a: 'a', b: 'b' });
1

你也可以直接设置某一个键值对。

typescript
setGlobalData('a', 'a');
1

UseGlobalData

useGlobalData 的组件版本。

vue
<script setup lang="ts">
import { UseGlobalData } from 'uni-app-use';
</script>

<template>
  <UseGlobalData v-slot="{ globalData, setGlobalData }">
    <p>{{ globalData }}</p>
  </UseGlobalData>
</template>
1
2
3
4
5
6
7
8
9

useImage

获取图片相关。

typescript
import { useImage } from 'uni-app-use';

const {
  chooseImage,
  choose,
  chooseMedia,
  previewImage,
  preview,
  closePreviewImage,
  closePreview,
  getImageInfo,
  getInfo,
  saveImageToPhotosAlbum,
  saveToPhotosAlbum,
  compressImage,
  compress,
} = useImage();
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

useImmer

https://cn.vuejs.org/guide/extras/reactivity-in-depth.html#immutable-data 的实现。另外暴露了 produce 方法。

typescript
import { useImmer } from 'uni-app-use';
const { state, update, produce } = useImmer(baseState);
1
2

updateproduce 的封装。

typescript
const update = (updater: (draft: D) => D) => (state.value = produce(state.value, updater));
1

你也可以直接使用 produce 来操作数据,见 immer 文档

useInterceptor

设置拦截器。

typescript
import { useInterceptor } from 'uni-app-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);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

useInvoice

获取发票相关。

typescript
import { useInvoice } from 'uni-app-use';

const { chooseInvoice, choose, chooseInvoiceTitle, chooseTitle } = useInvoice();
1
2
3

useLaunchOptions

获取启动时的参数。返回值与 onLaunch 的回调参数一致。

typescript
import { useLaunchOptions } from 'uni-app-use';

const options = useLaunchOptions();
1
2
3

useLoading

设置加载提示框参数,调用返回方法显示或隐藏加载提示框。

typescript
import { useLoading } from 'uni-app-use';

const { showLoading, hideLoading } = useLoading({
  /* 传入配置 */
});
showLoading(); // 实际显示加载提示框
hideLoading(); // 隐藏加载提示框
1
2
3
4
5
6
7

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

typescript
showLoading({
  /* 新传入配置 */
});
1
2
3

useLocation

获取位置相关。

typescript
import { useLocation } from 'uni-app-use';

const {
  getLocation,
  get,
  chooseLocation,
  choose,
  openLocation,
  open,
  onLocationChange,
  onChange,
  onLocationChangeError,
  onChangeError,
  offLocationChange,
  offChange,
  startLocationUpdate,
  startUpdate,
  startLocationBackgroundUpdate,
  startUpdateBackground,
  stopLocationUpdate,
  stopUpdate,
} = useLocation();
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

useMap

获取地图相关。

typescript
import { useMap } from 'uni-app-use';

const { createMapContext, createContext } = useMap();
1
2
3

useMenuButtonBoundingClientRect

获取胶囊按钮布局。

typescript
import { useMenuButtonBoundingClientRect } from 'uni-app-use';

const { menuButtonBoundingClientRect, rect } = useMenuButtonBoundingClientRect();
1
2
3

useModal

设置模态框参数,调用返回方法显示模态框。

typescript
import { useModal } from 'uni-app-use';

const showModal = useModal({
  /* 传入配置 */
});
showModal(); // 实际显示模态框
1
2
3
4
5
6

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

typescript
showModal({
  /* 新传入配置 */
});
1
2
3

useNavigationBar

获取导航条相关。

typescript
import { useNavigationBar } from 'uni-app-use';

const {
  setNavigationBarTitle,
  setTitle,
  setNavigationBarColor,
  setColor,
  showNavigationBarLoading,
  showLoading,
  hideNavigationBarLoading,
  hideLoading,
} = useNavigationBar();
1
2
3
4
5
6
7
8
9
10
11
12

useNetwork

获取网络信息。

typescript
import { useNetwork } from 'uni-app-use';

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

UseNetwork

useNetwork 的组件版本。

vue
<script setup lang="ts">
import { UseNetwork } from 'uni-app-use';
</script>

<template>
  <UseNetwork v-slot="{ type }">
    <p>type: {{ type }}</p>
  </UseNetwork>
</template>
1
2
3
4
5
6
7
8
9

useOnline

获取网络信息。

typescript
import { useOnline } from 'uni-app-use';

const isOnline = useOnline();
1
2
3

UseOnline

useOnline 的组件版本。

vue
<script setup lang="ts">
import { UseOnline } from 'uni-app-use';
</script>

<template>
  <UseOnline v-slot="{ isOnline }">
    <p>isOnline: {{ isOnline }}</p>
  </UseOnline>
</template>
1
2
3
4
5
6
7
8
9

usePage

获取当前展示页面信息。

typescript
import { usePage } from 'uni-app-use';

const page = usePage();
1
2
3

usePages

获取当前页面栈信息。

typescript
import { usePages } from 'uni-app-use';

const pages = usePages();
1
2
3

usePreferredDark

响应式的暗黑主题偏好。

typescript
import { usePreferredDark } from 'uni-app-use';

const prefersDark = usePreferredDark();
1
2
3

UsePreferredDark

usePreferredDark 的组件版本。

vue
<script setup lang="ts">
import { UsePreferredDark } from 'uni-app-use';
</script>

<template>
  <UsePreferredDark v-slot="{ prefersDark }">
    <p>{{ prefersDark }}</p>
  </UsePreferredDark>
</template>
1
2
3
4
5
6
7
8
9

usePreferredLanguage

响应式的语言偏好。

typescript
import { usePreferredLanguage } from 'uni-app-use';

const language = usePreferredLanguage();
1
2
3

UsePreferredLanguage

usePreferredLanguage 的组件版本。

vue
<script setup lang="ts">
import { UsePreferredLanguage } from 'uni-app-use';
</script>

<template>
  <UsePreferredLanguage v-slot="{ language }">
    <p>{{ language }}</p>
  </UsePreferredLanguage>
</template>
1
2
3
4
5
6
7
8
9

usePrevPage

获取当前展示页面的前一页面信息。

typescript
import { usePrevPage } from 'uni-app-use';

const prevPage = usePrevPage();
1
2
3

usePrevRoute

获取当前展示页面的前一页面路由路径信息。

typescript
import { usePrevRoute } from 'uni-app-use';

const prevRoute = usePrevRoute();
1
2
3

useProvider

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

typescript
import { useProvider } from 'uni-app-use';

const getProvider = getProvider({
  /* 传入配置 */
});
getProvider(); // 实际请求服务供应商
1
2
3
4
5
6

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

typescript
getProvider({
  /* 新传入配置 */
});
1
2
3

usePullDownRefresh

获取下拉刷新方法。

typescript
import { usePullDownRefresh } from 'uni-app-use';

const { startPullDownRefresh, start, stopPullDownRefresh, stop } = usePullDownRefresh();
1
2
3

useRecorder

获取录音相关。

typescript
import { useRecorder } from 'uni-app-use';

const { recorderManager, manager, useRecorderManager, useManager } = useRecorder();
1
2
3

useRequest

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

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

useRoute

获取当前展示页面的路由路径信息。

typescript
import { useRoute } from 'uni-app-use';

const route = useRoute();
1
2
3

useRouter

获取路由相关。

typescript
import { useRouter } from 'uni-app-use';

const {
  pages,
  page,
  prevPage,
  route,
  prevRoute,
  reLaunch,
  switchTab,
  redirectTo,
  navigateTo,
  navigateBack,
  navigateToMiniprogram,
  navigateBackMiniprogram,
} = useRouter();
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

useScanCode

设置扫码参数,调用返回方法调起客户端扫码界面。

typescript
import { useScanCode } from 'uni-app-use';

const scan = useScanCode({
  /* 传入配置 */
});
scan(); // 实际调起扫码
1
2
3
4
5
6

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

typescript
scan({
  /* 新传入配置 */
});
1
2
3

useScreenBrightness

获取和设置屏幕亮度。

typescript
import { useScreenBrightness } from 'uni-app-use';

const { screenBrightness, brightness, setScreenBrightness, setBrightness } = useScreenBrightness();

// 查看屏幕亮度
console.log('screenBrightness', screenBrightness);
console.log('brightness', brightness);
// 设置屏幕亮度,设置成功后自动更新
setScreenBrightness({
  ...
});
setBrightness({
  ...
});
1
2
3
4
5
6
7
8
9
10
11
12
13
14

UseScreenBrightness

useScreenBrightness 的组件版本。

vue
<script setup lang="ts">
import { UseScreenBrightness } from 'uni-app-use';
</script>

<template>
  <UseScreenBrightness v-slot="{ screenBrightness }">
    <p>{{ screenBrightness }}</p>
  </UseScreenBrightness>
</template>
1
2
3
4
5
6
7
8
9

useSelectorQuery

获取 SelectorQuery 实例。

typescript
import { useSelectorQuery } from 'uni-app-use';

const query = useSelectorQuery();
1
2
3

useSocket

uni-app 提供的 socket 操作的封装。

typescript
import { useSocket } from 'uni-app-use';

const { task, sendMessage, close, isConnecting, isConnected, isClosed, error } = useSocket({
  onSocketOpen,
  onSocketError,
  onSocketMessage,
  onSocketClose,
});
1
2
3
4
5
6
7
8

useStorage

获取存储方法。

typescript
import { useStorage } from 'uni-app-use';

const {
  getStorage,
  getStorageSync,
  get,
  getSync,
  setStorage,
  setStorageSync,
  set,
  setSync,
  removeStorage,
  removeStorageSync,
  remove,
  removeSync,
  clearStorage,
  clearStorageSync,
  clear,
  clearSync,
  getStorageInfo,
  getStorageInfoSync,
  getInfo,
  getInfoSync,
} = useStorage();
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

useSubscription

获取订阅相关。

typescript
import { useSubscription } from 'uni-app-use';

const { requestSubscribeMessage } = useSubscription();
1
2
3

useSupported

获取 API 是否被支持。

typescript
import { useSupported } from 'uni-app-use';

const isSupported = useSupported();
1
2
3

useSystemInfo

获取系统信息。

typescript
import { useSystemInfo } from 'uni-app-use';

const systemInfo = useSystemInfo();
1
2
3

UseSystemInfo

useSystemInfo 的组件版本。

vue
<script setup lang="ts">
import { UseSystemInfo } from 'uni-app-use';
</script>

<template>
  <UseSystemInfo v-slot="{ ... }"> ... </UseSystemInfo>
</template>
1
2
3
4
5
6
7

useSystemSetting

获取系统设置。

typescript
import { useSystemSetting } from 'uni-app-use';

const systemSetting = useSystemSetting();
1
2
3

useTabBar

获取标签栏操作。

typescript
import { useTabBar } from 'uni-app-use';

const {
  setTabBarItem,
  setItem,
  setTabBarStyle,
  setStyle,
  showTabBar,
  show,
  hideTabBar,
  hide,
  setTabBarBadge,
  setBadge,
  removeTabBarBadge,
  removeBadge,
  showTabBarRedDot,
  showRedDot,
  hideTabBarRedDot,
  hideRedDot,
} = useTabBar();
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

useToast

设置提示框参数,调用返回方法显示或隐藏提示框。

typescript
import { useToast } from 'uni-app-use';

const { showToast, hideToast } = useToast({
  /* 传入配置 */
});
showToast(); // 实际显示提示框
hideToast(); // 隐藏提示框
1
2
3
4
5
6
7

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

typescript
showToast({
  /* 新传入配置 */
});
1
2
3

useUniPlatform

获取运行应用时设置的 UNI_PLATFORM 值,默认为 h5

typescript
import { useUniPlatform } from 'uni-app-use';

const uniPlatform = useUniPlatform();
1
2
3

UseUniPlatform

useUniPlatform 的组件版本。

vue
<script setup lang="ts">
import { UseUniPlatform } from 'uni-app-use';
</script>

<template>
  <UseUniPlatform v-slot="{ uniPlatform }">
    <p>uniPlatform: {{ uniPlatform }}</p>
  </UseUniPlatform>
</template>
1
2
3
4
5
6
7
8
9

useUpdate

获取更新相关。

typescript
import { useUpdate } from 'uni-app-use';

const { updateManager, manager, useUpdateManager, useManager } = useUpdate();
1
2
3

useUploadFile

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

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

useUser

获取用户相关。

typescript
import { useUser } from 'uni-app-use';

const {
  login,
  checkSession,
  getUserInfo,
  getInfo,
  getUserProfile,
  getProfile,
  preLogin,
  closeAuthView,
  getCheckBoxState,
  univerifyManager,
  manager,
  useUniverifyManager,
  useManager,
} = useUser();
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

useVibrate

获取震动方法。

typescript
import { useVibrate } from 'uni-app-use';

const { vibrate, vibrateLong, vibrateShort } = useVibrate();
1
2
3

useVideo

获取视频相关。

typescript
import { useVideo } from 'uni-app-use';

const {
  createVideoContext,
  createContext,
  chooseVideo,
  choose,
  chooseMedia,
  saveVideoToPhotosAlbum,
  saveToPhotosAlbum,
  getVideoInfo,
  getInfo,
  compressVideo,
  compress,
  openVideoEditor,
  openEditor,
} = useVideo();
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

useVisible

获取当前页面显隐状态。

typescript
import { useVisible } from 'uni-app-use';

const isVisible = useVisible();
1
2
3

useWindowInfo

获取窗口信息。

typescript
import { useWindowInfo } from 'uni-app-use';

const windowInfo = useWindowInfo();
1
2
3

UseWindowInfo

useWindowInfo 的组件版本。

vue
<script setup lang="ts">
import { UseWindowInfo } from 'uni-app-use';
</script>

<template>
  <UseWindowInfo v-slot="{ ... }"> ... </UseWindowInfo>
</template>
1
2
3
4
5
6
7

其它

限制

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

  • 缺失某些全局变量(如 windownavigator 等)
  • 必须使用 uni-app 提供的 API 实现功能(如拦截器、存储等),API 不支持的也就无法支持(比如拦截同步 API)
  • 无法使用顶层 await

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

构建

对于 vue-cli,请修改项目根目录 vue.config.js 如下所示。

typescript
module.exports = {
  transpileDependencies: ['uni-app-use'],
};
1
2
3

对于 vite,你无需手动额外调整。

EventBus

如果你想使用 EventBus,请考虑使用 VueUse - useEventBusmitttiny-emitter。这个库不再重复提供类似功能。

TypeScript

uni-app-use 本身使用 TypeScript 开发,拥有类型提示。

资源

致谢

Released under the MIT License.