业务工具函数

@erp/biz 提供的业务相关工具函数，专注于 ERP 系统常见的业务场景。

功能分类

图片处理 - comer / downloadImageByUrl / copyImageByUrl
URL 处理 - getUrlParam / getUrlParamObject / parseUrlParam
资源加载 - loadScript / loadCss
格式化 - formatKB / numberToChinese
ID 生成 - s4 / s8
DOM 操作 - getCursorPosition / setCaret / addCssClass
拖拽 - getDraggableProps

引入方式

typescript

import { 
  compressImg, 
  loadScript, 
  loadCss,
  getUrlParam, 
  getUrlParamObject,
  parseUrlParam,
  downloadImageByUrl, 
  copyImageByUrl,
  formatKB, 
  numberToChinese, 
  s4, 
  s8,
  getVideoPoster,
  getFileExtension,
  getDraggableProps
} from '@erp/biz'

图片处理

compressImg

压缩图片 URL（基于阿里云 OSS 图片处理服务）。

typescript

function compressImg(url: string, width?: number, height?: number): string

参数：

参数	类型	默认值	说明
url	string	-	图片 URL
width	number	100	压缩后宽度
height	number	width	压缩后高度

示例：

typescript

// 压缩为 100x100
compressImg('https://oss.example.com/image.jpg')
// => https://oss.example.com/image.jpg?x-oss-process=image/resize,m_lfit,w_100,h_100

// 压缩为 200x150
compressImg('https://oss.example.com/image.jpg', 200, 150)
// => https://oss.example.com/image.jpg?x-oss-process=image/resize,m_lfit,w_200,h_150

// base64 图片不处理
compressImg('data:image/png;base64,...')
// => data:image/png;base64,...

// 已有参数的 URL 不处理
compressImg('https://example.com/image.jpg?v=1')
// => https://example.com/image.jpg?v=1

getVideoPoster

获取视频封面图（基于阿里云 OSS 视频截帧）。

typescript

function getVideoPoster(url: string): string

示例：

typescript

getVideoPoster('https://oss.example.com/video.mp4')
// => https://oss.example.com/video.mp4?x-oss-process=video/snapshot,t_0,f_jpg,m_fast

downloadImageByUrl

下载图片文件到本地。

typescript

function downloadImageByUrl(url: string, fileName?: string): void

参数：

参数	类型	说明
url	string	图片 URL
fileName	string	保存的文件名（可选，默认从 URL 提取）

示例：

typescript

// 使用原文件名
downloadImageByUrl('https://example.com/photo.jpg')

// 指定文件名
downloadImageByUrl('https://example.com/photo.jpg', '我的照片.jpg')

copyImageByUrl

复制图片到剪贴板。

typescript

async function copyImageByUrl(url: string): Promise<void>

示例：

typescript

await copyImageByUrl('https://example.com/image.jpg')
// 成功提示: "图片已复制到剪贴板"

URL 处理

getUrlParam

获取 URL 中指定参数的值。

typescript

function getUrlParam(name: string, url?: string): string | null

参数：

参数	类型	说明
name	string	参数名
url	string	URL 字符串（可选，默认 location.href）

示例：

typescript

// URL: https://example.com?id=123&name=test

getUrlParam('id')      // => '123'
getUrlParam('name')    // => 'test'
getUrlParam('other')   // => null

// 指定 URL
getUrlParam('page', 'https://example.com?page=2')  // => '2'

// 自动解码
// URL: https://example.com?name=%E5%BC%A0%E4%B8%89
getUrlParam('name')    // => '张三'

getUrlParamObject

获取 URL 中所有参数，返回对象。

typescript

function getUrlParamObject(url?: string): Record<string, string>

示例：

typescript

// URL: https://example.com?id=123&name=test&page=1

getUrlParamObject()
// => { id: '123', name: 'test', page: '1' }

// 指定 URL
getUrlParamObject('https://example.com?a=1&b=2')
// => { a: '1', b: '2' }

parseUrlParam

将对象转换为 URL 查询字符串。

typescript

function parseUrlParam(obj: object): string

示例：

typescript

parseUrlParam({ id: 123, name: 'test' })
// => 'id=123&name=test'

parseUrlParam({ keyword: '搜索关键词', page: 1 })
// => 'keyword=%E6%90%9C%E7%B4%A2%E5%85%B3%E9%94%AE%E8%AF%8D&page=1'

// 拼接完整 URL
const params = parseUrlParam({ id: 1, type: 'detail' })
const url = `https://example.com/api?${params}`
// => https://example.com/api?id=1&type=detail

资源加载

loadScript

动态加载 JavaScript 脚本文件。

typescript

function loadScript(url: string, attr?: Record<string, string>): Promise<boolean>

参数：

参数	类型	说明
url	string	脚本 URL
attr	object	script 标签属性（可选）

示例：

typescript

// 加载脚本
await loadScript('https://cdn.example.com/lib.js')

// 带属性
await loadScript('https://cdn.example.com/lib.js', {
  'data-id': '123',
  'crossorigin': 'anonymous'
})

// 加载多个脚本
await Promise.all([
  loadScript('https://cdn.example.com/lib1.js'),
  loadScript('https://cdn.example.com/lib2.js')
])

loadCss

动态加载 CSS 样式文件。

typescript

function loadCss(src: string): Promise<void>

示例：

typescript

await loadCss('https://cdn.example.com/style.css')

格式化

formatKB

格式化文件大小，自动转换单位。

typescript

function formatKB(
  value: number, 
  precision?: number, 
  isObject?: boolean,
  base?: number
): string | { unit: string; value: number; number: number }

参数：

参数	类型	默认值	说明
value	number	-	文件大小（KB）
precision	number	2	小数精度
isObject	boolean	false	是否返回对象
base	number	1024	进制

示例：

typescript

formatKB(512)          // => '512KB'
formatKB(1024)         // => '1MB'
formatKB(1536)         // => '1.5MB'
formatKB(1048576)      // => '1GB'
formatKB(1073741824)   // => '1TB'

// 指定精度
formatKB(1536, 1)      // => '1.5MB'
formatKB(1536, 0)      // => '2MB'

// 返回对象
formatKB(1536, 2, true)
// => { unit: 'MB', value: 1.5, number: 1.5, settle: 1024 }

numberToChinese

阿拉伯数字转中文数字。

typescript

function numberToChinese(num: number): string

示例：

typescript

numberToChinese(0)     // => '零'
numberToChinese(1)     // => '一'
numberToChinese(10)    // => '十'
numberToChinese(11)    // => '十一'
numberToChinese(21)    // => '二十一'
numberToChinese(100)   // => '一百'
numberToChinese(123)   // => '一百二十三'
numberToChinese(1000)  // => '一千'
numberToChinese(10000) // => '一万'

ID 生成

s4

生成 4 位随机 ID。

typescript

function s4(): string

示例：

typescript

s4()  // => 'a1b2'
s4()  // => 'f3e9'

s8

生成 8 位随机 ID。

typescript

function s8(): string

示例：

typescript

s8()  // => 'a1b2c3d4'
s8()  // => 'f3e9d8c7'

// 生成唯一 key
const items = data.map(item => ({
  ...item,
  key: s8()
}))

文件处理

getFileExtension

获取文件扩展名。

typescript

function getFileExtension(url: string): string

示例：

typescript

getFileExtension('https://example.com/file.pdf')   // => 'pdf'
getFileExtension('https://example.com/image.PNG')  // => 'png'
getFileExtension('https://example.com/doc.docx')   // => 'docx'
getFileExtension('https://example.com/noext')      // => ''

DOM 操作

getCursorPosition

获取输入框中光标的位置。

typescript

function getCursorPosition(node: HTMLElement): number | undefined

示例：

typescript

const input = document.querySelector('input')
const pos = getCursorPosition(input)
console.log('光标位置:', pos)

setCaret

设置输入框中光标的位置。

typescript

function setCaret(node: HTMLElement, caret: number): void

示例：

typescript

const input = document.querySelector('input')
setCaret(input, 5)  // 将光标移动到第5个字符后

addCssClass / removeCssClass

添加或移除 CSS 类名。

typescript

function addCssClass(element: HTMLElement, className: string): HTMLElement
function removeCssClass(element: HTMLElement, className: string): void

示例：

typescript

addCssClass(element, 'active')
addCssClass(element, 'class1 class2')  // 支持多个类名

removeCssClass(element, 'active')

addOrRemoveCssClass

根据条件添加或移除 CSS 类名。

typescript

function addOrRemoveCssClass(
  element: HTMLElement, 
  className: string, 
  addOrRemove?: boolean
): void

示例：

typescript

addOrRemoveCssClass(element, 'active', true)   // 添加
addOrRemoveCssClass(element, 'active', false)  // 移除

// 根据状态切换
addOrRemoveCssClass(element, 'selected', isSelected)

loadTemplate

将 HTML 字符串转换为 DOM 元素。

typescript

function loadTemplate(template: string): HTMLElement

示例：

typescript

const el = loadTemplate('<div class="card"><span>内容</span></div>')
document.body.appendChild(el)

拖拽

getDraggableProps

获取通用拖拽事件处理器。

typescript

function getDraggableProps(
  handle: string, 
  callback: (from: HTMLElement, to: HTMLElement) => void
): {
  onDragstart: (evt: DragEvent) => void
  onDragend: (evt: DragEvent) => void
  onDragover: (evt: DragEvent) => void
  onDragleave: (evt: DragEvent) => void
  onDrag: (evt: DragEvent) => void
  onMousedown: (evt: MouseEvent) => void
}

参数：

参数	类型	说明
handle	string	拖拽手柄选择器
callback	function	拖拽完成回调

示例：

vue

<template>
  <div 
    v-for="item in list"
    :key="item.id"
    v-bind="dragProps"
  >
    <span class="drag-handle">⋮⋮</span>
    {{ item.name }}
  </div>
</template>

<script setup>
import { getDraggableProps } from '@erp/biz'

const dragProps = getDraggableProps('.drag-handle', (from, to) => {
  // 处理排序逻辑
  const fromIndex = getIndex(from)
  const toIndex = getIndex(to)
  moveItem(fromIndex, toIndex)
})
</script>

常量

typescript

import { AssetsServer } from '@erp/biz'

// 静态资源服务器地址
AssetsServer  // => '//static.erp.91spyc.com/assets'

第三方库加载

initVideoPlugin

初始化视频播放器插件（MuiPlayer）。

typescript

import { initVideoPlugin } from '@erp/biz'

// 加载视频播放器所需资源
await initVideoPlugin()

// 然后可以使用 MuiPlayer
const player = new MuiPlayer({
  container: '#video-container',
  src: 'https://example.com/video.mp4'
})

Form 动态表单

SearchForm 查询表单

Table 数据表格

业务工具函数

引入方式

图片处理

compressImg

getVideoPoster

downloadImageByUrl

copyImageByUrl

URL 处理

getUrlParam

getUrlParamObject

parseUrlParam

资源加载

loadScript

loadCss

格式化

formatKB

numberToChinese

ID 生成

s4

s8

文件处理

getFileExtension

DOM 操作

getCursorPosition

setCaret

addCssClass / removeCssClass

addOrRemoveCssClass

loadTemplate

拖拽

getDraggableProps

常量

第三方库加载

initVideoPlugin

业务工具函数 ​

引入方式 ​

图片处理 ​

compressImg ​

getVideoPoster ​

downloadImageByUrl ​

copyImageByUrl ​

URL 处理 ​

getUrlParam ​

getUrlParamObject ​

parseUrlParam ​

资源加载 ​

loadScript ​

loadCss ​

格式化 ​

formatKB ​

numberToChinese ​

ID 生成 ​

s4 ​

s8 ​

文件处理 ​

getFileExtension ​

DOM 操作 ​

getCursorPosition ​

setCaret ​

addCssClass / removeCssClass ​

addOrRemoveCssClass ​

loadTemplate ​

拖拽 ​

getDraggableProps ​

常量 ​

第三方库加载 ​

initVideoPlugin ​

业务工具函数

引入方式

图片处理

compressImg

getVideoPoster

downloadImageByUrl

copyImageByUrl

URL 处理

getUrlParam

getUrlParamObject

parseUrlParam

资源加载

loadScript

loadCss

格式化

formatKB

numberToChinese

ID 生成

s4

s8

文件处理

getFileExtension

DOM 操作

getCursorPosition

setCaret

addCssClass / removeCssClass

addOrRemoveCssClass

loadTemplate

拖拽

getDraggableProps

常量

第三方库加载

initVideoPlugin