更新记录
1.1.5(2025-07-09) 下载此版本
1
1.1.4(2025-07-01) 下载此版本
优化
1.1.3(2025-07-01) 下载此版本
优化
查看更多平台兼容性
uni-app
Vue2 | Vue3 | Chrome | Safari | app-vue | app-nvue | Android | iOS | 鸿蒙 |
---|---|---|---|---|---|---|---|---|
√ | √ | √ | √ | √ | √ | - | - | - |
微信小程序 | 支付宝小程序 | 抖音小程序 | 百度小程序 | 快手小程序 | 京东小程序 | 鸿蒙元服务 | QQ小程序 | 飞书小程序 | 快应用-华为 | 快应用-联盟 |
---|---|---|---|---|---|---|---|---|---|---|
√ | √ | √ | √ | √ | √ | - | √ | √ | √ | √ |
其他
多语言 | 暗黑模式 | 宽屏模式 |
---|---|---|
× | × | √ |
工具库使用说明
工具库,支持微信小程序、支付宝小程序、APP 和 H5 平台。
目录结构
/uni_modules/x-tools/tools/
├── index.js # 主入口文件,通用工具函数
├── sugar.js # 语法糖,简化常用操作
├── router.js # 路由导航工具
├── h5Utils.js # H5 平台专用工具
├── appletUtils.js # 小程序专用工具
├── cacheFile.js # 文件缓存管理
├── codeUtil.js # 二维码/条码处理工具
└── com.js # 组件通用属性和工具
使用方式
导入方式
// 按需导入
import { sleep, deepClone, countDown } from '@/uni_modules/x-tools/tools/index.js'
import { toast, copy, saveImage } from '@/uni_modules/x-tools/tools/sugar.js'
import { navTo, navBack } from '@/uni_modules/x-tools/tools/router.js'
主要功能模块
1. 通用工具函数 (index.js)
基础工具
// 类型判断
const type = _typeof([1, 2, 3]) // 'array'
const type2 = _typeof('hello') // 'string'
// Promise 判断
const isPromise = isPromise(fetch('/api'))
// 休眠函数
await sleep(1000) // 延迟 1 秒
// 深拷贝
const newObj = deepClone(originalObj)
页面信息获取
// 获取当前页面路径
const currentPath = getCurrentPagePath() // '/pages/index/index'
const fullPath = getCurrentPagePath(true) // '/pages/index/index?id=123'
// 判断是否为 tabBar 页面
const isTabBar = isTabBarPage()
const isSpecificTabBar = isTabBarPage('/pages/home/home')
// 获取页面运行信息
const pageInfo = getPageInfo()
// 返回: { startPage, isSharePage, pageStackLen }
倒计时功能
// 基本用法
const timerId = countDown('2024-12-31 23:59:59', (info, isEnd) => {
console.log(info.str) // "12:30:45"
if (isEnd) {
console.log('倒计时结束')
}
})
// 自定义格式
countDown(endTime, callback, 'dd天hh时mm分ss秒')
// 停止倒计时
clearInterval(timerId)
轮询功能
// 轮询等待结果
const result = await pollingForResult(
apiFunction, // 要轮询的函数
[param1, param2], // 参数数组
(res) => { // 判断函数
if (res.status === 'success') return 'success'
if (res.status === 'failed') return 'fail'
// 返回其他值继续轮询
},
1000, // 轮询间隔(ms)
60000 // 超时时间(ms)
)
// 轮询获取数据
const stopPolling = pollingForData(
apiFunction,
[params],
(err, res, count) => {
if (err) {
console.log('第', count, '次请求失败:', err)
} else {
console.log('第', count, '次请求成功:', res)
}
},
1000 // 轮询间隔
)
// 停止轮询
stopPolling()
2. 语法糖工具 (sugar.js)
基础操作简化
// 日志输出
log('hello world') // console.log 的简写
// 单位转换
const pxValue = upx2px(750) // rpx 转 px
// 消息提示
toast('操作成功')
toast('错误信息', { icon: 'error', duration: 3000 })
// 拨打电话
makePhoneCall('***')
// 图片预览
previewImage(['url1', 'url2'], 'url1')
// 复制到剪贴板
copy('要复制的文本')
// 打开地图
openMap(116.404, 39.915, '天安门', '北京市东城区')
// 本地存储
setStorage('key', 'value')
数据验证
// 判断空值
isEmpty('') // true
isEmpty([]) // true
isEmpty({}) // true
isEmpty(null) // true
isEmpty('hello') // false
// 检查对象是否有空字段
const user = { name: 'Tom', age: '', email: 'tom@example.com' }
const emptyField = hasEmptyField(user) // 'age'
// 排除某些字段检查
const emptyField2 = hasEmptyField(user, ['age']) // null
数据处理
// 数据脱敏
dataMask('***', 3, 4) // '138****8000'
dataMask('张三丰', 1, 1) // '张*丰'
// 对象转查询字符串
object2queryStr({ name: 'Tom', age: 18 }) // '?name=Tom&age=18'
// HTML 转纯文本
html2text('<p>Hello <b>World</b></p>') // 'Hello World'
平台特定功能
// 保存图片
await saveImage('https://example.com/image.jpg')
await saveImage(localImagePath, false) // 不显示提示
// 跳转企业微信客服
toCustomerService('corpId', 'https://service-url')
// 查询元素信息 (在组件中使用)
const rect = await queryElementRect.call(this, '.my-element')
3. 路由导航 (router.js)
基础导航
// 保留当前页面,跳转到应用内的某个页面
navTo('/pages/detail/detail?id=123')
navTo('/pages/detail/detail', { fail: console.log }, 1000) // 延迟 1 秒
// 关闭当前页面,跳转到应用内的某个页面
redTo('/pages/login/login')
// 关闭所有页面,打开到应用内的某个页面
clearTo('/pages/home/home')
// 跳转到 tabBar 页面
tabTo('/pages/home/home')
shTab('/pages/profile/profile') // tabTo 的别名
// 返回上一页
navBack()
navBack(1000, 2) // 延迟 1 秒,返回 2 级页面
页面间数据传递
// 跳转并传递数据
const result = await navToAndEvent(
'/pages/select/select',
{ list: [1, 2, 3] }, // 传递给目标页面的数据
(data) => { // 接收返回数据的回调
console.log('返回数据:', data)
}
)
// 在目标页面接收数据 (Vue2)
onLoad() {
const eventChannel = this.getOpenerEventChannel()
eventChannel.on('navData', (data) => {
console.log('接收到数据:', data)
})
}
// 在目标页面返回数据
const eventChannel = this.getOpenerEventChannel()
navBackAndEvent(eventChannel, { selected: 'item1' })
4. H5 工具 (h5Utils.js)
开发调试
// 加载在线调试工具
await debug() // 加载 eruda 调试工具
URL 处理
// 获取查询参数
const params = getQueryParams() // 当前页面参数
const params2 = getQueryParams('https://example.com?name=Tom&age=18')
// 返回: { name: 'Tom', age: '18' }
// 判断浏览器环境
const browser = judgeBrowser() // 'wx' | 'ali' | 'unknown'
脚本加载
// 动态加载 JavaScript
await loadScript('https://cdn.example.com/lib.js')
微信公众号开发
// 授权获取 code
getWxAuthCode('appId', 'state', 'snsapi_userinfo')
// 配置微信 JS-SDK
wxConfig({
appId: 'your-app-id',
timestamp: 1234567890,
noncestr: 'random-string',
signature: 'signature'
})
// 微信支付
try {
const result = await wxPay(paymentParams)
console.log('支付成功')
} catch (error) {
console.log('支付失败或取消')
}
// 设置分享信息
wxShare({
title: '分享标题',
desc: '分享描述',
imgUrl: 'https://example.com/share.jpg',
link: 'https://example.com/page'
})
支付宝生活号开发
// 授权获取 code
try {
const result = await getAliAuthCode('appId', 'auth_user')
console.log('授权成功:', result.authCode)
} catch (error) {
console.log('授权失败')
}
// 支付宝支付
try {
const result = await aliPay('tradeNo123456')
console.log('支付成功')
} catch (error) {
console.log('支付失败')
}
5. 小程序工具 (appletUtils.js)
视频号直播
// 跳转到视频号直播 (仅微信小程序)
toChannelsLive('finderUserName')
分享参数处理
// 获取小程序分享参数
const shareParams = getWxShareParams(
{ custom: 'param' }, // 自定义参数
'分享标题',
'https://example.com/share.jpg',
'/pages/share/share'
)
// 返回: { title, path, imageUrl }
场景参数获取
// 获取小程序场景参数 (扫码进入等)
const sceneParams = getSceneParams()
6. 文件缓存管理 (cacheFile.js)
import { cacheFile } from '@/utils/cacheFile'
// 通过 URL 获取本地文件路径 (自动下载并缓存)
const localPath = await cacheFile.getFilePathByUrl('https://example.com/image.jpg')
7. 二维码/条码工具 (codeUtil.js)
import { CodeUtil } from '@/utils/codeUtil'
// 初始化,定义支持的码类型
const codeUtil = new CodeUtil(['user', 'product', 'coupon'])
// 扫码
const result = await codeUtil.scan()
// 扫码并解析
const codeInfo = await codeUtil.getCodeInfo()
// 返回: { type: 'user', content: { id: 123 } }
// 生成码内容
const codeData = codeUtil.makeCode('user', { id: 123, name: 'Tom' })
8. 组件工具 (com.js)
// 通用组件属性
export const commonProps = {
bgColor: {
type: String,
default: '#fff'
},
customStyle: {
type: Object,
default: () => ({})
}
}
// 字符串转像素值
const pxValue = str2px('750rpx') // 转换为对应的 px 值
const pxValue2 = str2px('100px') // 100
const pxValue3 = str2px('50') // 50
Vue2 兼容性
库中包含了 Vue2 的兼容性处理:
// 在 main.js 中调用,让 uni API Vue2 支持 Promise
promisify()
// 获取页面通信管道 (Vue2)
const eventChannel = pageEvent.call(this)
注意事项
- 平台兼容性: 某些功能仅在特定平台可用,调用前请检查平台支持
- 权限申请: 保存图片、拨打电话等功能需要相应权限
- 网络请求: 文件下载、图片保存等功能需要网络权限
- 错误处理: 大部分异步操作都包含了错误处理,但建议在业务代码中也加上 try-catch
示例项目结构
// main.js
import { promisify } from '@/uni_modules/x-tools/tools/index.js'
promisify() // Vue2 项目中启用
// pages/index.vue
import { toast, copy } from '@/uni_modules/x-tools/tools/sugar.js'
import { navTo } from '@/uni_modules/x-tools/tools/router.js'
import { countDown } from '@/uni_modules/x-tools/tools/index.js'
export default {
onLoad() {
// 开始倒计时
this.timerId = countDown('2024-12-31 23:59:59', (info) => {
this.countdownText = info.str
})
},
methods: {
handleCopy() {
copy('复制内容')
toast('已复制')
},
handleNavigation() {
navTo('/pages/detail/detail?id=123')
}
}
}