[DEPRECATED] uni-app-use
该依赖已废弃,请迁移到功能一致的 @uni-helper/uni-use。
uni-app (vue3)
组合式工具集。
安装
使用 npm
:
npm install uni-app-use @vueuse/core
使用 yarn
:
yarn install uni-app-use @vueuse/core
使用 pnpm
:
pnpm install uni-app-use @vueuse/core
使用 cnpm
:
cnpm install uni-app-use @vueuse/core
目前只考虑小程序和移动应用环境。不考虑支持 uni_modules
。
使用
tryOnHide
安全的 onHide
。如果是在组件生命周期内,就调用 onHide()
;如果不是,就直接调用函数。
import { tryOnHide } from 'uni-app-use'
tryOnHide(() => {
...
});
2
3
4
5
tryOnInit
安全的 onInit
。如果是在组件生命周期内,就调用 onInit()
;如果不是,就直接调用函数。
import { tryOnInit } from 'uni-app-use'
tryOnInit(() => {
...
});
2
3
4
5
tryOnLoad
安全的 onLoad
。如果是在组件生命周期内,就调用 onLoad()
;如果不是,就直接调用函数。
import { tryOnLoad } from 'uni-app-use'
tryOnLoad(() => {
...
});
2
3
4
5
tryOnReady
安全的 onReady
。如果是在组件生命周期内,就调用 onReady()
;如果不是,就直接调用函数。
import { tryOnReady } from 'uni-app-use'
tryOnReady(() => {
...
});
2
3
4
5
tryOnShow
安全的 onShow
。如果是在组件生命周期内,就调用 onShow()
;如果不是,就直接调用函数。
import { tryOnShow } from 'uni-app-use'
tryOnShow(() => {
...
});
2
3
4
5
tryOnUnload
安全的 onUnload
。如果是在组件生命周期内,就调用 onUnload()
;如果不是,就直接调用函数。
import { tryOnUnload } from 'uni-app-use'
tryOnUnload(() => {
...
});
2
3
4
5
useAccountInfo
获取当前账号信息。
import { useAccountInfo } from 'uni-app-use';
const accountInfo = useAccountInfo();
2
3
useActionSheet
设置菜单列表参数,调用返回方法显示菜单列表。
import { useActionSheet } from 'uni-app-use';
const showActionSheet = useActionSheet({
/* 传入配置 */
});
showActionSheet(); // 实际显示菜单列表
2
3
4
5
6
可以传入一个对象来更新已有配置,这样会使用 扩展运算符 来确认最终配置。
showActionSheet({
/* 新传入配置 */
});
2
3
useAddress
获取地址相关。
import { useAddress } from 'uni-app-use';
const { chooseAddress, choose } = useAddress();
2
3
useApp
获取当前应用实例。如果想要获取 globalData
,可以直接使用 useGlobalData
。
import { useApp } from 'uni-app-use';
const app = useApp();
2
3
useAppBaseInfo
获取应用基础信息。
import { useAppBaseInfo } from 'uni-app-use';
const appBaseInfo = useAppBaseInfo();
2
3
UseAppBaseInfo
useAppBaseInfo
的组件版本。
<script setup lang="ts">
import { UseAppBaseInfo } from 'uni-app-use';
</script>
<template>
<UseAppBaseInfo v-slot="{ ... }"> ... </UseAppBaseInfo>
</template>
2
3
4
5
6
7
useArrayBufferToBase64
获取 ArrayBuffer 对应的 base64。可以直接传入 ref
。
import { useArrayBufferToBase64 } from 'uni-app-use';
const base64 = useArrayBufferToBase64(arrayBuffer);
2
3
useAudio
获取音频相关。
import { useAudio } from 'uni-app-use';
const {
backgroundAudioManager,
backgroundManager,
useBackgroundAudioManager,
useBackgroundManager,
createInnerAudioContext,
createInnerContext,
} = useAudio();
2
3
4
5
6
7
8
9
10
useAuthorize
获取授权相关。
import { useAuthorize } from 'uni-app-use';
const { authorize, openSetting, getSetting, openAppAuthorizeSetting, getAppAuthorizeSetting } =
useAuthorize();
2
3
4
useBackground
获取背景设置方法。
import { useBackground } from 'uni-app-use';
const { setBackgroundColor, setColor, setBackgroundTextStyle, setTextStyle } = useBackground();
2
3
useBase64ToArrayBuffer
获取 base64 对应的 ArrayBuffer。可以直接传入 ref
。
import { useBase64ToArrayBuffer } from 'uni-app-use';
const arrayBuffer = useBase64ToArrayBuffer(base64);
2
3
useCamera
获取相机相关。
import { useCamera } from 'uni-app-use';
const { createCameraContext, createContext } = useCamera();
2
3
useClipboardData
获取和设置剪切板数据。
import { useClipboardData } from 'uni-app-use';
const { clipboardData, setClipboardData } = useClipboardData();
// 查看剪切板数据
console.log('clipboardData', clipboardData);
// 设置剪切板数据,设置成功后 clipboardData 自动更新
setClipboardData({
...
});
2
3
4
5
6
7
8
9
10
UseClipboardData
useClipboardData
的组件版本。
<script setup lang="ts">
import { UseClipboardData } from 'uni-app-use';
</script>
<template>
<UseClipboardData v-slot="{ clipboardData }">
<p>{{ clipboardData }}</p>
</UseClipboardData>
</template>
2
3
4
5
6
7
8
9
useDeviceInfo
获取设备信息。
import { useDeviceInfo } from 'uni-app-use';
const deviceInfo = useDeviceInfo();
2
3
UseDeviceInfo
useDeviceInfo
的组件版本。
<script setup lang="ts">
import { UseDeviceInfo } from 'uni-app-use';
</script>
<template>
<UseDeviceInfo v-slot="{ ... }"> ... </UseDeviceInfo>
</template>
2
3
4
5
6
7
useDownloadFile
uni.downloadFile
的封装。使用方法参见 https://vueuse.org/integrations/useAxios/。
返回值中含有 task,可自行操作。
useEnterOptions
获取启动时的参数。
import { useEnterOptions } from 'uni-app-use';
const options = useEnterOptions();
2
3
useFile
获取文件相关。
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();
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
。
import { useGlobalData } from 'uni-app-use';
const { globalData, setGlobalData } = useGlobalData();
2
3
可以传入一个对象来更新已有配置,这样会使用 扩展运算符 来确认最终配置。
setGlobalData({ a: 'a', b: 'b' });
你也可以直接设置某一个键值对。
setGlobalData('a', 'a');
UseGlobalData
useGlobalData
的组件版本。
<script setup lang="ts">
import { UseGlobalData } from 'uni-app-use';
</script>
<template>
<UseGlobalData v-slot="{ globalData, setGlobalData }">
<p>{{ globalData }}</p>
</UseGlobalData>
</template>
2
3
4
5
6
7
8
9
useImage
获取图片相关。
import { useImage } from 'uni-app-use';
const {
chooseImage,
choose,
chooseMedia,
previewImage,
preview,
closePreviewImage,
closePreview,
getImageInfo,
getInfo,
saveImageToPhotosAlbum,
saveToPhotosAlbum,
compressImage,
compress,
} = useImage();
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
方法。
import { useImmer } from 'uni-app-use';
const { state, update, produce } = useImmer(baseState);
2
update
是 produce
的封装。
const update = (updater: (draft: D) => D) => (state.value = produce(state.value, updater));
你也可以直接使用 produce
来操作数据,见 immer 文档。
useInterceptor
设置拦截器。
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);
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
useInvoice
获取发票相关。
import { useInvoice } from 'uni-app-use';
const { chooseInvoice, choose, chooseInvoiceTitle, chooseTitle } = useInvoice();
2
3
useLaunchOptions
获取启动时的参数。返回值与 onLaunch
的回调参数一致。
import { useLaunchOptions } from 'uni-app-use';
const options = useLaunchOptions();
2
3
useLoading
设置加载提示框参数,调用返回方法显示或隐藏加载提示框。
import { useLoading } from 'uni-app-use';
const { showLoading, hideLoading } = useLoading({
/* 传入配置 */
});
showLoading(); // 实际显示加载提示框
hideLoading(); // 隐藏加载提示框
2
3
4
5
6
7
可以传入一个对象来更新已有配置,这样会使用 扩展运算符 来确认最终配置。
showLoading({
/* 新传入配置 */
});
2
3
useLocation
获取位置相关。
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();
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
useMap
获取地图相关。
import { useMap } from 'uni-app-use';
const { createMapContext, createContext } = useMap();
2
3
useMenuButtonBoundingClientRect
获取胶囊按钮布局。
import { useMenuButtonBoundingClientRect } from 'uni-app-use';
const { menuButtonBoundingClientRect, rect } = useMenuButtonBoundingClientRect();
2
3
useModal
设置模态框参数,调用返回方法显示模态框。
import { useModal } from 'uni-app-use';
const showModal = useModal({
/* 传入配置 */
});
showModal(); // 实际显示模态框
2
3
4
5
6
可以传入一个对象来更新已有配置,这样会使用 扩展运算符 来确认最终配置。
showModal({
/* 新传入配置 */
});
2
3
useNavigationBar
获取导航条相关。
import { useNavigationBar } from 'uni-app-use';
const {
setNavigationBarTitle,
setTitle,
setNavigationBarColor,
setColor,
showNavigationBarLoading,
showLoading,
hideNavigationBarLoading,
hideLoading,
} = useNavigationBar();
2
3
4
5
6
7
8
9
10
11
12
useNetwork
获取网络信息。
import { useNetwork } from 'uni-app-use';
const { type, isWifi, is2g, is3g, is4g, is5g, isEthernet, isUnknown, isOnline, isOffline } =
useNetwork();
2
3
4
UseNetwork
useNetwork
的组件版本。
<script setup lang="ts">
import { UseNetwork } from 'uni-app-use';
</script>
<template>
<UseNetwork v-slot="{ type }">
<p>type: {{ type }}</p>
</UseNetwork>
</template>
2
3
4
5
6
7
8
9
useOnline
获取网络信息。
import { useOnline } from 'uni-app-use';
const isOnline = useOnline();
2
3
UseOnline
useOnline
的组件版本。
<script setup lang="ts">
import { UseOnline } from 'uni-app-use';
</script>
<template>
<UseOnline v-slot="{ isOnline }">
<p>isOnline: {{ isOnline }}</p>
</UseOnline>
</template>
2
3
4
5
6
7
8
9
usePage
获取当前展示页面信息。
import { usePage } from 'uni-app-use';
const page = usePage();
2
3
usePages
获取当前页面栈信息。
import { usePages } from 'uni-app-use';
const pages = usePages();
2
3
usePreferredDark
响应式的暗黑主题偏好。
import { usePreferredDark } from 'uni-app-use';
const prefersDark = usePreferredDark();
2
3
UsePreferredDark
usePreferredDark
的组件版本。
<script setup lang="ts">
import { UsePreferredDark } from 'uni-app-use';
</script>
<template>
<UsePreferredDark v-slot="{ prefersDark }">
<p>{{ prefersDark }}</p>
</UsePreferredDark>
</template>
2
3
4
5
6
7
8
9
usePreferredLanguage
响应式的语言偏好。
import { usePreferredLanguage } from 'uni-app-use';
const language = usePreferredLanguage();
2
3
UsePreferredLanguage
usePreferredLanguage
的组件版本。
<script setup lang="ts">
import { UsePreferredLanguage } from 'uni-app-use';
</script>
<template>
<UsePreferredLanguage v-slot="{ language }">
<p>{{ language }}</p>
</UsePreferredLanguage>
</template>
2
3
4
5
6
7
8
9
usePrevPage
获取当前展示页面的前一页面信息。
import { usePrevPage } from 'uni-app-use';
const prevPage = usePrevPage();
2
3
usePrevRoute
获取当前展示页面的前一页面路由路径信息。
import { usePrevRoute } from 'uni-app-use';
const prevRoute = usePrevRoute();
2
3
useProvider
设置服务供应商参数,调用返回方法获取服务供应商。
import { useProvider } from 'uni-app-use';
const getProvider = getProvider({
/* 传入配置 */
});
getProvider(); // 实际请求服务供应商
2
3
4
5
6
可以传入一个对象来更新已有配置,这样会使用 扩展运算符 来确认最终配置。
getProvider({
/* 新传入配置 */
});
2
3
usePullDownRefresh
获取下拉刷新方法。
import { usePullDownRefresh } from 'uni-app-use';
const { startPullDownRefresh, start, stopPullDownRefresh, stop } = usePullDownRefresh();
2
3
useRecorder
获取录音相关。
import { useRecorder } from 'uni-app-use';
const { recorderManager, manager, useRecorderManager, useManager } = useRecorder();
2
3
useRequest
uni.request
的封装。使用方法参见 https://vueuse.org/integrations/useAxios/。
返回值中含有 task,可自行操作。
useRoute
获取当前展示页面的路由路径信息。
import { useRoute } from 'uni-app-use';
const route = useRoute();
2
3
useRouter
获取路由相关。
import { useRouter } from 'uni-app-use';
const {
pages,
page,
prevPage,
route,
prevRoute,
reLaunch,
switchTab,
redirectTo,
navigateTo,
navigateBack,
navigateToMiniprogram,
navigateBackMiniprogram,
} = useRouter();
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
useScanCode
设置扫码参数,调用返回方法调起客户端扫码界面。
import { useScanCode } from 'uni-app-use';
const scan = useScanCode({
/* 传入配置 */
});
scan(); // 实际调起扫码
2
3
4
5
6
可以传入一个对象来更新已有配置,这样会使用 扩展运算符 来确认最终配置。
scan({
/* 新传入配置 */
});
2
3
useScreenBrightness
获取和设置屏幕亮度。
import { useScreenBrightness } from 'uni-app-use';
const { screenBrightness, brightness, setScreenBrightness, setBrightness } = useScreenBrightness();
// 查看屏幕亮度
console.log('screenBrightness', screenBrightness);
console.log('brightness', brightness);
// 设置屏幕亮度,设置成功后自动更新
setScreenBrightness({
...
});
setBrightness({
...
});
2
3
4
5
6
7
8
9
10
11
12
13
14
UseScreenBrightness
useScreenBrightness
的组件版本。
<script setup lang="ts">
import { UseScreenBrightness } from 'uni-app-use';
</script>
<template>
<UseScreenBrightness v-slot="{ screenBrightness }">
<p>{{ screenBrightness }}</p>
</UseScreenBrightness>
</template>
2
3
4
5
6
7
8
9
useSelectorQuery
获取 SelectorQuery
实例。
import { useSelectorQuery } from 'uni-app-use';
const query = useSelectorQuery();
2
3
useSocket
uni-app
提供的 socket
操作的封装。
import { useSocket } from 'uni-app-use';
const { task, sendMessage, close, isConnecting, isConnected, isClosed, error } = useSocket({
onSocketOpen,
onSocketError,
onSocketMessage,
onSocketClose,
});
2
3
4
5
6
7
8
task
: https://uniapp.dcloud.net.cn/api/request/socket-task.htmlsendMessage
: https://uniapp.dcloud.net.cn/api/request/websocket.html#sendsocketmessageclose
: https://uniapp.dcloud.net.cn/api/request/websocket.html#closesocketisConnecting
:socket
是否连接中isConnected
:socket
是否已经连接isClosed
:socket
是否已关闭error
: 使用socket
期间的错误onSocketOpen
: https://uniapp.dcloud.net.cn/api/request/websocket.html#onsocketopenonSocketError
: https://uniapp.dcloud.net.cn/api/request/websocket.html#onsocketerroronSocketMessage
: https://uniapp.dcloud.net.cn/api/request/websocket.html#onsocketmessageonSocketClose
: https://uniapp.dcloud.net.cn/api/request/websocket.html#onsocketclose
useStorage
获取存储方法。
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();
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
useSubscription
获取订阅相关。
import { useSubscription } from 'uni-app-use';
const { requestSubscribeMessage } = useSubscription();
2
3
useSupported
获取 API 是否被支持。
import { useSupported } from 'uni-app-use';
const isSupported = useSupported();
2
3
useSystemInfo
获取系统信息。
import { useSystemInfo } from 'uni-app-use';
const systemInfo = useSystemInfo();
2
3
UseSystemInfo
useSystemInfo
的组件版本。
<script setup lang="ts">
import { UseSystemInfo } from 'uni-app-use';
</script>
<template>
<UseSystemInfo v-slot="{ ... }"> ... </UseSystemInfo>
</template>
2
3
4
5
6
7
useSystemSetting
获取系统设置。
import { useSystemSetting } from 'uni-app-use';
const systemSetting = useSystemSetting();
2
3
useTabBar
获取标签栏操作。
import { useTabBar } from 'uni-app-use';
const {
setTabBarItem,
setItem,
setTabBarStyle,
setStyle,
showTabBar,
show,
hideTabBar,
hide,
setTabBarBadge,
setBadge,
removeTabBarBadge,
removeBadge,
showTabBarRedDot,
showRedDot,
hideTabBarRedDot,
hideRedDot,
} = useTabBar();
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
useToast
设置提示框参数,调用返回方法显示或隐藏提示框。
import { useToast } from 'uni-app-use';
const { showToast, hideToast } = useToast({
/* 传入配置 */
});
showToast(); // 实际显示提示框
hideToast(); // 隐藏提示框
2
3
4
5
6
7
可以传入一个对象来更新已有配置,这样会使用 扩展运算符 来确认最终配置。
showToast({
/* 新传入配置 */
});
2
3
useUniPlatform
获取运行应用时设置的 UNI_PLATFORM
值,默认为 h5
。
import { useUniPlatform } from 'uni-app-use';
const uniPlatform = useUniPlatform();
2
3
UseUniPlatform
useUniPlatform
的组件版本。
<script setup lang="ts">
import { UseUniPlatform } from 'uni-app-use';
</script>
<template>
<UseUniPlatform v-slot="{ uniPlatform }">
<p>uniPlatform: {{ uniPlatform }}</p>
</UseUniPlatform>
</template>
2
3
4
5
6
7
8
9
useUpdate
获取更新相关。
import { useUpdate } from 'uni-app-use';
const { updateManager, manager, useUpdateManager, useManager } = useUpdate();
2
3
useUploadFile
uni.uploadFile
的封装。使用方法参见 https://vueuse.org/integrations/useAxios/。
返回值中含有 task,可自行操作。
useUser
获取用户相关。
import { useUser } from 'uni-app-use';
const {
login,
checkSession,
getUserInfo,
getInfo,
getUserProfile,
getProfile,
preLogin,
closeAuthView,
getCheckBoxState,
univerifyManager,
manager,
useUniverifyManager,
useManager,
} = useUser();
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
useVibrate
获取震动方法。
import { useVibrate } from 'uni-app-use';
const { vibrate, vibrateLong, vibrateShort } = useVibrate();
2
3
useVideo
获取视频相关。
import { useVideo } from 'uni-app-use';
const {
createVideoContext,
createContext,
chooseVideo,
choose,
chooseMedia,
saveVideoToPhotosAlbum,
saveToPhotosAlbum,
getVideoInfo,
getInfo,
compressVideo,
compress,
openVideoEditor,
openEditor,
} = useVideo();
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
useVisible
获取当前页面显隐状态。
import { useVisible } from 'uni-app-use';
const isVisible = useVisible();
2
3
useWindowInfo
获取窗口信息。
import { useWindowInfo } from 'uni-app-use';
const windowInfo = useWindowInfo();
2
3
UseWindowInfo
useWindowInfo
的组件版本。
<script setup lang="ts">
import { UseWindowInfo } from 'uni-app-use';
</script>
<template>
<UseWindowInfo v-slot="{ ... }"> ... </UseWindowInfo>
</template>
2
3
4
5
6
7
其它
限制
在小程序和移动应用环境下有如下无法避开的限制:
- 缺失某些全局变量(如
window
、navigator
等) - 必须使用
uni-app
提供的 API 实现功能(如拦截器、存储等),API 不支持的也就无法支持(比如拦截同步 API) - 无法使用顶层
await
在开发网页时,建议直接使用 vue
,避免过多的环境判断代码,同时也能享受更好的生态,如 vueuse
的完整支持。
构建
对于 vue-cli
,请修改项目根目录 vue.config.js
如下所示。
module.exports = {
transpileDependencies: ['uni-app-use'],
};
2
3
对于 vite
,你无需手动额外调整。
EventBus
如果你想使用 EventBus
,请考虑使用 VueUse - useEventBus、mitt 或 tiny-emitter。这个库不再重复提供类似功能。
TypeScript
uni-app-use
本身使用 TypeScript 开发,拥有类型提示。