gypsy-crm-frontend-vu/uni_modules/x-tools

# x-tools 工具库使用文档

x-tools 是基于 uni-app 打造的通用工具集合，覆盖通用工具函数、界面语法糖、路由导航、H5 与小程序专用能力等常见场景。所有模块均可单独按需引入，也可以通过主入口统一管理，帮助你在跨端项目中快速复用能力。

支持平台

• 微信小程序
• 支付宝小程序
• App（uni-app 运行时）
• H5 / Web

具体 API 是否可用需参考 uni-app 官方文档及平台限制，文档中带有 #ifdef 注释的能力仅在对应平台有效。

快速开始

1. 确保工程已经安装并同步 uni_modules/x-tools 模块。
2. 在需要的页面或模块中引入工具函数：

import { promisify, countDown } from "@/uni_modules/x-tools/tools/index.js"
import { toast } from "@/uni_modules/x-tools/tools/sugar.js"

1. 对于 Vue2 项目，请在入口文件执行 promisify() 以启用 Promise 化支持。

模块总览

模块	文件路径	主要能力
通用工具	tools/index.js	Promise 包装、类型判断、页面信息、倒计时、轮询、深拷贝等
语法糖	tools/sugar.js	日志、提示、剪贴板、地图、客服、图片保存、表单校验等
路由导航	tools/router.js	路由跳转、事件通道数据透传、延时跳转
H5 专用	tools/h5Utils.js	调试面板、URL 参数、公众号与生活号授权及支付
小程序专用	tools/appletUtils.js	视频号直跳、微信分享参数、场景值解析
异步重试	tools/retryAsync.js	支持退避策略的 Promise 重试工具
码工具	tools/codeUtil.js	扫码、编码与解码工具类
组件辅助	tools/com.js	通用组件属性定义、尺寸转换

通用工具（tools/index.js）

主入口导出了常用函数，并将其他工具模块聚合到命名空间中：

import * as tools from "@/uni_modules/x-tools/tools/index.js"

const { sugar, router, h5Utils, appletUtils } = tools

基础能力

• promisify()：在 Vue2 项目中调用后，可让内置 uni API 返回 Promise，便于 async/await 调用。
• isPromise(obj)：判断目标是否符合 Promise 接口，常用于链式调用的防御性编程。
• _typeof(value)：返回更精确的类型字符串（如 array、date、set）。
• sleep(ms)：返回在指定毫秒后 resolve 的 Promise，用于节流、动画等待等场景。
• deepClone(target, map?)：支持 Map、Set、Symbol 等复杂结构的深拷贝工具，自动处理循环引用。

页面辅助

• getCurrentPage()：获取当前页面实例，等价于 getCurrentPages().slice(-1)[0]。
• getCurrentPagePath(fullPath = false)：返回当前页面路径，可选包含 query。
• isTabBarPage(path?)：判断当前页面或指定路径是否在 pages.json 的 tabBar 配置中。
• getPageInfo()：返回 { currentPage, startPage, isSharePage, pageStackLen }，用于埋点与分享判断。

计时与轮询

• countDown(endTime, callback, formatStr = "hh:mm:ss", refreshRate = 100)：基于毫秒级刷新倒计时，callback(info, isEnd) 中的 info 带有格式化文本及 d/h/m/s 数据。
• pollingForResult(fun, params, judgeFun, ms = 1000, timeout = 60000)：轮询异步函数直到 judgeFun 返回 success 或 fail。
• pollingForData(fun, params, callback, ms = 1000)：持续轮询并在每次调用后触发回调，返回的函数可立即停止轮询。

const timer = countDown("2025-12-31 23:59:59", ({ str }) => {
  this.countDownText = str
})

const task = () => api.getResult()
await pollingForResult(task, [], res => res.status === "OK" ? "success" : undefined)

模块聚合

index.js 将其他工具按命名空间导出，可通过 router.navTo、sugar.toast 等方式直接使用，便于统一管理依赖。

语法糖模块（tools/sugar.js）

UI 与交互

• toast(title, options?)：封装 uni.showToast，默认 2 秒无图标，支持自定义 icon 与 duration。
• previewImage(urls, current, options?)：图片预览，自动接管失败回调。
• saveImage(url, tips = true)：支持 H5 下载和小程序或 APP 保存到相册，可选是否提示。
• log(...args)：console.log 简写。

系统能力

• makePhoneCall(phoneNumber)：拨打电话并输出失败日志。
• openMap(lng, lat, name, address, options?)：打开地图定位。
• toCustomerService(corpId, url)：跳转企业微信客服，支持微信小程序、APP、H5。
• pageEvent.call(this)：Vue2 页面获取事件通道，需绑定页面实例。

数据与表单

• isEmpty(value) 与 hasEmptyField(obj, excludedKeys = [])：识别空值与未填写字段，返回首个空字段路径。
• setStorage(key, value)：同步缓存。
• object2queryStr(obj)：对象转查询字符串，自动补齐 ? 与 &。
• html2text(html)：去除标签和实体。
• dataMask(str, head, tail)：按位数脱敏，可用于手机号或证件号。

其他辅助

• upx2px(val)：将 upx 或 rpx 转换成像素。
• copy(str, options?)：复制内容到剪贴板。
• queryElementRect.call(this, selector)：基于 uni.createSelectorQuery 获取元素布局信息，支持数组批量查询。

import { toast, dataMask, hasEmptyField } from "@/uni_modules/x-tools/tools/sugar.js"

if (hasEmptyField(formData)) {
  toast("请完善表单信息")
}

const phone = dataMask("13800138000", 3, 4)

路由模块（tools/router.js）

• navTo(url, options?, timeout = 0)：普通页面跳转，可设置延时与额外参数。
• redTo(url, timeout)：uni.redirectTo 封装。
• clearTo(url, timeout)：uni.reLaunch 封装，清空页面栈。
• tabTo(url, timeout) 与 shTab(url, timeout)：跳转到 tabBar 页面。
• navBack(timeout = 0, delta = 1)：返回上一页。
• navToAndEvent(url, data, acceptCallback?, timeout)：跳转并通过事件通道传递数据，返回 Promise 获取回传值。
• navBackAndEvent(eventChannel, backData, timeout, delta)：在返回前向来源页面发送 backData。

import { navToAndEvent, navBackAndEvent } from "@/uni_modules/x-tools/tools/router.js"

await navToAndEvent("/pages/detail/detail", { id: 1 }, res => {
  console.log("detail 返回数据", res)
})

const eventChannel = this.getOpenerEventChannel()
eventChannel.on("navData", data => {
  this.detailId = data.id
})
navBackAndEvent(eventChannel, { updated: true })

H5 专用工具（tools/h5Utils.js）

• debug(tip = true)：动态加载 eruda 调试面板，失败时自动尝试多组 CDN。
• getQueryParams(url?)：解析 URL 查询字符串，默认读取当前地址。
• judgeBrowser()：识别浏览器环境，返回 wx、ali 或 unknown。
• loadScript(src)：动态注入 script，返回加载完成的节点。
• getWxAuthCode(appId, state?, scope?)：发起微信公众号 OAuth 授权，scope 默认为 snsapi_base。
• wxConfig(params)：基于签名参数配置 jWeixin，内部包含常用 API 列表。
• wxPay(params)：调用 chooseWXPay 发起公众号支付。
• wxShare(params)：设置好友与朋友圈分享信息。
• getAliAuthCode(appId, scope?)：支付宝生活号授权，支持 auth_base 与 auth_user。
• aliPay(tradeNO)：支付宝生活号支付封装。

import { debug, getQueryParams, wxPay } from "@/uni_modules/x-tools/tools/h5Utils.js"

debug()
const { orderNo } = getQueryParams()
await wxPay(payParams)

小程序工具（tools/appletUtils.js）

• toChannelsLive(finderUserName)：在微信小程序内跳转视频号直播，自动提示错误信息。
• getWxShareParams(queryParams?, title?, imageUrl?, path?)：生成小程序分享配置，默认读取当前页面参数并补充标题与路径。
• getSceneParams()：解析小程序场景值（如扫码进入），内部复用 h5Utils.getQueryParams 处理 scene。

import { getWxShareParams } from "@/uni_modules/x-tools/tools/appletUtils.js"

onShareAppMessage() {
  return getWxShareParams({ source: "invite" }, "邀请你加入", "/pages/index/index")
}

异步重试工具（tools/retryAsync.js）

retryAsync(asyncFn, options) 为任意 Promise 操作提供自动重试，支持自定义退避策略、超时控制与钩子。

选项	默认值	说明
maxRetries	3	最大允许的重试次数（不含首次执行）。
delay	1000	首次重试前的等待时间，单位毫秒。
backoffStrategy	fixed	退避策略：fixed、exponential、linear。
backoffFactor	2	指数退避或线性退避时的增长因子。
shouldRetry(error, attempt)	() => true	返回 false 可终止后续重试。
onRetry(error, attempt, max)	() => {}	每次准备重试时触发，可用于埋点。
timeout	空	单次任务超时时间，超时会抛出异常并进入重试流程。

import { retryAsync } from "@/uni_modules/x-tools/tools/retryAsync.js"

const fetchWithRetry = () => retryAsync(() => api.fetchData(), {
  maxRetries: 5,
  backoffStrategy: "exponential",
  shouldRetry: (err, attempt) => err.code !== "INVALID_TOKEN",
  onRetry: (err, attempt) => console.log(`retry ${attempt}`, err.message)
})

码工具（tools/codeUtil.js）

• new CodeUtil(codeTypeArray)：实例化时声明支持的码类型（数组顺序即类型索引）。
• codeUtil.scan(options?)：调用 uni.scanCode 扫码。
• codeUtil.getCodeInfo(options?)：扫码并解析内置编码格式，返回 { type, content }。
• codeUtil.makeCode(type, content)：生成带类型索引的 JSON 字符串，便于反向解析。
• codeUtil.parseCode(codeInfo)：解析任意字符串，返回码类型或错误信息。

import { CodeUtil } from "@/uni_modules/x-tools/tools/codeUtil.js"

const codeUtil = new CodeUtil(["user", "product"])
const payload = codeUtil.makeCode("user", { id: 123 })
const info = codeUtil.parseCode(payload)

组件辅助（tools/com.js）

• commonProps：通用组件属性集合，包含 bgColor、customStyle 等常用配置，便于在多个组件复用。
• str2px(str)：将 750rpx、100px、50 等字符串转换成像素值，与 sugar.upx2px 配合使用可统一渲染尺寸。

import { commonProps, str2px } from "@/uni_modules/x-tools/tools/com.js"

export default {
  props: {
    ...commonProps,
    width: {
      type: String,
      default: "750rpx"
    }
  },
  computed: {
    pixelWidth() {
      return str2px(this.width)
    }
  }
}

组合示例

import { countDown, pollingForData } from "@/uni_modules/x-tools/tools/index.js"
import { toast, hasEmptyField } from "@/uni_modules/x-tools/tools/sugar.js"
import { navTo } from "@/uni_modules/x-tools/tools/router.js"

export default {
  data() {
    return {
      countdownText: "",
      form: { phone: "", code: "" }
    }
  },
  onLoad() {
    this.timerId = countDown(Date.now() + 5 * 60 * 1000, ({ str }, finished) => {
      this.countdownText = str
      if (finished) toast("倒计时结束")
    })

    this.stopPolling = pollingForData(() => api.checkStatus(), [], (err, res) => {
      if (res?.done) {
        this.stopPolling()
        navTo("/pages/result/result?id=" + res.id)
      }
    }, 2000)
  },
  methods: {
    submit() {
      if (hasEmptyField(this.form)) return toast("请填写完整")
    }
  },
  onUnload() {
    clearInterval(this.timerId)
    this.stopPolling && this.stopPolling()
  }
}

注意事项

• 平台差异：带有 #ifdef 宏的函数仅在对应平台可用，调用前请先判断运行环境。
• 权限与授权：保存图片、拨打电话、支付等能力需提前申请相应权限或签名。
• 网络依赖：文件下载、远程支付等需要网络通畅并在 HTTPS 环境下运行。
• 错误处理：工具内部会在失败时打印日志，建议在业务代码中补充 try/catch 或失败提示。
• 性能考量：轮询与倒计时应适度释放资源，在页面卸载时清理定时器与停止函数。

更多信息

• 最新功能与修复请查看 changelog.md。
• 如需扩展工具模块，推荐在 tools 目录下新增文件并通过 index.js 统一导出。