更新记录

1.1.21（2026-01-11） 下载此版本

优化加载中提示

1.1.20（2026-01-04） 下载此版本

新增设置 TabBar 徽章

1.1.19（2026-01-04） 下载此版本

优化图片保存提示

平台兼容性

uni-app(3.6.15)

uni-app x(3.6.17)

t-xtools

基于 uni-app 的通用工具插件，按模块聚合常用功能，兼容 Vue2、Vue3。为获得更好的语法提示与 IDE 智能补全，推荐使用“手动全局挂载”的方式。

安装与使用

Vue3（推荐）手动全局挂载，获得完整语法提示

// main.js
import { createSSRApp } from "vue";
import xtools from "@/uni_modules/t-xtools";

export function createApp() {
  const app = createSSRApp(App);

  // 将常用方法挂到全局，IDE 可准确提示
  app.config.globalProperties.$xtools = xtools;

  uni.$xtools = xtools;

  return { app };
}

说明：使用 app.use(tXTools, { mpShare: true }) 在部分 IDE 中可能无法获得良好的语法提示；改为如上“手动全局挂载”后，this.$xtools 与 uni.$xtools 的方法均可获得更完整的智能提示。

Vue3（可选）插件挂载

// main.js
import { createSSRApp } from "vue";
import tXTools from "@/uni_modules/t-xtools";

export function createApp() {
  const app = createSSRApp(App);
  app.use(tXTools, { mpShare: true });
  return { app };
}

Vue2 插件挂载

// main.js
import Vue from "vue";
import tXTools from "@/uni_modules/t-xtools";

Vue.use(tXTools, { mpShare: true });

全局访问

• 通过 this.$xtools 或 uni.$xtools 访问聚合方法（例如：$xtools.imageCache、$xtools.debounce、$xtools.throttle）

功能一览

• 配置
  • Default 默认图片地址
  • Domain 相对路径补全域名
  • os() 返回设备平台：uni.getDeviceInfo().platform
  • uuid() 返回设备唯一标识：uni.getDeviceInfo().deviceId
• 图片
  • perfectUrl(url) 补全图片地址（自动去除前导/并折叠非协议//）
  • isBase64(str) 判断是否为 base64
  • preview(url|Array, needPerfect=false) 预览图片；当 needPerfect=true 时对每个地址先执行 perfectUrl
  • imageCache(url) APP/小程序端图片缓存
  • pathToBase64(path) 将本地路径/网络图转换为 base64（跨 H5/APP/微信小程序）
  • base64ToPath(base64) 将 base64 写入文件并返回路径（跨 APP/微信小程序/H5）
  • saveImage(url, tips=true) 保存图片（H5 触发下载，其它端保存到相册）
• 时间
  • getTime(ten=true) 返回时间戳：true 秒(10 位)，false 毫秒(13 位)
  • timeFormat(dateTime, fmt) 格式化为指定字符串，如 yyyy-mm-dd、yyyy年mm月dd日 hh时MM分
  • timeFrom(timestamp, fmt|false) 转为“多久之前”，false 时始终返回“xx 之前”
  • sleep(time=500) 延时 Promise，用于 async/await
• 登录
  • waitForLogin(loginKey?) 等待登录，就绪条件为本地缓存存在指定键，默认 appUid
  • runAfterLogin(fn, label, loginKey?) 登录就绪后执行回调
  • getWxAuthCode(appId, state?, scope?) 微信公众号授权获取 code（仅 H5）
  • LoginKey 登录就绪检测的键，默认 appUid
• 导航
  • goNext(url)、goBack(n)、goTab(url)、goAllClose(url)、goClose(url)
  • page() 获取当前页面路径
• 存储
  • get(key, value?)、set(key, value)、getRemove(key)、remove(key)
• 通知
  • showtt(text, icon)、showload()
  • setClipboard(text, tip=true) 复制文本到剪贴板
  • createPushMessage(options) 创建本地通知（仅 APP），icon 支持网络地址自动缓存
• 节流防抖
  • debounce(fn, wait, immediate)、throttle(fn, wait, immediate)
• 小程序
  • openMiniProgram(appId, path, envVersion, allowFullScreen=true) 跳转到其他小程序
  • updateManager() 小程序更新管理（检测更新并应用）
  • 插屏广告：wxInterstitialAd(adUnitId, vipExpireTs?, cb?)
  • vipExpireTs：VIP 过期时间戳（10 位秒或 13 位毫秒），未过期则不弹广告
  • cb：回调集合 { onLoad, onError, onClose, onShowError }

wxInterstitialAd 用法

• 方法：wxInterstitialAd(adUnitId, vipExpireTsOrCb?, cb?) → Promise<boolean>
• 参数：
  • adUnitId：广告位 ID
  • vipExpireTsOrCb：可传 10/13 位时间戳；或直接传回调对象 { onLoad, onError, onClose, onShowError }
  • cb：回调对象（当第二参是时间戳时可用第三参传回调）
• 返回：Promise<boolean>，true 表示正常展示并关闭，false 表示未展示（如 VIP 免弹或环境不支持）

示例：

// 1) 基础 Promise 用法
this.$xtools
  .wxInterstitialAd("ad-unit-id")
  .then((shown) => {
    if (shown) console.log("已展示并关闭");
    else console.log("未展示");
  })
  .catch((err) => console.log("展示失败", err));

// 2) async/await
const shown = await this.$xtools.wxInterstitialAd("ad-unit-id");
if (!shown) console.log("未展示");

// 3) 仅传回调对象（省略 VIP 时间戳）
this.$xtools.wxInterstitialAd("ad-unit-id", {
  onLoad: () => console.log("加载成功"),
  onError: (e) => console.log("加载失败", e),
  onClose: () => console.log("已关闭"),
  onShowError: (e) => console.log("显示失败", e),
});

// 4) 带 VIP 时间戳（10位或13位）
await this.$xtools.wxInterstitialAd("ad-unit-id", vipExpireTs);

• 分享（小程序）
  • 插件挂载时可通过参数 { mpShare: true } 开启，提供 uni.$xtools.mpShare
  • 使用“手动全局挂载”时，可在页面内设置：

onLoad() {
  this.$xtools.mpShare = {
    title: '标题',
    path: '/pages/index/index',
    imageUrl: '/static/share.jpg'
  }
}

示例

<template>
  <uv-button
    text="去个人中心"
    @click="$xtools.goNext('/pages/profile/profile')"
  />
</template>

<script>
export default {
  onLoad() {
    const avatar = this.$xtools.perfectUrl("images/a.png");
    const ts10 = this.$xtools.getTime(); // 10位
    const ts13 = this.$xtools.getTime(false); // 13位
    const fmt = this.$xtools.timeFormat(ts13, "yyyy年mm月dd日 hh时MM分");
    const from = this.$xtools.timeFrom(ts13);

    // 配置登录就绪键（直接赋值）
    this.$xtools.LoginKey = "token";

    // 等待登录（可传入自定义键）
    this.$xtools.waitForLogin("token").then(() => {
      // ...
    });

    // 预览图片：不补全/补全URL
    this.$xtools.preview(["/static/a.jpg", "images/b.jpg"]);
    this.$xtools.preview(["images/c.jpg", "/images/d.jpg"], true);
    // 插屏广告：基础用法
    this.$xtools.wxInterstitialAd("ad-unit-id");
  },
};
</script>

目录结构

uni_modules/t-xtools/
  ├─ index.js           // 插件聚合与挂载
  ├─ share.js           // 小程序分享 mixin
  └─ js_sdk/            // 模块源码
     ├─ image.js        // perfectUrl/isBase64/preview
     ├─ getImageCache.js
     ├─ time.js         // getTime/timeFormat/timeFrom
     ├─ login.js        // getWxAuthCode
     ├─ loginReady.js   // waitForLogin/runAfterLogin
     ├─ navigate.js     // goNext/goBack/...
     ├─ storage.js      // get/set/getRemove/remove
     ├─ notify.js       // showtt/showload
     ├─ clipboard.js
     ├─ push.js
     ├─ throttle.js
     ├─ debounce.js
     ├─ miniProgram.js  // openMiniProgram
     ├─ updateManager.js
     └─ router.js       // page

约定

• 全局挂载后提供：this.$xtools、uni.$xtools
• 网络图片统一通过 $xtools.perfectUrl() 处理