common-vue3-utils v1.0.1

• 概述
• 如何使用
  • 安装
  • 引入
• base库使用的环境变量列表
• API
  • type \& interface \& class
    • Exception 异常类
    • CacheItem 缓存项
    • ServicesHeader 调用接口headers选项
    • ServicesOptions 调用接口选项
    • SystemRet 通用返回结构（移动端）
    • PCSystemRet 通用返回结构（PC端）
    • WeixinBridgeObject 微信jssdk的wx对象
    • DictItem 数据字典枚举项
    • Dict 数据字典
    • Env 环境变量
    • MyTreeNode\<T> 树形节点
    • RouteInfo 路由信息
    • WXImageWatermark 微信图片水印
    • WXImage 微信图片
    • ImageRet 图片服务器返回结构
    • WXChooseRes 微信图片选择结果
    • WXUploadRes 微信图片上传结果
    • TimingStage Timing打点
    • RouterGuard 路由守卫类型
  • Util 实用工具
    • untill 异步状态检查
    • isWeixinClient 判断是否微信客户端
    • setTitle 设置页面title内容
    • clone 克隆对象
    • promiseScriptLoader 异步加载外部script
    • sleep 延迟执行
    • getQueryString 获取url参数
    • currentUrl 获取当前url
    • currentPath 获取当前路径
    • setQueStr 设置uri参数
    • delQueStr 删除uri参数
    • oauth 公众号/企业微信授权
    • jssdk jssdk实例化
    • listToTree
    • ucwords
    • urlToPascalCase
    • objToUrl
    • redirect
    • assignAttrs
    • xss
    • randomInt
    • exportCSV
    • getDeviceResolution
    • findItem
  • Acc
    • add, sub, mul, div
  • Cache
    • set
    • get
    • remove
  • Datetime
    • today
    • format
  • Dict
    • dict
    • getDict
    • addDict
  • Env
    • set
    • get
  • ImageUtil
    • 构造方法
    • chooseImage
    • uploadImageToWX
    • uploadImageToServer
  • Locker
    • lockBack, releaseBack, lockScroll, releaseScroll
  • Pay
    • invoke
  • Services
    • invoke
    • setBasicSetting
  • RouterExtender
  • StringUtil
    • numberFormat
    • priceFormat
    • startWith
    • endWith
    • convertCurrency
  • Timing
    • instance
    • tick
    • report
  • Validator
    • isEmptyObject
    • isNumeric
    • isString
    • isObject
    • isArray
    • isMobile
    • isTel
    • isAlphabetChinese
    • isAlphabetNumberChinese
    • isIDCard
    • isVehicleNumber
    • isEmail
    • isURL
    • authPasswd

概述

common-vue3-utils库是使用typescript开发，面向vue3，定位是一个轻量级，平台无关（PC、Mobile皆可使用），UI库无关（不集成具体UI库）的通用库。包含了请求封装，数据验证，缓存操作，基础接口定义（interface），实用工具以及微信相关验证及jssdk封装等等。目的是减少项目中重复定义的通用逻辑，并提供路由守卫的顺序校验控制。

如何使用

安装

npm install common-vue3-utils@latest --save-dev

注意：该库仅发布到公司内网的私服中，如开发机在外部网络将无法安装，因此安装时需要指定仓库地址。

引入

import { Util, Cache } from 'common-vue3-utils' // 例子中的 Util 和 Cache 为 common-vue3-utils 导出的成员

base库使用的环境变量列表

API

此章节主要描述各导出成员的提供的功能。注意：任何标注为Promise化方法的实例代码，默认只写回调方式，如需await / async可以自行改写，此文档不再赘述

type & interface & class

描述库中定义的type、interface和class

Exception 异常类

class，继承自Error类，用于定义自定义异常使用。库中大部分异常均抛出此实例。一般结合try-catch使用。

成员变量

方法

构造方法

实例化异常

方法参数

返回

Exception 实例

示例代码

import { Exception } from 'common-vue3-utils'
const e = new Exception('invalid code', 400)

getCode

获取异常代码

返回

number

示例代码

import { Exception } from 'common-vue3-utils'
const e = new Exception('invalid code', 400)
console.log(e.getCode()) // 400

getMessage

获取异常信息

返回

string

示例代码

import { Exception } from 'common-vue3-utils'
const e = new Exception('invalid code', 400)
console.log(e.getMessage()) // invalid code

CacheItem 缓存项

interface，缓存项，用于下述的Cache工具库 |属性名|类型|必须|说明| |:---|:---:|:---:|:---| |lifetime|number|是|缓存有效期, ms| |data|any|是|缓存内容|

ServicesHeader 调用接口headers选项

interface，Services invoke参数中headers的配置项 |属性名|类型|必须|说明| |:---|:---:|:---:|:---| |proxydatatype|string|否|指定该接口的参数以何种格式传递给后端，支持传入json, form以及query。json：转发时会以post+json形式发起请求（默认）；form：转发时会以post+form形式发起请求；query: 转发时会以get+querystring形式发起请求|

ServicesOptions 调用接口选项

interface，Services invoke的参数类型 |属性名|类型|必须|说明| |:---|:---:|:---:|:---| |url|string|是|请求的url路径| |data|object|是|请求的参数| |service|string|否|service头内容| |contentType|string|否|content-type头内容| |type|string|否|请求方式, get, post，默认post| |headers|object|否|http请求头对象| |withCredentials|boolean|否|是否发送凭证| |resType|ResponseType|否|返回类型，默认json| |cache|number|否|正常响应的缓存时间，默认false，不缓存|

SystemRet 通用返回结构（移动端）

interface，通用返回结构（移动端） |属性名|类型|必须|说明| |:---|:---:|:---:|:---| |status|number|是|状态值，200是正常，其它异常| |msg|string|是|返回信息| |data|T|是|返回数据|

PCSystemRet 通用返回结构（PC端）

interface，通用返回结构（PC端） |属性名|类型|必须|说明| |:---|:---:|:---:|:---| |status|number|是|状态值，1是正常，其它异常| |message|string|是|返回信息| |data|T|是|返回数据|

WeixinBridgeObject 微信jssdk的wx对象

interface，微信jssdk的wx对象 |属性名|类型|必须|说明| |:---|:---:|:---:|:---| |config|Function|是|验证方法| |ready|Function|是|验证成功| |error|Function|是|验证失败| |checkJsApi|Function|是|查询是否有API的权限| |具体的API|Function|是|参考微信公众号JSSDK的文档|

DictItem 数据字典枚举项

interface，字典枚举项，用于下述的Dict实用类 |属性名|类型|必须|说明| |:---|:---:|:---:|:---| |key|StringOrNumber|是|枚举值| |value|StringOrNumber|是|枚举内容|

Dict 数据字典

interface，字典，用于下述的Dict实用类 |属性名|类型|必须|说明| |:---|:---:|:---:|:---| |name|string|是|字典名| |enums|DictItem[]|是|字典枚举项列表|

Env 环境变量

interface，环境变量，用于下述的Env实用类 |属性名|类型|必须|说明| |:---|:---:|:---:|:---| |name|string|是|变量名| |value|StringOrNumber|是|变量值|

MyTreeNode\<T> 树形节点

interface，树节点，用于Util.listToTree |属性名|类型|必须|说明| |:---|:---:|:---:|:---| |key|StringOrNumber|是|节点id| |pKey|StringOrNumber|是|父节点id| |title|string|是|节点名| |isLeaf|boolean|是|是否叶子节点| |visible|number|是|是否显示， 1显示| |path|string|是|节点id构成的路径| |data|T|是|节点数据| |children|MyTreeNode\<T>[]|是|子节点列表| |disabled|boolean|是|是否禁用|

RouteInfo 路由信息

interface，路由信息 |属性名|类型|必须|说明| |:---|:---:|:---:|:---| |name|string|是|路由名| |path|string|是|路由路径| |params|any|是|路由params对象| |query|any|是|路由query对象|

WXImageWatermark 微信图片水印

interface，微信图片水印 |属性名|类型|必须|说明| |:---|:---:|:---:|:---| |x|number|是|横坐标，从左上角算| |y|number|是|纵坐标，从左上角算| |fontSize|number|是|水印文字大小| |text|string|是|水印文字|

WXImage 微信图片

interface，微信图片对象 |属性名|类型|必须|说明| |:---|:---:|:---:|:---| |serverId|string|是|微信图片的serverId| |watermarks|WXImageWatermark[]|是|水印列表| |isPrivate|number|是|是否加密地址|

ImageRet 图片服务器返回结构

interface，图片服务器返回的图片对象 |属性名|类型|必须|说明| |:---|:---:|:---:|:---| |state|string|是|状态| |title|string|是|文件名| |size|string|是|文件大小| |url|string|是|文件url|

WXChooseRes 微信图片选择结果

interface，微信jssdk的chooseImage结果对象 |属性名|类型|必须|说明| |:---|:---:|:---:|:---| |errMsg|string|是|结果信息| |localIds|string[]|是|本地id列表|

WXUploadRes 微信图片上传结果

interface，微信jssdk的uploadImage结果对象 |属性名|类型|必须|说明| |:---|:---:|:---:|:---| |errMsg|string|是|结果信息| |serverId|string|是|服务器资源id列表|

TimingStage Timing打点

interface，Timing实用类的打点对象 |属性名|类型|必须|说明| |:---|:---:|:---:|:---| |name|string|是|打点标记文字| |time|string|是|打点时间| |cost|number|是|距离上一次打点的耗时，ms| |costFromStart|number|是|从instance时算起的耗时，ms| |extra|any|是|打点传入的extra信息|

RouterGuard 路由守卫类型

type, 用以描述路由守卫方法的参数 |参数名|类型|必须|说明| |:---|:---:|:---:|:---| |services|Services|是|服务API对象| |from|RouteLocationNormalized|是|vue router的路由对象| |to|RouteLocationNormalized|是|vue router的路由对象| |next|Function|是|vue router的next方法|

Util 实用工具

这是一个实用工具集对象，也是实用频率最高的一个API。使用前，需要import。

untill 异步状态检查

Promise化的定时检查异步任务的方式，等待异步完成的方法，通常配合await / async使用。如在无法注入已经存在的异步回调的情况下，可以使用该方法进行判断具体的异步事务是否已经完成。

方法参数

返回

Promise

示例代码

import { Util } from 'common-vue3-utils'


let somethingIsReady = false
// 模拟异步任务，2秒后成功
setTimeout(() => {
    somethingIsReady = true
}, 2000)

console.log('somethingIsReady: no')
// 定时检查是否完成
Util.untill(
    () => {
        if (somethingIsReady) {
            return true
        }
    },
    10,
    20000
).then(() => {
    console.log('somethingIsReady: yes')// 两秒后输出
})

isWeixinClient 判断是否微信客户端

判断是否微信客户端(排除企业微信客户端)

方法参数

无

返回

boolean

示例代码

import { Util } from 'common-vue3-utils'

if (Util.isWeixinClient()) {
    console.log('现在客户端是微信客户端')
}

setTitle 设置页面title内容

设置页面title内容（即浏览器标签栏或移动端的标题栏内容）

方法参数

返回

无

示例代码

import { Util } from 'common-vue3-utils'

Util.setTitle('标题内容')

clone 克隆对象

克隆对象，用于避免操作新对象，会引起源对象变更时候使用

方法参数

返回

示例代码

import { Util } from 'common-vue3-utils'

const obj1 = { a: 1, b: 2 }
const obj2 = Util.clone(obj1)
const obj3 = obj1
obj2.a = 3
console.log(obj1) // { a: 1, b: 2 }
console.log(obj2) // { a: 3, b: 2 } 不会修改obj1.a的内容，因为clone方法是拷贝一个新的对象，不是对obj1的引用

obj3.a = 4
console.log(obj1) // { a: 4, b: 2 }
console.log(obj3) // { a: 4, b: 2 } 会修改obj1.a的内容，因为js是面向对象的，赋值默认是传引用

promiseScriptLoader 异步加载外部script

Promise化的异步加载外部的javascript，在引入jssdk，地图jsapi，统计js等场景下需要。须确保引入的地址是可信的，官方的，以防被投毒。

方法参数

返回

Promise

示例代码

import { Util } from 'common-vue3-utils'

Util.promiseScriptLoader('http://xxxx.com/xxx.js').then(() => {
    console.log('loaded') // 加载成功，可以访问里面的内容或API
}).catch(() => {
    console.log('error loaded') // 加载失败
})

sleep 延迟执行

Promise化的延迟执行。

方法参数

返回

Promise

示例代码

import { Util } from 'common-vue3-utils'

// 延迟两秒执行
Util.sleep(2000).then(() => {
    console.log('ok')
})

getQueryString 获取url参数

获取当前页面url或指定url里的query参数内容()

方法参数

返回

string

示例代码

import { Util } from 'common-vue3-utils'

console.log(Util.getQueryString('a', '?a=1&b=2')) // 1

currentUrl 获取当前url

获取当前页面url，不含hash部分

方法参数

无

返回

string

示例代码

import { Util } from 'common-vue3-utils'

console.log(Util.currentUrl()) // http://localhost:9090/?no_loading=1&code=silentsea001

currentPath 获取当前路径

获取当前host+路径

方法参数

无

返回

string

示例代码

import { Util } from 'common-vue3-utils'

console.log(Util.currentPath()) // http://localhost:9090/

setQueStr 设置uri参数

设置url里指定的参数值

方法参数

返回

string

示例代码

import { Util } from 'common-vue3-utils'

console.log(Util.setQueStr('http://test.com/?a=1&b=2', 'a', '9')) // http://test.com/?a=9&b=2

delQueStr 删除uri参数

删除url里指定的参数值

方法参数

返回

string

示例代码

import { Util } from 'common-vue3-utils'

console.log(Util.delQueStr('http://test.com/?a=1&b=2', 'a')) // http://test.com/?b=2

oauth 公众号/企业微信授权

公众号或企业微信的oauth认证链接构造或重定向

方法参数

返回

string或重定向

示例代码

import { Util } from 'common-vue3-utils'

console.log(Util.oauth('http://test.com/?a=1&b=2', true, false)) // http://192.170.200.9:9898/wxwork/cgi-bin/public/oauth.html?appid=wxad5f4041fd5c0992&redirect_uri=aHR0cCUzQSUyRiUyRnRlc3QuY29tJTJGJTNGYSUzRDElMjZiJTNEMg%3D%3D&response_type=code&scope=snsapi_userinfo&state=stamp_oauth#wechat_redirect
// 此oauth url为模拟oauth的地址，生产为微信端提供的oauth地址https://open.weixin.qq.com/connect/oauth2/authorize

jssdk jssdk实例化

用于初始化微信JSSDK及完成相应页面验证，并返回微信JSSDK对象，建议在pinia store中定义action，提供给vue等调用

方法参数

返回

Promise\<WeixinBridgeObject>

示例代码

import { Services, Util } from 'common-vue3-utils'
import services from '../lib/services' // 此为具体项目中用于实例化Services对象的文件

jssdk() {
    return new Promise<WeixinBridgeObject>((resolve, reject) => {
        Util.jssdk(services, Env.get('JSSDK_API').split(','))
            .then((wx) => {
                resolve(wx)
            })
            .catch(() => {
                reject(false)
            })
    })
}

listToTree

数组转树形结构

方法参数

泛型 T： 传入用于描述数组对象的interface或者class |参数名|类型|必须|默认值|说明| |:---|:---:|:---:|:---:|:---| |arr|T[]|是|-|对象数组| |id|string|是|-|id属性名| |pId|string|是|-|父id属性名| |title|string|是|-|节点标题属性名| |visible|string|是|-|是否显示属性名| |filter|Function|是|-|过滤方法，提供给调用侧控制特定节点是否要被过滤掉，方法返回ture表示允许加入到树，反之则被过滤| |topPid|StringOrNumber|否|-|顶级节点的id，如不传入，则自动筛选出无对应pid的节点，作为顶层节点|

返回

MyTreeNode[]

示例代码

import { Util } from 'common-vue3-utils'
// 此处仅为更好描述传入listToTree的泛型结构，开发中不建议此处定义，而应该在单独的d.ts中定义并引入
interface RawMenuItem {
    id: number
    menuName: string
    moduleId: string | null
    parentId: number
    sort: number
    htmlUrl: string
    jsUrl: string
    url: string
    icon: string
    menuType: string
    visible: number
    perms: string
    descn: string
    menuId: number
    prefixedName: string
    routeName: string
}
const menuList: RawMenuItem[] = [] // 数组对象
const menuTree = Util.listToTree<RawMenuItem>(
                    menuList,
                    'id',
                    'parentId',
                    'menuName',
                    'visible',
                    () => {
                        return true
                    })

ucwords

对传入字符串的首字母大写，并将剩余字符小写

方法参数

返回

string

示例代码

import { Util } from 'common-vue3-utils'
var str = 'sadKLSAaskl'
console.log(Util.ucwords(str)) // 'Sadklsaaskl'

urlToPascalCase

对传入url字符串转换成Pascal形式，即abc/def/ghi => AbcglueDefglueGhi

方法参数

返回

string

示例代码

import { Util } from 'common-vue3-utils'
const url = 'outsourcing/driver/form'
console.log(Util.urlToPascalCase(url, '-')) // Outsourcing-Driver-Form

objToUrl

对象转url参数

方法参数

泛型 T： 传入用于描述对象的interface或者class |参数名|类型|必须|默认值|说明| |:---|:---:|:---:|:---:|:---| |obj|T|是|-|需要转换的对象|

返回

string[]

示例代码

import { Util } from 'common-vue3-utils'
// 此处仅为更好描述传入objToUrl的泛型结构，开发中不建议此处定义，而应该在单独的d.ts中定义并引入
interface Params {
    beginDate: string
    endDate: string
    status: string
}
const params: Params = {
    beginDate: '2023-08-12',
    endDate: '2023-08-31',
    status: '1'
}
console.log(Util.objToUrl(params)) //  ['beginDate=2023-08-12', 'endDate=2023-08-31', 'status=1']

redirect

重定向到指定链接，可以用于跳转到外部系统，或者执行导出

方法参数

返回

无

示例代码

import { Util } from 'common-vue3-utils'
Util.redirect('http://www.baidu.com')

assignAttrs

批量设置给定泛型T的对象属性

方法参数

返回

无

示例代码

import { Util } from 'common-vue3-utils'
// 此处仅为更好描述传入assignAttrs的泛型结构，开发中不建议此处定义，而应该在单独的d.ts中定义并引入
interface Params {
    beginDate: string
    endDate: string
    status: string
}
const params1: Params = {
    beginDate: '2023-08-12',
    endDate: '2023-08-31',
    status: '1'
}
const params2: Params = {
    beginDate: '2023-08-12',
    endDate: '2023-08-31',
    status: '2'
}
Util.assignAttrs<Params>(params1, params2) 
console.log(params1) // {beginDate: '2023-08-12', endDate: '2023-08-31', status: '2'}

xss

xss过滤

方法参数

返回

字符串

示例代码

import { Util } from 'common-vue3-utils'

const str = '<span>1</span>'
console.log(Util.xss(str, undefined)) 

randomInt

返回给定范围(含)内的一个随机的整数

方法参数

返回

number

示例代码

import { Util } from 'common-vue3-utils'

console.log(Util.randomInt(1, 5)) // 返回1至5的随机整数

exportCSV

导出数据成csv文件

方法参数

返回

无

示例代码

import { Util } from 'common-vue3-utils'

console.log(Util.exportCSV([[1, 2, 3], [4, 5, 6]]), 'test.csv') //

getDeviceResolution

获取设备宽高

方法参数

无

返回

示例代码

import { Util } from 'common-vue3-utils'

console.log(Util.getDeviceResolution() //

findItem

查询列表中满足条件的元素

方法参数

返回

T[]

示例代码

import { Util } from 'common-vue3-utils'

interface TestItem {
    name: string
}

const list:TestItem[] = [{name: 'a'}, {name: 'b'}]

console.log(Util.findItem<TestItem>(list, 'name', 'b'))// [{name: 'b'}]

Acc

这是一个用于精确计算的工具类。因为众所周知的原因，原生js进行计算会出现意想不到的结果，所以需要定义一个符合运算结果的方式来实现。

add, sub, mul, div

分别为加法，减法，乘法，除法

方法参数

返回

number

示例代码

import { Acc } from 'common-vue3-utils'

console.log(Acc.add(1, '2')) // 3
console.log(Acc.sub(10, 2)) // 8
console.log(Acc.mul('2', '2')) // 4
console.log(Acc.div('2', 4)) // 0.5

Cache

这是一个用于操作浏览器缓存的工具类。存储介质是基于localStorage

set

设置缓存

方法参数

返回

无

示例代码

合并到最后描述

get

读取缓存

方法参数

返回

any

示例代码

合并到最后描述

remove

删除缓存

方法参数

返回

any

示例代码

import { Cache, Util } from 'common-vue3-utils'
/** 
 * 有效期内及有效期外读取
 */
const cacheKey = 'username'
const cacheValue = 'Tommy'

Cache.set(cacheKey, cacheValue, 10000) // 设置一个缓存，有效期为10s
console.log(Cache.get(cacheKey)) // 'Tommy'
Util.sleep(11000).then(() => {
    console.log(Cache.get(cacheKey)) // null
})

/** 
 * 删除前后读取
 */
const cacheKey = 'username'
const cacheValue = 'Tommy'

Cache.set(cacheKey, cacheValue, 10000) // 设置一个缓存，有效期为10s
console.log(Cache.get(cacheKey)) // 'Tommy'
Cache.remove(cacheKey) // 删除指定cache
console.log(Cache.get(cacheKey)) // null

Datetime

这是一个用于获取日期的实用类

today

获取今天日期

方法参数

无

返回

string

示例代码

import { Datetime } from 'common-vue3-utils'
console.log(Datetime.today()) // 当天日期： YYYY-MM-DD

format

格式化日期

方法参数

返回

string

示例代码

import { Datetime } from 'common-vue3-utils'
console.log(Datetime.format('2018-12-21 20:00:12', 'YYYY-MM-DD')) // 2018-12-21

Dict

这是一个字典操作的实用类。注意，这个是没有使用命名空间方式实现的，而是直接暴露了具体的操作方法

dict

获取字典的枚举值

方法参数

返回

StringOrNumber

示例代码

合并到最后描述

getDict

获取字典，常用于输出字典选项列表

方法参数

返回

DictItem[]

示例代码

合并到最后描述

addDict

增加字典

方法参数

返回

无

示例代码

import type { Dict } from 'common-vue3-utils/@types'
import { dict, getDict, addDict } from 'common-vue3-utils'

const newDict:Dict = {
    name: 'serviceType',
    enums: [
        { key: '1', value: '上门' },
        { key: '2', value: '自提' }
    ]
}

addDict(newDict) // 写入一个字典
console.log(getDict('serviceType')) // [ { key: '1', value: '上门' }, { key: '2', value: '自提' } ]
console.log(dict('serviceType', '1')) // 上门

Env

这是一个用于操作环境变量的实用类，常用于项目读取环境配置，并设置到环境变量，以便于common-vue3-utils内部使用，项目中也可以使用

set

设置环境变量

方法参数

返回

无

示例代码

import { Env } from 'common-vue3-utils'

Env.set('DEBUG', 'disabled')

get

获取环境变量

方法参数

返回

无

示例代码

import { Env } from 'common-vue3-utils'

console.log(Env.get('DEBUG', 'empty content')) // 'empty content'
Env.set('DEBUG', 'disabled')
console.log(Env.get('DEBUG', 'empty content')) // 'disabled'

ImageUtil

这是一个用于上传微信图片的实用工具类

构造方法

实例化

方法参数

返回

无

示例代码

import { ImageUtil } from 'common-vue3-utils'
import services from '@/lib/services'

// 假设在commonStore中实现了jssdk实例化
commonStore
    .jssdk()
    .then((wx: WeixinBridgeObject) => {
        imageUtil = new ImageUtil(services, wx)
    })
    .catch(() => {
        // jssdk 实例化失败
    })

chooseImage

调起微信jssdk的选择图片

方法参数

返回

Promise<string[]>: localId的字符串数组

示例代码

imageUtil.chooseImage({ count: 3 }).then( (localIds: string[]) => {
    console.log(localIds)  
})

uploadImageToWX

上传至微信服务器，默认支持批量

方法参数

返回

Promise<string[]>: serverId的字符串数组

示例代码

imageUtil
    .uploadImageToWX({
        localIds: [image.localId],
        isShowProgressTips: isShowProgressTips.value })
        .then((serverIds: string[]) => {
            console.log(serverIds)    
        })
        .catch((e) => {
            console.error('upload to wx error: ' + JSON.stringify(e))
        })

uploadImageToServer

上传至图片服务器（实际上是经过node网关拉取微信服务器的资源，并上传到图片服务器）

方法参数

返回

Promise<ImageRet[]>: 图片上传结果对象

示例代码

imageUtil
    .uploadImageToServer({ pics, convert: true })
    .then((uploaded: ImageRet[]) => {                   
    })
    .catch((e) => {
        console.error('upload to server error: ' + JSON.stringify(e))
    })

Locker

这是一个用于锁定/解锁用户操作的实用工具类，包括用户返回，用户滚动等

lockBack, releaseBack, lockScroll, releaseScroll

分别为锁定用户返回，解锁用户返回，锁定用户滚动，解锁用户滚动

方法参数

无

返回

无

示例代码

import { Locker } from 'common-vue3-utils'
const l = Locker.instance()
l.lockBack() // 锁定用户返回
l.releaseBack() // 解锁用户返回
l.lockScroll() // 锁定用户滚动
l.releaseScroll() // 解锁用户滚动

Pay

这是一个用于发起微信支付的实用工具类

invoke

发起微信支付

方法参数

返回

无

示例代码

import router from '@/router'
import { Pay } from 'common-vue3-utils'

// 请求后端接口，获取支付参数
const ret = await crossDistrictStore.createPay({
    mailNo: orderInfo.value.mailNo
})

Pay.instance().invoke(router, {
    paramMap: ret.paramMap,
    successRoute: {
        name: 'CrossDistrict/PayResult',
        path: '',
        params: {
            orderId: orderInfo.value.orderId,
            result: 'success'
        },
        query: {}
    },
    failRoute: {
        name: 'CrossDistrict/PayResult',
        path: '',
        params: {
            orderId: orderInfo.value.orderId,
            result: 'fail'
        },
        query: {}
    }
})

Services

这是一个用于发起接口调用的类，基于axios实现

invoke

发起调用

方法参数

返回

无

示例代码

import { Services } from 'common-vue3-utils'

const services = new Services()

/**
 * 设置全局请求头
 */
services.setBasicSetting('headers', {
    clientId: import.meta.env.VITE_CLIENT_ID
})

const ret = (await services.invoke({
    url: servicePrefix + 'wx/proxy/outsdriver/manage/current/role',
        data: {
            userId: '',
            mobile: ''
        }
    })) as SystemRet<UserInfo>

if (ret.status !== Services.NORMAL_STATUS) {
   throw new Exception(ret.msg, ret.status)
}

setBasicSetting

设置默认配置

方法参数

返回

无

示例代码

import { Services } from 'common-vue3-utils'

const services = new Services()

/**
 * 设置全局请求头
 */
services.setBasicSetting('headers', {
    clientId: import.meta.env.VITE_CLIENT_ID
})

RouterExtender

对vue-router对象的扩展，次扩展仅提供一个方法，即RouterExtender，用于集成RouterGuard到路由的跳转钩子中，实现路由守卫的功能。在权限控制，通用属性获取等场景下能提供便利的开发模式。

方法参数

返回

无

示例代码

import { createRouter, createWebHashHistory } from 'vue-router'
import services from '@/lib/services'

const router = createRouter({
    history: createWebHashHistory(),
    routes: []// 此处省略路由定义
})

RouterExtender(router, services, (e: Exception) => {
    if (e.getCode() === 404) {
        router.push({ name: 'not-found' })
    }
})

StringUtil

通用字符串实用工具类

numberFormat

数值格式化

方法参数

返回

number

示例代码

import { StringUtil } from 'common-vue3-utils'

console.log(StringUtil.numberFormat('200.2151231', 2, true)) //200.22

priceFormat

金额格式化

方法参数

返回

string

示例代码

import { StringUtil } from 'common-vue3-utils'

console.log(StringUtil.priceFormat('200221.2151231', 2, '￥', ',')) //￥200,221.22

startWith

判断给定字符串是否以指定字符串开头(大小写敏感)

方法参数

返回

boolean

示例代码

import { StringUtil } from 'common-vue3-utils'

console.log(StringUtil.startWith('Whoareyou', 'Who')) // true
console.log(StringUtil.startWith('Whoareyou', 'who')) // false

endWith

判断给定字符串是否以指定字符串结尾(大小写敏感)

方法参数

返回

boolean

示例代码

import { StringUtil } from 'common-vue3-utils'

console.log(StringUtil.endWith('WhoareYou', 'You')) // true
console.log(StringUtil.endWith('WhoareYou', 'you')) // false

convertCurrency

将阿拉伯数字的金额转换成中文大小写金额

方法参数

返回

string

示例代码

import { StringUtil } from 'common-vue3-utils'

console.log(StringUtil.convertCurrency('57892.12')) // 伍万柒仟捌佰玖拾贰元壹角贰分

Timing

时间评估实用工具类，用于评估代码块的执行时间

instance

获取实例

方法参数

返回

Timing

示例代码

import { Timing } from 'common-vue3-utils' // 或gzpost-desktop-for-vue3

Timing.instance('test')  // 参数是用来标识实例的

tick

计时打点

方法参数

返回

无

示例代码

import { Timing } from 'common-vue3-utils' // 或gzpost-desktop-for-vue3

Timing.instance('test').tick('用户登录', {username: 'Johnny'}) // 

report

在浏览器控制台中输出报告

方法参数

无

返回

无

示例代码

import { Timing } from 'common-vue3-utils' // 或gzpost-desktop-for-vue3

Timing.instance('test').report() // 输出报告，在控制台查看

Validator

通用格式或类型验证实用工具类

isEmptyObject

是否空对象

方法参数

返回

boolean

示例代码

import { Validator } from 'common-vue3-utils'

console.log(Validator.isEmptyObject({})) // true
console.log(Validator.isEmptyObject({a : 1})) // false

isNumeric

是否合法整数，如果是合法数字，将转换成整数返回

方法参数

返回

number: 当val为非0的其它数字 NaN: 当val不是数字 true: 当val是0 因此可以简单判断if(Validator.isNumeric(val))即可

示例代码

import { Validator } from 'common-vue3-utils'

console.log(Validator.isNumeric('a')) // NaN
console.log(Validator.isNumeric('1')) // 1
console.log(Validator.isNumeric('-1.1')) // -1
console.log(Validator.isNumeric('0')) // true

isString

是否是字符串

方法参数

返回

boolean

示例代码

import { Validator } from 'common-vue3-utils'

console.log(Validator.isString('a')) // true
console.log(Validator.isString(1)) // false
console.log(Validator.isString(true)) // false
console.log(Validator.isString({a: 1})) // false

isObject

是否是对象

方法参数

返回

boolean

示例代码

import { Validator } from 'common-vue3-utils'

console.log(Validator.isObject({ a: 1 })) // true
console.log(Validator.isObject(1)) // false
console.log(Validator.isObject([{ a: 1 }])) // false
console.log(Validator.isObject(true)) // false

isArray

是否是数组

方法参数

返回

boolean

示例代码

import { Validator } from 'common-vue3-utils'

console.log(Validator.isArray({ a: 1 })) // false
console.log(Validator.isArray(1)) // false
console.log(Validator.isArray([{ a: 1 }])) // true
console.log(Validator.isArray(true)) // false

isMobile

是否是手机

方法参数

返回

boolean

示例代码

import { Validator } from 'common-vue3-utils'

console.log(Validator.isMobile('13022120391')) // true
console.log(Validator.isMobile('12023123391')) // false

isTel

是否是固话

方法参数

返回

boolean

示例代码

import { Validator } from 'common-vue3-utils'

console.log(Validator.isTel('13022120391')) // false
console.log(Validator.isTel('02099182212')) // true
console.log(Validator.isTel('0755-10209932')) // true

isAlphabetChinese

是否只包含中文或英文字符

方法参数

返回

boolean

示例代码

import { Validator } from 'common-vue3-utils'

console.log(Validator.isAlphabetChinese('你好，')) // false
console.log(Validator.isAlphabetChinese('aaa')) // true
console.log(Validator.isAlphabetChinese('你好aaa')) // true
console.log(Validator.isAlphabetChinese('12023123391')) // false

isAlphabetNumberChinese

是否只包含中文或英文字符及数字

方法参数

返回

boolean

示例代码

import { Validator } from 'common-vue3-utils'

console.log(Validator.isAlphabetNumberChinese('你好，')) // false
console.log(Validator.isAlphabetNumberChinese('aaa')) // true
console.log(Validator.isAlphabetNumberChinese('你好aa111a')) // true
console.log(Validator.isAlphabetNumberChinese('12023123391')) // true

isIDCard

是否合法的身份证号码

方法参数

返回

boolean

示例代码

import { Validator } from 'common-vue3-utils'

console.log(Validator.isIDCard('你好，')) // false
console.log(Validator.isIDCard('110101200007286907')) // true

isVehicleNumber

是否合法的车牌号

方法参数

返回

boolean

示例代码

import { Validator } from 'common-vue3-utils'

console.log(Validator.isVehicleNumber('你好，')) // false
console.log(Validator.isVehicleNumber('粤A99109')) // true

isEmail

是否合法的电子邮箱地址

方法参数

返回

boolean

示例代码

import { Validator } from 'common-vue3-utils'

console.log(Validator.isEmail('你好，')) // false
console.log(Validator.isEmail('admin@test.com')) // true

isURL

是否合法的电子邮箱地址

方法参数

返回

boolean

示例代码

import { Validator } from 'common-vue3-utils'

console.log(Validator.isURL('你好，')) // false
console.log(Validator.isURL('http://test.com/sdj')) // true

authPasswd

验证密码强度

方法参数

返回

string pw-empty: 完全不符合强度要求 pw-weak: 弱密码 pw-medium: 中等强度 pw-fine: 强度偏好 pw-good: 强度最好

示例代码

import { Validator } from 'common-vue3-utils'

console.log(Validator.authPasswd('123456')) // pw-empty
console.log(Validator.authPasswd('12345678')) // pw-weak
console.log(Validator.authPasswd('abc122029')) // pw-medium
console.log(Validator.authPasswd('JKSDJK@1002')) // pw-fine
console.log(Validator.authPasswd('Wknm@2029')) // pw-good