# API 详细说明

# 基础函数

# auth

描述：权限控制组件显示隐藏

参数：

data (Array)：需要权限的字符串数组
store (Object)：可选的Pinia store实例，如果未提供则尝试从uni.$store获取

返回值：

Boolean：是否有权限显示组件

示例：

// 在组件中使用
import { auth } from '@/libs/func'

export default {
  methods: {
    checkPermission() {
      // 检查是否有 'admin' 或 'editor' 权限
      const hasPermission = auth(['admin', 'editor'])
      return hasPermission
    }
  }
}

# isArray

描述：判断是否为数组

参数：

arr (Any)：需要判断的值

返回值：

Boolean：是否为数组

示例：

isArray([1, 2, 3]) // true
isArray('abc') // false

# deepClone

描述：深度克隆对象

参数：

obj (Any)：需要克隆的对象

返回值：

Any：克隆后的对象

示例：

const original = { name: 'test', nested: { value: 1 } }
const cloned = deepClone(original)
cloned.nested.value = 2
console.log(original.nested.value) // 1

# deepMerge

描述：深度合并对象

参数：

target (Object)：目标对象
source (Object)：源对象

返回值：

Object：合并后的对象

示例：

const target = { name: 'test', nested: { value: 1 } }
const source = { age: 20, nested: { value: 2 } }
const merged = deepMerge(target, source)
console.log(merged) // { name: 'test', age: 20, nested: { value: 2 } }

# random

描述：生成指定范围内的随机整数

参数：

min (Number)：最小值
max (Number)：最大值

返回值：

Number：随机整数

示例：

random(1, 10) // 生成1-10之间的随机整数

# sys

描述：获取系统信息同步接口

参数：无

返回值：

Object：系统信息对象

示例：

const systemInfo = sys()
console.log(systemInfo.platform) // 输出当前平台

# getPx

描述：获取用户传递值的px值

参数：

value (Number|String)：用户传递的值
unit (Boolean)：是否返回单位，默认false

返回值：

Number|String：处理后的像素值

示例：

getPx(100) // 100
getPx('100rpx') // 转换后的px值
getPx('100px', true) // '100px'

# range

描述：数值范围限制

参数：

min (Number)：最小值，默认0
max (Number)：最大值，默认0
value (Number)：需要限制的值，默认0

返回值：

Number：限制在范围内的值

示例：

range(0, 100, 150) // 100
range(0, 100, -50) // 0
range(0, 100, 50) // 50

# uuid

描述：生成UUID

参数：

len (Number)：指定长度，默认0（生成标准UUID）

返回值：

String：生成的UUID

示例：

uuid() // 生成标准UUID
uuid(10) // 生成10位随机字符串

# setClipboardData

描述：设置剪贴板内容

参数：

data (Any)：需要复制的内容

返回值：无

示例：

setClipboardData('复制的内容') // 复制内容到剪贴板并显示提示

# $parent

描述：获取父组件的参数

参数：

name (String|undefined)：父组件的参数名，默认为undefined（查找最顶层父组件）

返回值：

Object|Boolean：找到的父组件实例或false

示例：

// 在子组件中
const parentComponent = this.$parent('ParentComponentName')
if (parentComponent) {
  // 使用父组件的方法或属性
  parentComponent.someMethod()
}

# addStyle

描述：样式转换，对象转字符串或字符串转对象

参数：

customStyle (Object|String)：需要转换的样式
target (String)：转换目标，'object' 或 'string'，默认'object'

返回值：

Object|String：转换后的样式

示例：

// 对象转字符串
const styleObj = { fontSize: '14px', color: 'red' }
const styleStr = addStyle(styleObj, 'string') // 'font-size:14px;color:red;'

// 字符串转对象
const styleStr = 'font-size:14px;color:red;'
const styleObj = addStyle(styleStr, 'object') // { fontSize: '14px', color: 'red' }

# addUnit

描述：添加单位

参数：

value (Any)：需要添加单位的值，默认'auto'

返回值：

String：添加单位后的值

示例：

addUnit(100) // '100rpx'
addUnit('100px') // '100px'
addUnit('auto') // 'auto'

# trim

描述：去除空格

参数：

str (String)：需要去除空格的字符串
pos (String)：去除空格的位置，'both'（左右）、'left'、'right'、'all'，默认'both'

返回值：

String：去除空格后的字符串

示例：

trim('  test  ') // 'test'
trim('  test  ', 'left') // 'test  '
trim('  test  ', 'right') // '  test'
trim('  t e s t  ', 'all') // 'test'

# sleep

描述：延时函数

参数：

value (Number)：延时时间（毫秒），默认30

返回值：

Promise：Promise对象

示例：

// 异步使用
async function test() {
  console.log('开始')
  await sleep(1000)
  console.log('1秒后执行')
}

# queryRect

描述：查询DOM元素信息

参数：

selector (String)：DOM节点选择器
that (Object)：组件实例（Vue 3中需要特殊处理）
all (Boolean)：是否查找全部，默认false
timeout (Number)：超时时间（毫秒），默认3000

返回值：

Promise：包含DOM元素信息的Promise

示例：

// 查询单个元素
queryRect('.test').then(rect => {
  console.log(rect) // { bottom: 100, height: 50, left: 0, right: 200, top: 50, width: 200 }
})

// 查询多个元素
queryRect('.item', null, true).then(rects => {
  console.log(rects.length) // 匹配到的元素数量
})

# reImgUrl

描述：处理图片URL，判断是否为网络图片或本地图片

参数：

url (String)：图片URL

返回值：

String|Object：处理后的图片URL或require对象

示例：

reImgUrl('https://example.com/image.jpg') // 'https://example.com/image.jpg'
reImgUrl('/static/image.png') // require('/static/image.png')

# hasClass

描述：判断是否存在指定class

参数：

uiClass (String)：元素的class字符串
className (String)：需要判断的class名称

返回值：

Boolean：是否存在指定class

示例：

hasClass('class1 class2', 'class1') // false（注意：该函数返回的是不存在的结果，需要取反使用）
!hasClass('class1 class2', 'class1') // true

# toBack

描述：返回上一页

参数：无

返回值：无

示例：

toBack() // 返回上一页

# audioPlay

描述：播放音频

参数：

src (String)：音频文件路径

返回值：无

示例：

audioPlay('https://example.com/audio.mp3') // 播放指定音频

# getMaxPages

描述：获取总分页数

参数：

total (Number)：总数据条数
limit (Number)：每页数据条数

返回值：

Number：总分页数

示例：

getMaxPages(100, 10) // 10
getMaxPages(101, 10) // 11

# formatRichText

描述：格式化富文本，控制小程序中图片大小

参数：

html (String)：富文本内容

返回值：

String|null：格式化后的富文本或null

示例：

const richText = '<p>测试内容</p><img src="https://example.com/image.jpg" style="width: 500px;">' 
const formatted = formatRichText(richText) // 格式化后的富文本，图片会添加max-width:100%等样式

# getSystemInfoSync

描述：获取系统信息同步接口

参数：无

返回值：

Object：系统信息对象

示例：

const systemInfo = getSystemInfoSync()
console.log(systemInfo.platform) // 输出当前平台

# findParentComponent

描述：递归循环获取上级指定组件

参数：

_this (Object)：当前组件实例
componentName (String)：要查找的组件名称

返回值：

Object|undefined：找到的组件实例或undefined

示例：

// 在子组件中查找名为 'ParentComponent' 的父组件
const parent = findParentComponent(this, 'ParentComponent')
if (parent) {
  parent.someMethod()
}

# 防抖节流

# debounce

描述：防抖函数，一定时间内只有最后一次操作，再过wait毫秒后才执行函数

参数：

func (Function)：要执行的回调函数
wait (Number)：延时时间（毫秒），默认500
immediate (Boolean)：是否立即执行，默认false

返回值：无

示例：

// 输入框防抖
const debouncedSearch = debounce((keyword) => {
  // 执行搜索操作
  console.log('搜索:', keyword)
}, 300)

// 在输入事件中调用
inputHandler(keyword) {
  debouncedSearch(keyword)
}

# throttle

描述：节流函数，在一定时间内只能触发一次

参数：

func (Function)：要执行的回调函数
wait (Number)：延时时间（毫秒），默认500
immediate (Boolean)：是否立即执行，默认true

返回值：无

示例：

// 滚动事件节流
const throttledScroll = throttle(() => {
  // 执行滚动操作
  console.log('滚动中...')
}, 100)

// 在滚动事件中调用
scrollHandler() {
  throttledScroll()
}

# 路由

# route

描述：路由跳转

参数：

config (Object)：路由配置对象
- url (String)：跳转URL
- type (String)：跳转类型，可选值：'redirectTo'、'switchTab'、'reLaunch'、'navigateBack'，默认'navigateTo'
- delta (Number)：返回的页面数，仅当type为'navigateBack'时有效
- animationType (String)：动画类型，默认'pop-in'
- animationDuration (Number)：动画时长，默认300

返回值：无

示例：

// 普通跳转
route({ url: '/pages/detail?id=1' })

// 重定向
route({ url: '/pages/login', type: 'redirectTo' })

// 切换tab
route({ url: '/pages/index', type: 'switchTab' })

// 返回上一页
route({ type: 'navigateBack', delta: 1 })

# 验证函数

# email

描述：验证电子邮箱格式

参数：

value (String)：需要验证的邮箱地址

返回值：

Boolean：是否为有效邮箱

示例：

email('test@example.com') // true
email('invalid-email') // false

# mobile

描述：验证手机号格式

参数：

value (String)：需要验证的手机号

返回值：

Boolean：是否为有效手机号

示例：

mobile('13812345678') // true
mobile('12345678901') // false

# url

描述：验证URL格式

参数：

value (String)：需要验证的URL

返回值：

Boolean：是否为有效URL

示例：

url('https://example.com') // true
url('invalid-url') // false

# date

描述：验证日期格式

参数：

value (String|Number)：需要验证的日期

返回值：

Boolean：是否为有效日期

示例：

date('2023-01-01') // true
date('invalid-date') // false
date(1672531200000) // true（时间戳）

# number

描述：验证十进制数字

参数：

value (String|Number)：需要验证的值

返回值：

Boolean：是否为有效数字

示例：

number(123) // true
number('123.45') // true
number('abc') // false

# idCard

描述：验证身份证号码

参数：

value (String)：需要验证的身份证号码

返回值：

Boolean：是否为有效身份证号码

示例：

idCard('110101199001011234') // true
idCard('invalid-id-card') // false

# carNo

描述：验证车牌号

参数：

value (String)：需要验证的车牌号

返回值：

Boolean：是否为有效车牌号

示例：

carNo('京A12345') // true（旧车牌）
carNo('京AD12345') // true（新能源车牌）
carNo('invalid-car-no') // false

# amount

描述：验证金额，只允许2位小数

参数：

value (String|Number)：需要验证的金额

返回值：

Boolean：是否为有效金额

示例：

amount('123.45') // true
amount('123.456') // false
amount('1,234.56') // true

# empty

描述：判断是否为空

参数：

value (Any)：需要判断的值

返回值：

Boolean：是否为空

示例：

empty('') // true
empty(null) // true
empty(undefined) // true
empty([]) // true
empty({}) // true
empty('test') // false
empty([1, 2, 3]) // false

# image

描述：验证图片格式

参数：

value (String)：需要验证的图片URL

返回值：

Boolean：是否为有效图片格式

示例：

image('https://example.com/image.jpg') // true
image('https://example.com/file.pdf') // false

# video

描述：验证视频格式

参数：

value (String)：需要验证的视频URL

返回值：

Boolean：是否为有效视频格式

示例：

video('https://example.com/video.mp4') // true
video('https://example.com/image.jpg') // false