jay-utils-uni

一个面向 UniApp（H5 / 小程序 / App）全端通用的 JavaScript 工具库。零依赖、开箱即用，把项目里常见的「请求、路由、存储、格式化、校验、日期、树、平台判断、WebSocket、上传下载」等重复代码全部封装好，一套配置、多个项目复用。

支持：Vue2 / Vue3、H5、微信/支付宝等小程序、App（iOS / Android / 鸿蒙）。所有 uni.* / plus.* / window.* 调用均有环境保护，不会因为平台差异报错。

一、安装

npm install jay-utils-uni

发布到 npm 的包内已包含：

• dist/index.esm.js（ESM，现代构建用）
• dist/index.cjs（CJS，老工程 require 用）
• dist/index.d.ts（TypeScript 类型）
• docs/index.html（渲染好的使用文档站）
• docs/*.md（各模块 Markdown 原文）
• vite-plugin.mjs（可选的路由构建插件，配合 createRouter 使用）

二、快速开始

方式 1：按需引入（推荐）

import { formatDate, getToken, platform } from 'jay-utils-uni'

const now = formatDate(new Date(), 'YYYY-MM-DD')
const isApp = platform().isApp
const token = getToken()

方式 2：全量引入（简单项目）

import * as u from 'jay-utils-uni'

u.toast('Hello')
u.formatPrice(19.9) // ¥19.90

方式 3：CJS（Vue2 老工程 / Node 脚本）

const u = require('jay-utils-uni')

三、模块总览（418 个导出）

| 模块 | 说明 | 文档 | | --- | --- | --- | | core | 类型判断、常量、环境、ID、日志、数学、字符串、对象、数组 | docs/core.md | | api | 接口工厂 createApi：URL+方法声明成函数，告别样板 | docs/api.md | | data | 日期、格式化、文件、树、校验 | docs/data.md | | async | 高阶函数（防抖/节流/重试/并发/记忆化）、Promise 工具 | docs/async.md | | platform/request | 三合一 HTTP 封装（请求/上传/下载 + 10 大能力开关） | docs/request.md | | platform/router | 路由跳转封装 + createRouter 类式路由 + vite 插件 | docs/router.md | | platform 其他 | 系统信息、UI 交互、存储、网络、剪贴板、音频、下载、权限、推送、Socket、URL | docs/platform.md | | 综合示例 | 一个真实项目的完整接入姿势 | docs/example.md |

四、30 秒上手三个高频场景

1. 发起一个请求（三合一，自动带 token、防重复、失败重试）

import { createRequest } from 'jay-utils-uni'

const http = createRequest({
  baseURL: 'https://api.example.com',
  timeout: 10000,
  token: { enable: true, getToken: () => uni.getStorageSync('token'), headerName: 'Authorization' },
  business: { successCode: 0, loginCode: 401 },
})

// 普通请求
const res = await http.get('/user/info')
// 上传图片（APP/小程序/H5 通用）
await http.upload('/upload/img', { filePath: tempFilePath, name: 'file', formData: { type: 'avatar' } })

2. 页面跳转（自动登录拦截 + 参数类型还原）

import { createRouter } from 'jay-utils-uni'

const router = createRouter({ isLogin: () => !!getToken() })
export default { install(app) { app.use(router) } }

// 页面里：this.$router.go('/pages/detail/index', { id: 1001 })
// 目标页：this.$router.getRouteQuery() // => { id: 1001 }（数字自动还原）

3. 存储 + 格式化 + 平台判断

import { setItem, getItem, formatPrice, platform } from 'jay-utils-uni'

setItem('cart', [{ id: 1, price: 12.5 }])
const cart = getItem('cart', [])
const p = platform() // { name:'App', isIOS:true, isMiniProgram:false, ... }

五、模块间如何配合（核心思路）

「傻瓜式」不代表各自独立——本库特意做了联动设计，常用组合如下：

| 组合 | 说明 | 详情 | | --- | --- | --- | | createApi(http, ...) + createRequest() | 一个 http 实例 + 多个业务 API 模块文件，接口清单零样板 | docs/request.md | | createRouter() + vite-plugin | 构建期自动读 pages.json 生成路由表，页面无需重复配置 | docs/router.md | | request + core/constants | STATUS_CODE / HTTP_METHOD / DEFAULT_CONFIG 直接作为请求配置引用 | docs/request.md | | request + platform/network | 请求前自动检测网络（network.enable），断网直接拦截 | docs/request.md | | router + platform/storage | 登录判断 isLogin 通常读 getToken() | docs/router.md | | platform() + env.isXxx | 平台/系统判断做 UI 差异与条件渲染 | docs/platform.md | | storageWithExpire + request | 带过期时间的接口缓存 | docs/platform.md | | tree + format + validate | 后台菜单树 → 前端展示/校验全套 | docs/data.md |

六、为什么不用手写

• 全端安全：所有平台 API 均有 typeof 保护，小程序没有 window、App 才有 plus，库内已自动分流。
• 一套配置多项目：request / router / storage / cdn 都是「工厂函数」，每个项目传自己的参数即可，业务代码零差异。
• 不再重复造轮子：集合运算、精度计算、深拷贝、时间戳转换、脱敏、表单校验等 400+ 方法随取随用。

七、许可

MIT