@uni-helper/uni-use
uni-app (vue3)
组合式工具集。要求 node>=18
。
-
@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
- 其它
- 资源
- 致谢
安装依赖
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 开发,拥有类型提示。