354 lines
14 KiB
Markdown
354 lines
14 KiB
Markdown
---
|
||
name: lime-shared 常用函数库
|
||
description: 专为 uni-app / uni-app x 组件开发设计的轻量级工具集，提供验证器、单位转换、DOM 查询、动画过渡、BEM 命名等辅助能力。
|
||
tags:
|
||
- shared
|
||
- 工具
|
||
- BEM
|
||
- 工具函数
|
||
plugin: lime-shared
|
||
category: SDK 工具库
|
||
dependencies: []
|
||
---
|
||
|
||
# lime-shared 常用函数库
|
||
|
||
专为 uni-app / uni-app x 组件开发设计的轻量级工具集，提供验证器、单位转换、图片处理、Canvas、DOM 查询、动画过渡、BEM 命名等高效便捷的辅助能力，全面兼容蒸汽模式（uvue/uts）跨平台编译。
|
||
|
||
> 插件依赖：无
|
||
|
||
## 安装方法
|
||
|
||
1. 在 uni-app 插件市场中搜索并导入 `lime-shared`
|
||
2. 导入后可能需要重新编译项目
|
||
3. 在代码中按需引入所需函数即可使用
|
||
|
||
::: tip 注意🔔
|
||
本插件为函数库，不提供组件标签，仅通过 `import` 方式按需引入工具函数。
|
||
:::
|
||
|
||
## 代码演示
|
||
|
||
### 基础使用
|
||
|
||
按需引入工具函数即可使用，无需全局注册。
|
||
|
||
```js
|
||
// 引入单个函数
|
||
import { addUnit } from '@/uni_modules/lime-shared/addUnit'
|
||
import { classNames } from '@/uni_modules/lime-shared/classNames'
|
||
import { stringifyStyle } from '@/uni_modules/lime-shared/stringifyStyle'
|
||
|
||
// 在组件中使用
|
||
const style = stringifyStyle({ color: 'red', fontSize: '14px' })
|
||
const className = classNames('btn', { 'btn--disabled': true })
|
||
const size = addUnit(100) // '100px'
|
||
```
|
||
|
||
### 验证器使用
|
||
|
||
提供一系列类型与格式验证函数，统一返回布尔值。
|
||
|
||
```js
|
||
import { isNumber } from '@/uni_modules/lime-shared/isNumber'
|
||
import { isEmail } from '@/uni_modules/lime-shared/isEmail'
|
||
import { isURL } from '@/uni_modules/lime-shared/isURL'
|
||
import { isIP } from '@/uni_modules/lime-shared/isIP'
|
||
|
||
isNumber(42) // true
|
||
isNumber('42') // false
|
||
isEmail('a@b.com') // true
|
||
isURL('https://a.com') // true
|
||
isIP('192.168.1.1') // true
|
||
isIP('::1', { version: 6 }) // true
|
||
```
|
||
|
||
### BEM 命名与样式工具
|
||
|
||
配合 `lime-style` 提供扁平化 BEM 类名生成与样式字符串拼接。
|
||
|
||
```js
|
||
import { createBem } from '@/uni_modules/lime-shared/bem'
|
||
import { classNames } from '@/uni_modules/lime-shared/classNames'
|
||
import { stringifyStyle } from '@/uni_modules/lime-shared/stringifyStyle'
|
||
|
||
const bem = createBem('avatar')
|
||
|
||
// 生成 BEM 类名
|
||
bem.b() // 'l-avatar'
|
||
bem.e('icon') // 'l-avatar__icon'
|
||
bem.m('small') // 'l-avatar--small'
|
||
bem.em('icon', 'round') // 'l-avatar__icon--round'
|
||
bem.m('small', true) // 'l-avatar--small'
|
||
bem.ev('icon', ['active', 'border']) // 'l-avatar__icon--active-border'
|
||
|
||
// 合并类名（自动过滤空值）
|
||
const cls = classNames(bem.b(), bem.m('disabled', isDisabled), props.lClass)
|
||
|
||
// 拼接样式字符串（自动过滤 null/undefined）
|
||
const style = stringifyStyle({ color: 'red' }, props.lStyle)
|
||
```
|
||
|
||
### DOM 查询与节点信息
|
||
|
||
跨平台获取节点位置尺寸、查询组件实例。
|
||
|
||
```js
|
||
import { getRect, getAllRect } from '@/uni_modules/lime-shared/getRect'
|
||
import { getCurrentInstance } from 'vue'
|
||
|
||
const instance = getCurrentInstance()
|
||
// 获取单个节点
|
||
getRect('.item', instance).then((rect) => {
|
||
console.log(rect.width, rect.height)
|
||
})
|
||
// 获取多个节点
|
||
getAllRect('.item', instance).then((rects) => {
|
||
console.log(rects.length)
|
||
})
|
||
```
|
||
|
||
### Canvas 异步上下文
|
||
|
||
统一封装不同平台 Canvas 创建逻辑，返回一致的接口。
|
||
|
||
```js
|
||
import { createCanvasContextAsync } from '@/uni_modules/lime-shared/createCanvasContextAsync'
|
||
|
||
const canvas = await createCanvasContextAsync('myCanvas', instance.proxy)
|
||
const ctx = canvas.renderContext
|
||
ctx.fillStyle = '#ff0000'
|
||
ctx.fillRect(0, 0, 100, 100)
|
||
canvas.flush()
|
||
const dataURL = await canvas.toDataURL('image/png', 1.0)
|
||
```
|
||
|
||
### 动画与过渡
|
||
|
||
提供 `raf` 动画帧、`sleep` 延时、`Timeline`/`Animation` 时间轴及 `useTransition` 过渡能力。
|
||
|
||
```js
|
||
import { raf, cancelRaf, doubleRaf } from '@/uni_modules/lime-shared/raf'
|
||
import { sleep } from '@/uni_modules/lime-shared/sleep'
|
||
import { Timeline, Animation } from '@/uni_modules/lime-shared/animation'
|
||
|
||
// 动画帧
|
||
const id = raf(() => console.log('frame'))
|
||
cancelRaf(id)
|
||
|
||
// 延时
|
||
await sleep(300)
|
||
|
||
// 时间轴
|
||
const timeline = new Timeline()
|
||
timeline.add(new Animation(0, 100, 300, 0), 0)
|
||
timeline.start()
|
||
```
|
||
|
||
## API 文档
|
||
|
||
> 以下按功能分类列出全部可用函数。除特别说明外，所有函数均支持 uni-app / uni-app x 跨平台。
|
||
|
||
### 验证器
|
||
|
||
| 函数名 | 路径 | 说明 |
|
||
| --- | --- | --- |
|
||
| `isBase64(str)` | `isBase64` | 判断字符串是否为 Base64 编码 |
|
||
| `isDataURI(str)` | `isBase64` | 判断字符串是否为 Base64 编码的 data URI |
|
||
| `isBoolean(value)` | `isBoolean` | 严格判断值是否为布尔值 |
|
||
| `isByteLength(str, options)` | `isByteLength` | 验证字符串字节长度是否在范围内 |
|
||
| `isDate(input, options)` | `isDate` | 验证字符串或 Date 是否为有效日期 |
|
||
| `isDef(value)` | `isDef` | 检查值是否已定义（非 undefined/null） |
|
||
| `isEmail(email)` | `isEmail` | 验证电子邮件地址格式 |
|
||
| `isEmpty(value)` | `isEmpty` | 判断值是否为空（null/空串/空数组/空对象） |
|
||
| `isFunction(val)` | `isFunction` | 检查值是否为函数类型 |
|
||
| `isIP(ip, options)` | `isIP` | 验证 IP 地址（支持 IPv4/IPv6） |
|
||
| `isNumber(value)` | `isNumber` | 检查值是否为数字类型 |
|
||
| `isNumeric(value)` | `isNumeric` | 检查值是否为数字或可解析为数字的字符串 |
|
||
| `isObject(val)` | `isObject` | 检查值是否为对象类型 |
|
||
| `isPromise(val)` | `isPromise` | 检查值是否为 Promise |
|
||
| `isRegExp(obj)` | `isRegExp` | 检测值是否为正则表达式对象 |
|
||
| `isString(str)` | `isString` | 检查值是否为字符串类型 |
|
||
| `isURL(url, options)` | `isURL` | 综合验证 URL（支持协议白名单、TLD、端口等） |
|
||
| `isValidDomain(str, options)` | `isValidDomain` | 验证字符串是否为合法域名 |
|
||
|
||
### 单位转换
|
||
|
||
| 函数名 | 路径 | 说明 |
|
||
| --- | --- | --- |
|
||
| `addUnit(value, unit='px')` | `addUnit` | 给值添加单位，已含单位则原样返回 |
|
||
| `unitConvert(value, base=0)` | `unitConvert` | 将 rpx/px/% 字符串转换为像素数字 |
|
||
| `parseUnit(value, base=0)` | `unitConvert` | 包装 `unitConvert`，NaN 返回 null |
|
||
| `toNumber(val)` | `toNumber` | 将字符串转换为数字，无法转换返回原值或 null |
|
||
|
||
### 图片处理
|
||
|
||
| 函数名 | 路径 | 说明 |
|
||
| --- | --- | --- |
|
||
| `arrayBufferToFile(buffer, name, format)` | `arrayBufferToFile` | 将 ArrayBuffer 转为临时文件路径 |
|
||
| `base64ToArrayBuffer(base64)` | `base64ToArrayBuffer` | 从 data URI 解析 base64 并转为 ArrayBuffer |
|
||
| `base64ToPath(base64, filename)` | `base64ToPath` | 将 base64 数据转为临时文件路径 |
|
||
| `pathToBase64(path)` | `pathToBase64` | 将文件路径转为 base64 data URI |
|
||
| `exif` | `exif` | 图片 EXIF 信息读取对象（不支持 uni-app x App） |
|
||
| `createImage(canvas)` | `createImage` | 创建用于 canvas 的 Image 对象 |
|
||
|
||
### Canvas
|
||
|
||
| 函数名 | 路径 | 说明 |
|
||
| --- | --- | --- |
|
||
| `canIUseCanvas2d()` | `canIUseCanvas2d` | 判断当前环境是否支持 canvas 2d |
|
||
| `createCanvas(canvasId, component)` | `createCanvas` | 创建 canvas 上下文 |
|
||
| `createCanvasContextAsync(canvasId, component)` | `createCanvasContextAsync` | 异步创建 canvas 上下文，返回统一接口 |
|
||
|
||
### 页面与 DOM
|
||
|
||
| 函数名 | 路径 | 说明 |
|
||
| --- | --- | --- |
|
||
| `getCurrentPage()` | `getCurrentPage` | 返回当前页面实例 |
|
||
| `getRect(selector, context, node)` | `getRect` | 获取单个节点位置尺寸信息 |
|
||
| `getAllRect(selector, context, node)` | `getRect` | 获取所有匹配节点位置尺寸信息 |
|
||
| `getViewportScrollInfo()` | `getRect` | 获取视口滚动条位置信息 |
|
||
| `getScrollIntoViewValue(...)` | `getRect` | 计算元素滚动到可视区域的目标位置 |
|
||
| `getDeviceInfo()` | `getDeviceInfo` | 获取设备信息 |
|
||
| `getWindowInfo()` | `getWindowInfo` | 获取窗口信息 |
|
||
| `selectComponent(selector)` | `selectComponent` | 链式查询器，查找组件实例 |
|
||
| `selectAllComponent(selector, options)` | `selectAllComponent` | 批量选择组件 |
|
||
| `selectElement(selector)` | `selectElement` | 链式 DOM 查询器（uni-app x 专用） |
|
||
| `findClosestElementWithStyle(el, prop)` | `dom` | 向上查找具有指定 style 的祖先元素 |
|
||
|
||
### 动画与延时
|
||
|
||
| 函数名 | 路径 | 说明 |
|
||
| --- | --- | --- |
|
||
| `sleep(delay=300)` | `sleep` | 延时指定毫秒后 resolve 的 Promise |
|
||
| `raf(fn)` | `raf` | 请求动画帧 |
|
||
| `cancelRaf(id)` | `raf` | 取消动画帧 |
|
||
| `doubleRaf(fn)` | `raf` | 双倍动画帧 |
|
||
| `createAnimation(options)` | `createAnimation` | 创建动画对象（NVUE 链式调用） |
|
||
| `Timeline` | `animation` | 动画时间轴类 |
|
||
| `Animation` | `animation` | 单个动画对象类 |
|
||
| `useTransition(source, options)` | `animation/useTransition` | 数值过渡动画 composable |
|
||
|
||
### 数学与数字
|
||
|
||
| 函数名 | 路径 | 说明 |
|
||
| --- | --- | --- |
|
||
| `clamp(val, min, max)` | `clamp` | 将值限制在范围内 |
|
||
| `closest(arr, target)` | `closest` | 在数组中找到最接近目标数字的元素 |
|
||
| `floatAdd(num1, num2)` | `floatAdd` | 浮点数加法（精度修复） |
|
||
| `floatDiv(num1, num2)` | `floatDiv` | 浮点数除法（精度修复） |
|
||
| `floatMul(num1, num2)` | `floatMul` | 浮点数乘法（精度修复） |
|
||
| `floatSub(num1, num2)` | `floatSub` | 浮点数减法（精度修复） |
|
||
| `random(min, max, fixed=0)` | `random` | 生成指定范围内的随机数 |
|
||
| `range(start, end, step=1, fromRight=false)` | `range` | 生成数字范围数组 |
|
||
|
||
### 字符串与数组
|
||
|
||
| 函数名 | 路径 | 说明 |
|
||
| --- | --- | --- |
|
||
| `addSeparator(num, separator=',', digit=3)` | `addSeparator` | 每隔 n 位数字添加分隔符 |
|
||
| `arrayEqual(arr1, arr2)` | `arrayEqual` | 浅比较两个数组是否相等 |
|
||
| `assignAtIndex(arr, index, value)` | `assignAtIndex` | 安全在数组指定索引赋值 |
|
||
| `camelCase(str, isPascalCase=false)` | `camelCase` | 转换为 camelCase 或 PascalCase |
|
||
| `characterLimit(type, char, max)` | `characterLimit` | 按字符/字节计算长度并截断 |
|
||
| `fillArray(length, value)` | `fillArray` | 生成指定长度并用指定值填充的数组 |
|
||
| `fillZero(number, length=2)` | `fillZero` | 在数字前补零至指定长度 |
|
||
| `findLastIndex(array, predicate)` | `findLastIndex` | 兼容版 findLastIndex polyfill |
|
||
| `kebabCase(str, separator='-')` | `kebabCase` | 转换为指定连接符命名 |
|
||
| `shuffle(arr)` | `shuffle` | Fisher-Yates 算法随机打乱数组 |
|
||
| `toArray(item)` | `toArray` | 将单个元素包装为数组 |
|
||
| `toBoolean(value)` | `toBoolean` | 将值转为布尔 |
|
||
|
||
### 对象工具
|
||
|
||
| 函数名 | 路径 | 说明 |
|
||
| --- | --- | --- |
|
||
| `cloneDeep(obj)` | `cloneDeep` | 深度克隆对象/数组 |
|
||
| `coalesce(...values)` | `coalesce` | 返回第一个非空值（保留 0/false） |
|
||
| `hasOwn(obj, key)` | `hasOwn` | 检查对象是否具有指定属性 |
|
||
| `merge(obj, defaults)` | `merge` | 深度合并，用 defaults 填充 obj 的空值 |
|
||
|
||
### BEM 命名与样式
|
||
|
||
| 函数名 | 路径 | 说明 |
|
||
| --- | --- | --- |
|
||
| `createBem` | `bem` | 默认配置 BEM 工厂函数（namespace=`l`） |
|
||
| `createBemStruct(config)` | `bem` | 自定义配置 BEM 工厂函数 |
|
||
| `Bem` | `bem` | BEM 类生成器类 |
|
||
| `classNames(...args)` | `classNames` | 拼接类名字符串，自动过滤空值 |
|
||
| `parseStyle(css)` | `parseStyle` | 将 CSS 字符串转为样式对象 |
|
||
| `stringifyStyle(...args)` | `stringifyStyle` | 拼接样式字符串，自动过滤空值 |
|
||
| `toCssVars(obj, prefix='--l-')` | `stringifyStyle` | 将对象转换为 CSS 自定义属性字符串 |
|
||
|
||
### 平台与杂项
|
||
|
||
| 函数名 | 路径 | 说明 |
|
||
| --- | --- | --- |
|
||
| `getLocalFilePath(path)` | `getLocalFilePath` | 将路径转换为本地绝对路径 |
|
||
| `getPlatform()` | `platform` | 返回当前平台的根对象（wx/my/uni 等） |
|
||
| `obj2url(data, isPrefix=false)` | `obj2url` | 将对象转换为 URL 查询字符串 |
|
||
| `guid(len=32)` | `guid` | 生成指定长度的伪随机字符串 |
|
||
| `uniqid(prefix='lime')` | `uniqid` | 生成带前缀的唯一 ID |
|
||
| `isBrowser` | `isBrowser` | 是否为 Web 环境常量 |
|
||
| `vue` | `vue` | Vue API 重导出（VUE3/VUE2 兼容） |
|
||
|
||
### 省市区数据
|
||
|
||
| 函数名 | 路径 | 说明 |
|
||
| --- | --- | --- |
|
||
| `areaList` | `areaData` | 中国省市区原始数据（province/city/county） |
|
||
| `useCascaderAreaData()` | `areaData` | 转换为级联选择器树形结构 |
|
||
|
||
### 节流防抖
|
||
|
||
| 函数名 | 路径 | 说明 |
|
||
| --- | --- | --- |
|
||
| `debounce(fn, wait=300)` | `debounce` | 防抖函数 |
|
||
| `throttle(func, wait, options)` | `throttle` | 节流函数（支持 leading/trailing） |
|
||
|
||
## Vue2 使用说明
|
||
|
||
插件在 Vue2 项目中通过 `@vue/composition-api` 提供 `computed`、`ref`、`watch` 等组合式 API 能力，需按以下方式配置。
|
||
|
||
关键配置代码（在 main.js 中添加）：
|
||
|
||
```js
|
||
// vue2
|
||
import Vue from 'vue'
|
||
import VueCompositionAPI from '@vue/composition-api'
|
||
Vue.use(VueCompositionAPI)
|
||
```
|
||
|
||
## 快速预览
|
||
|
||
本插件为函数库，不提供可视化演示组件。可直接在任意 uni-app 项目中按需引入函数进行使用。
|
||
|
||
## 插件标签说明
|
||
|
||
| 标签类型 | 示例 | 说明 |
|
||
|---------|------|------|
|
||
| 函数库 | `import { ... } from '@/uni_modules/lime-shared/...'` | 仅通过 import 方式按需引入，无组件标签 |
|
||
|
||
## 文档链接
|
||
|
||
📚 函数库详细文档请访问以下站点：
|
||
- [常用函数库文档 - 站点1](https://limex.qcoon.cn/uts/shared.html)
|
||
- [常用函数库文档 - 站点2](https://limeui.netlify.app/uts/shared.html)
|
||
- [常用函数库文档 - 站点3](https://limeui.familyzone.top/uts/shared.html)
|
||
|
||
## 注意事项
|
||
|
||
1. 本插件为函数库，所有函数均按需引入，无需全局注册
|
||
2. `exif` 图片信息读取不支持 uni-app x App 环境
|
||
3. `createAnimation` 在 uni-app x（uvue）环境下请使用 `lime-animateIt` 插件
|
||
4. `getLocalFilePath` 在 uni-app x（uvue）环境下重新导出为 `getResourcePath`（来自 `lime-file-utils`）
|
||
5. 部分函数在不同平台有不同实现，但导出名称与签名保持一致，无需关心平台差异
|
||
|
||
## 支持与赞赏
|
||
|
||
如果你觉得本插件解决了你的问题，可以考虑支持作者：
|
||
|
||
| 支付宝赞助 | 微信赞助 |
|
||
|------------|------------|
|
||
|  |  |
|