@mbjia/utils

Package

@mbjia/utils

工具函数包，包含文件处理、URL、时间格式、事件总线、权限判断、上传辅助、并发任务等通用和业务工具。

事件协议上传数据

安装

npm install @mbjia/utils

何时使用

场景	推荐能力
跨组件通信	eventBus
文件名、文件类型、图片信息处理	getFileType、trimFileName、getImageInfo
URL 转换和参数读取	convertToHttps、getUrlParams
上传列表合并、文件类型判断	上传辅助函数和常量
并发任务或队列处理	Loop、WorkerPool、p-limit

主要能力

能力	示例
文件与媒体	getFileType、trimFileName、getVideoCover、checkUploadImageOrVideo
URL	convertToHttps、formatUrl、FIT_IMAGE
时间格式	musicDurationFormatter、videoDurationFormatter
事件	eventBus
权限	userActionsJudge、judgePersonalUser
上传辅助	mergeUploadingAssetsAndAssetList、fileExtensions
并发任务	Loop、WorkerPool、Timer

utils 内容较多，最终使用时建议优先通过 IDE 跳转查看函数签名。

常用函数速查

函数 / 常量	入参	返回值	说明
getFileType	fileName: string	string	获取文件扩展名，包含点号。
trimFileName	fileName: string	string	去掉扩展名后的文件名。
file2base64	file: File	Promise<any>	文件转 base64。
getImgRotation	file: File	Promise<number>	读取图片 EXIF 方向并返回旋转角度。
convertToHttps	url: string	string	将 http:// 转为 https://。
getImageInfo	url: string	Promise<{ success; image?; width?; height? }>	加载图片并返回尺寸。
imageTypeList	-	string[]	支持的图片扩展名。
videoTypeList	-	string[]	支持的视频扩展名。

文件与媒体

名称	入参	返回值	说明
getFileType	fileName: string	string	返回扩展名，包含 .。
trimFileName	fileName: string	string	去掉扩展名。
file2base64	file: File	Promise<any>	文件转 data URL。
getImgRotation	file: File	Promise<number>	读取 EXIF 方向，返回旋转角度。
getVideoInfo	url: string	Promise<{ width; height; duration } | string>	读取视频元信息，5 秒失败兜底。
getAudioInfo	url: string	Promise<{ duration } | string>	读取音频时长，5 秒失败兜底。
isVideo	url: string	boolean	根据扩展名或 data URL 判断视频。
isMusic	url: string	boolean	根据扩展名或 data URL 判断音频。
getVideoCover	file: File	Promise<string>	获取视频第一秒截图；图片文件直接返回 object URL。
getMediaCover	file: File, callback	Promise<string>	生成图片/视频预览图并回调。
isGif	url: string	boolean	判断 gif。
getImageFromUrl	url: string	Promise<File>	从图片 URL 生成 File。
getAudioStatus	file: File, supportExtensions: string[]	Promise<UploadFileType>	校验音频格式、大小和时长。
getVideoInfoByFile	File[] | FileList, preId?	Promise<any[]>	批量读取本地视频文件元信息。

常量：

名称	类型	说明
IMAGE_WIDTHS	number[]	七牛/OSS 图片裁剪可选宽度。
defaultImage	string	默认兜底图片，OEM 站点会使用 OEM 图片。
audioExtensions	string[]	支持音频扩展名。
unSupportVideoCover	string[]	不支持直接生成视频封面的扩展名。
imageTypeList	string[]	图片扩展名。
videoTypeList	string[]	视频扩展名。
imgMimeType / videoMimeType / meidaMimeType / musicMimeType	string[]	文件选择器 MIME 类型。
docMimeType / excleMimeType	string[]	文档和表格 MIME 类型。
fileExtensions	Record<string, string[]>	特殊文件扩展名，如字体、cube。

URL 与图片处理

名称	入参	返回值	说明
convertToHttps	url: string	string	http:// 转 https://。
transformUrlToBlob	url: string	Promise<Blob>	通过 XHR 获取远程文件。
wipeOffQueryString	url: string	string	移除 ? 后的查询参数。
hasWipeOff	url?: string	boolean | string	判断是否包含 ? 或 ! 裁剪信息。
wipeOffPixelInfo	url: string	string	移除末尾 !1080 一类分辨率信息。
addUrlProtocol	url: string	string	给 // 开头地址补 https:。
formatUrl	url: string	string	组合移除 query、移除像素信息、补协议。
FIT_IMAGE	url, width, height?	string	内网资源按最接近宽度拼接图片裁剪后缀。
normalUrl	url: string	string	移除查询参数。
rgb2Hex	color: string	string	RGB 或短 hex 转标准 hex。
dataURLtoBlob	dataurl: string	Blob	data URL 转 Blob。
getCanvasPixelColor	canvas, x, y	{ rgba; rgb; hex; r; g; b; a } | null	获取 canvas 指定像素颜色。
preLoadImage	src, onload?, onerror?	void	预加载图片。

上传与文件选择

名称	入参	返回值	说明
getUploadFileListStatus	files, maxSize?, assetType?	UploadFileType[] | undefined	返回不合规文件列表。
checkUploadImageOrVideo	files, maxSize?, assetType?	File[]	返回合规文件列表。
showPicker	{ mimeType; multiple? }	Promise<File[]>	使用 browser-fs-access 打开文件选择器。
getFileWithHandle	DragEvent	Promise<any>	从拖拽项读取 FileSystem handle。
getFileTypeByMimeType	mimeType: string	{ video; image; audio }	根据 MIME 判断素材类型。
mergeUploadingAssetsAndAssetList	{ uploadingList; assetList }	{ finalUploadingList; finalAssetList }	合并上传中素材和正式素材列表，去重。
generateAssetId	file: File	string	基于文件名、大小、类型生成本地 id。

数据结构：

export type UploadFileType = {
  name: string
  file: File
  status?: 'success' | 'fail'
  reason?: string
}

时间、格式与浏览器

名称	入参	返回值	说明
musicDurationFormatter	seconds: number	string	秒转 mm:ss。
videoDurationFormatter	totalSeconds: number	string	秒转 hh:mm:ss。
formatTimeFromMilliseconds	milliseconds, ratio?	string	微秒/毫秒转 hh:mm:ss，默认按 1000000 换算。
preFixZero	num, length	string	数字前补 0。
convertBit	bit: number	string	bit 转 MB/GB 文案。
checkBrowserSupportVESdk	-	{ WasmSupport; SABSupport; WebcodecSupport; VESdkSupport }	检查 VE SDK 运行能力。
os	-	'windows' | 'mac' | 'linux' | undefined	根据 navigator 判断系统。
isTextEllipsis	box, content	void	监听元素判断文本是否溢出。

请求、并发与定时

名称	入参	返回值	说明
to	Promise	[err, data]	Promise 错误捕获工具。
SendRequest.addRequest	request, limits?, callback?	Promise	限制并发请求。
SendRequestWithTimeOut.addRequest	request, limits?, callback?	Promise	类似 SendRequest，队列继续执行时异步调度。
Timer.addTimer	callback, firstTime?, restTime?, name?	symbol	模拟 interval，可等待前一次执行完成。
Timer.clearTimer	name: symbol	void	清除指定计时器。
Timer.clearAll	-	void	清除所有计时器。
IInterval	typeof Timer	-	Timer 别名。
strictThrottle	func, wait, options?	Function & { cancel }	更严格的节流实现。

业务判断与权限

名称	入参	返回值	说明
isLogin	-	string | undefined	从 Cookie 读取当前 token。
getHostName	-	string	获取当前主域名，第三方站点返回空。
handleJumpOutSide	env, blank	void	按当前环境跳转不同地址。
resetOnLogin	-	void	清理 ORIGIN。
isAliCloudMarketplaceUser	-	boolean	判断阿里云服务市场用户。
isQiniuUser	-	boolean	判断七牛用户。
isJdUser	-	boolean	判断京东用户。
judgePersonalUser	organizeList	boolean	判断是否个人用户。
userActionsJudge	userRightsData	object	从权益数据解析素材、作品、团队字体等操作权限。
PRODUCT_STATUS	ProductStatus	string | undefined	转换作品状态文案。
assetStatus	Record<number, string>	-	素材状态文案。

AI 搜索与素材常量

export enum AI_SEARCH_TYPE {
  LENS = 'lens',
  CAPTIONS = 'captions',
  CONTENT = 'content',
}

export enum AI_SEARCH_RANGE {
  CURRENT_DIR = 'currentDir',
  ALL = 'all',
  PERSONAL = 'personal',
}

名称	说明
AI_SEARCH_TYPE_NONE	无 AI 搜索类型。
searchRangeIsAllOrPersonal(range)	判断搜索范围是否全部或个人。
searchRangeIsAll(range)	判断搜索范围是否全部。
isAiSearch(type)	判断是否 AI 搜索类型。
SearchBarAiSearchAfterOptionsFilter	搜索栏后置选项过滤配置。
homePagePath / landingPagePath	首页和未登录落地页路径。
isDefaultDir(data)	判断素材目录是否默认目录。
getRatioTag(returnValue)	素材比例枚举转展示文案。

其他工具

名称	入参	返回值	说明
forEach	list, callback	void	支持数组或对象遍历。
middleSaveDispatch	dispatch, namespace, data	void	Umi dva save 分发辅助。
generateUUID	-	string	生成 UUID 风格字符串。
getQueryParams	url: string	Record<string, string>	解析 URL query。
getRandomId	-	string	随机 id。
deleteSessionStorageByField	field: string	void	删除 key 包含字段的 sessionStorage。
stopPropagation	event	void	阻止冒泡。
copyToClipboard	text: string	void	复制文本。
dynamicLoading.css/js	path, callback?	void	动态加载 CSS 或 JS。
setupClarity	projectId?	void	初始化 Microsoft Clarity。

低频导出索引

这些导出在业务里出现频率较低，建议先确认已有组件是否已经封装好对应能力。

名称	类型	说明
loop	模块导出	循环/轮询工具模块。
fakeProgress	模块导出	假进度工具模块，常用于等待态。
filterHiddenFile	模块导出	过滤隐藏文件。
getNodeContent	模块导出	获取 DOM 节点内容。
smartSizeCovert	模块导出	智能尺寸转换。
veCache	模块导出	VE 缓存工具。
getAssetActionTypesOptions	模块导出	素材操作类型选项。
fromThirdWebsite	boolean	是否第三方站点。
setTokenName	Function	根据站点来源设置 token cookie key。
USER_INFO / USER / USER_ID	string	用户信息相关存储 key。
GUANGHE_TYPE / FROM	string	渠道/来源相关常量。
isInNet	(url: string) => boolean	判断是否内部资源域名。
VeEnv	class/module	环境判断工具。
unSupportVideoCoverMimeType	string[]	不支持生成视频封面的 MIME 类型。
USER_SOURCE	enum	用户来源枚举，含京东、七牛。
getImageSize	(ratio: number) => string	比例转尺寸枚举。
getLinkAssets / getLinkAssetsByKey	Function	根据素材 link 关系查关联素材。
eqAssetUrl	(originUrl, crtUrl) => boolean	比较素材 URL，忽略视频截图 query。
needAiMat	(materia) => boolean	判断素材是否需要 AI 抠图。
isJSON	(str: string) => boolean	判断字符串是否 JSON。
pipe	(...fns) => Function	管道函数。
isAiSaas	来源于 site-env	AI SaaS 环境判断。
trimmedStr	(value) => string	去掉首尾空格。
timerSym	() => symbol	生成定时器标识。
NotUseMimeType	string[]	使用扩展名而非 MIME 的文件类型。
getExtension	(url: string) => string | null	从 URL 获取扩展名。