muzhiyu-ui 1.0.0

package/utils/index.js

@@ -0,0 +1,600 @@
+/**
+ * MuZhiYu UI 全局核心工具函数库 (Unified Utility Collection)
+ * 涵盖网络请求、表单正则校验、剪贴板读写、颜色 HEX/RGB 计算、字符串/日期/金额格式化、深拷贝与防抖节流函数
+ * @author muzhiyu
+ * @version 2.0.0
+ */
+
+import http from './request.js'
+
+/**
+ * 常用基础工具集合 (Utils)
+ */
+export const util = {
+	/**
+	 * 去除字符串首尾空格
+	 * @param {string} value - 待处理的字符串
+	 * @returns {string} 处理后的字符串
+	 */
+	trim(value = '') {
+		return String(value).replace(/(^\s*)|(\s*$)/g, '')
+	},
+
+	/**
+	 * 全局替换字符串中的匹配项
+	 * @param {string} text - 目标文本
+	 * @param {string} search - 需要被替换的查找内容
+	 * @param {string} replacement - 替换后的新文本
+	 * @returns {string} 替换完毕的文本
+	 */
+	replaceAll(text = '', search, replacement) {
+		return String(text).replace(new RegExp(search, 'gm'), replacement)
+	},
+
+	/**
+	 * 手机号码中间 4 位脱敏显示 (例如: 138****5678)
+	 * @param {string|number} num - 手机号码
+	 * @returns {string} 脱敏后的手机号
+	 */
+	maskPhone(num = '') {
+		const str = String(num)
+		return str.length === 11 ? str.replace(/^(\d{3})\d{4}(\d{4})$/, '$1****$2') : str
+	},
+
+	/**
+	 * 金额千分位格式化并保留两位小数 (例如: 1234567.89 -> 1,234,567.89)
+	 * @param {number|string} money - 金额数字
+	 * @returns {string} 格式化后的千分位金额字符串
+	 */
+	formatMoney(money) {
+		const n = parseFloat(money || 0).toFixed(2)
+		return n.replace(/\B(?=(\d{3})+(?!\d))/g, ',')
+	},
+
+	/**
+	 * 日期时间格式化
+	 * @param {string} [format='YYYY-MM-DD HH:mm:ss'] - 目标格式 (支持 YYYY, MM, DD, HH, mm, ss)
+	 * @param {Date|string|number} date - Date 对象、时间戳或日期字符串
+	 * @returns {string} 格式化后的日期字符串
+	 */
+	formatDate(format = 'YYYY-MM-DD HH:mm:ss', date) {
+		if (!date) return ''
+		const d = new Date(date)
+		if (isNaN(d.getTime())) return ''
+		const pad = (n) => (n < 10 ? '0' + n : '' + n)
+		const map = {
+			YYYY: d.getFullYear(),
+			MM: pad(d.getMonth() + 1),
+			DD: pad(d.getDate()),
+			HH: pad(d.getHours()),
+			mm: pad(d.getMinutes()),
+			ss: pad(d.getSeconds())
+		}
+		let result = format
+		for (const [key, val] of Object.entries(map)) {
+			result = result.replace(key, val)
+		}
+		return result
+	},
+
+	/**
+	 * 防抖函数 (连续触发只在停止触发 N 毫秒后执行一次)
+	 * @param {Function} fn - 需要防抖的目标函数
+	 * @param {number} [delay=300] - 延迟时间 (毫秒)
+	 * @returns {Function} 包裹后的防抖函数
+	 */
+	debounce(fn, delay = 300) {
+		let timer = null
+		return function(...args) {
+			if (timer) clearTimeout(timer)
+			timer = setTimeout(() => {
+				fn.apply(this, args)
+			}, delay)
+		}
+	},
+
+	/**
+	 * 节流函数 (连续触发在指定时间间隔内只执行一次)
+	 * @param {Function} fn - 需要节流的目标函数
+	 * @param {number} [interval=300] - 触发间隔 (毫秒)
+	 * @returns {Function} 包裹后的节流函数
+	 */
+	throttle(fn, interval = 300) {
+		let last = 0
+		return function(...args) {
+			const now = Date.now()
+			if (now - last >= interval) {
+				last = now
+				fn.apply(this, args)
+			}
+		}
+	},
+
+	/**
+	 * 对象与数组深拷贝 (递归防止引用污染)
+	 * @param {*} obj - 待深拷贝的目标对象或数组
+	 * @returns {*} 拷贝后的全新对象/数据
+	 */
+	deepClone(obj) {
+		if (obj === null || typeof obj !== 'object') return obj
+		if (obj instanceof Date) return new Date(obj)
+		if (obj instanceof Array) return obj.map(item => util.deepClone(item))
+		const cloned = {}
+		for (const key in obj) {
+			if (Object.prototype.hasOwnProperty.call(obj, key)) {
+				cloned[key] = util.deepClone(obj[key])
+			}
+		}
+		return cloned
+	},
+
+	/**
+	 * 生成带前缀的唯一随机字符串 ID
+	 * @param {string} [prefix='mu'] - ID 前缀
+	 * @returns {string} 唯一 ID 字符串
+	 */
+	uniqueId(prefix = 'mu') {
+		return `${prefix}_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`
+	},
+
+	/**
+	 * 判断当前运行环境是否为 Android (含鸿蒙 HarmonyOS)
+	 * @returns {boolean} 是否为 Android 或 鸿蒙系统
+	 */
+	isAndroid() {
+		const sys = uni.getDeviceInfo ? uni.getDeviceInfo() : uni.getSystemInfoSync()
+		const platform = (sys.platform || '').toLowerCase()
+		return platform === 'android' || platform.includes('harmony') || platform === 'ohos'
+	},
+
+	/**
+	 * 判断当前运行环境是否为 HarmonyOS 鸿蒙系统
+	 * @returns {boolean} 是否为 鸿蒙系统
+	 */
+	isHarmonyOS() {
+		const sys = uni.getDeviceInfo ? uni.getDeviceInfo() : uni.getSystemInfoSync()
+		const platform = (sys.platform || '').toLowerCase()
+		return platform.includes('harmony') || platform === 'ohos'
+	},
+
+	/**
+	 * 判断当前运行环境是否为 iOS
+	 * @returns {boolean} 是否为 iOS 系统
+	 */
+	isIOS() {
+		const sys = uni.getDeviceInfo ? uni.getDeviceInfo() : uni.getSystemInfoSync()
+		const platform = (sys.platform || '').toLowerCase()
+		return platform === 'ios' || platform === 'mac'
+	},
+
+	/**
+	 * JS 命令式触发自定义 `<mu-toast>` 组件 (支持传参开启或传 false 关闭)
+	 * @param {string|boolean|Object} options - 提示文案、选项对象或 boolean (false 代表关闭)
+	 * @param {string} [type='default'] - 图标类型: 'default' | 'success' | 'error' | 'warning' | 'loading'
+	 * @param {number} [duration=2000] - 持续时间 (毫秒)
+	 */
+	toast(options, type = 'default', duration = 2000) {
+		if (options === false) {
+			uni.$emit('mu-toast-hide')
+			return
+		}
+		let payload = {}
+		if (typeof options === 'object' && options !== null) {
+			let iconType = options.type || type
+			if (options.icon) {
+				iconType = (options.icon === 'success') ? 'success' : ((options.icon === 'error' || options.icon === 'fail') ? 'error' : ((options.icon === 'loading') ? 'loading' : 'default'))
+			}
+			payload = {
+				title: options.title || options.text || '',
+				type: iconType,
+				position: options.position || 'center',
+				duration: options.duration || duration
+			}
+		} else {
+			payload = {
+				title: String(options || '提示信息'),
+				type,
+				position: 'center',
+				duration
+			}
+		}
+
+		// 发射全局事件触发页面挂载的 <mu-toast> 组件
+		uni.$emit('mu-toast-show', payload)
+	},
+
+	/**
+	 * JS 命令式触发自定义 `<mu-notify>` 消息通知组件 (支持传参开启或传 false 关闭)
+	 * @param {string|boolean|Object} options - 消息文案、选项对象或 boolean (false 代表关闭)
+	 * @param {string} [type='primary'] - 通知类型: 'primary' | 'success' | 'warning' | 'error'
+	 * @param {number} [duration=3000] - 持续时间 (毫秒)
+	 */
+	notify(options, type = 'primary', duration = 3000) {
+		if (options === false) {
+			uni.$emit('mu-notify-close')
+			return
+		}
+		let payload = {}
+		if (typeof options === 'object' && options !== null) {
+			payload = {
+				message: options.message || options.title || '',
+				type: options.type || type,
+				position: options.position || 'top',
+				duration: options.duration !== undefined ? options.duration : duration,
+				background: options.background || ''
+			}
+		} else {
+			payload = {
+				message: String(options || ''),
+				type,
+				position: 'top',
+				duration
+			}
+		}
+		uni.$emit('mu-notify-show', payload)
+	},
+
+	/**
+	 * JS 命令式触发全屏加载页 `<mu-loading-page>` (支持传参开启或传 false 关闭)
+	 * @param {string|boolean|Object} [options=true] - 加载配置对象、提示文案或 boolean (false 代表关闭)
+	 */
+	loadingPage(options = true) {
+		if (options === false) {
+			uni.$emit('mu-loading-page-hide')
+			return
+		}
+		let payload = {}
+		if (typeof options === 'object' && options !== null) {
+			payload = {
+				text: options.text || options.title || '页面加载中...',
+				subText: options.subText || '',
+				type: options.type || 'logo',
+				layout: options.layout || 'card',
+				image: options.image || '',
+				imageAnimation: options.imageAnimation || 'pulse',
+				color: options.color || '#171717'
+			}
+		} else if (typeof options === 'string') {
+			payload = { text: options, type: 'logo', layout: 'card' }
+		} else {
+			payload = { text: '页面加载中...', type: 'logo', layout: 'card' }
+		}
+		uni.$emit('mu-loading-page-show', payload)
+	},
+
+	/**
+	 * 开启全屏遮罩 Loading
+	 * @param {string} [title='请稍候...'] - 加载提示语
+	 */
+	showLoading(title = '请稍候...') {
+		uni.showLoading({ title, mask: true })
+	},
+
+	/**
+	 * 关闭全屏遮罩 Loading
+	 */
+	hideLoading() {
+		uni.hideLoading()
+	}
+}
+
+/**
+ * 常见正则校验函数对象 (Validator)
+ */
+export const validator = {
+	/**
+	 * 判断值是否为空或未定义 (null / undefined / '')
+	 * @param {*} value - 待校验值
+	 * @returns {boolean} 是否为空
+	 */
+	isNullOrEmpty(value) {
+		return value === null || value === '' || value === undefined
+	},
+
+	/**
+	 * 校验中国大陆 11 位手机号码格式
+	 * @param {string|number} value - 手机号码
+	 * @returns {boolean} 是否合规
+	 */
+	isMobile(value) {
+		return /^(?:1[3-9]\d)\d{5}(\d{3}|\*{3})$/.test(String(value))
+	},
+
+	/**
+	 * 校验电子邮箱地址格式
+	 * @param {string} value - 邮箱地址
+	 * @returns {boolean} 是否合规
+	 */
+	isEmail(value) {
+		return /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/.test(String(value))
+	},
+
+	/**
+	 * 校验中国车牌号 (支持传统燃油车牌 7 位与新能源车牌 8 位)
+	 * @param {string} value - 车牌号码
+	 * @returns {boolean} 是否合规
+	 */
+	isCarNo(value) {
+		const str = String(value)
+		const xreg = /^[京津沪渝冀豫云辽黑湘皖鲁新苏浙赣鄂桂甘晋蒙陕吉闽贵粤青藏川宁琼使领A-Z]{1}[A-Z]{1}(([0-9]{5}[DF]$)|([DF][A-HJ-NP-Z0-9][0-9]{4}$))/
+		const creg = /^[京津沪渝冀豫云辽黑湘皖鲁新苏浙赣鄂桂甘晋蒙陕吉闽贵粤青藏川宁琼使领A-Z]{1}[A-Z]{1}[A-HJ-NP-Z0-9]{4}[A-HJ-NP-Z0-9挂学警港澳]{1}$/
+		return str.length === 7 ? creg.test(str) : str.length === 8 ? xreg.test(str) : false
+	},
+
+	/**
+	 * 校验中国大陆 18 位身份证号码 (带校验码加权校验算法)
+	 * @param {string} value - 身份证号
+	 * @returns {boolean} 是否合规
+	 */
+	isIdCard(value) {
+		const str = String(value)
+		if (str.length === 18) {
+			const arr = str.split('')
+			const W = [7, 9, 10, 5, 8, 4, 2, 1, 6, 3, 7, 9, 10, 5, 8, 4, 2, 1]
+			const V = [1, 0, 10, 9, 8, 7, 6, 5, 4, 3, 2]
+			if (arr[17].toLowerCase() === 'x') arr[17] = 10
+			let sum = 0
+			for (let i = 0; i < 17; i++) sum += W[i] * arr[i]
+			return arr[17] == V[sum % 11]
+		}
+		return false
+	},
+
+	/**
+	 * 校验金额或合法小数格式
+	 * @param {string|number} value - 数值
+	 * @returns {boolean} 是否合规
+	 */
+	isAmount(value) {
+		return /^([0-9]*[.]?[0-9])[0-9]{0,1}$/.test(String(value))
+	},
+
+	/**
+	 * 校验是否全为纯数字
+	 * @param {string|number} value - 文本
+	 * @returns {boolean} 是否为纯数字
+	 */
+	isNum(value) {
+		return /^[0-9]+$/.test(String(value))
+	},
+
+	/**
+	 * 校验 URL 网址格式
+	 * @param {string} value - URL 网址
+	 * @returns {boolean} 是否合法 URL
+	 */
+	isUrl(value) {
+		return /^((https?|ftp|file):\/\/)?([\da-z\.-]+)\.([a-z\.]{2,6})(:[0-9]{1,5})?(\/.*)?$/.test(String(value))
+	}
+}
+
+/**
+ * 校验表单对象数据的主入口函数
+ * @param {Object} formData - 表单数据键值对 { name: '张三' }
+ * @param {Array<Object>} rules - 校验规则配置数组 [{ name: 'name', rule: ['required'], msg: ['请输入姓名'] }]
+ * @returns {string} 如果返回空字符串 '' 说明校验通过；若不通过则返回首个错误提示语
+ */
+export function validate(formData, rules) {
+	for (const item of rules) {
+		const { name, rule = [], msg = [] } = item
+		if (!name || !rule.length || !msg.length) continue
+		const val = formData[name]
+		if (!rule.includes('required') && validator.isNullOrEmpty(val)) continue
+
+		for (let i = 0; i < rule.length; i++) {
+			const ruleName = rule[i]
+			const errorMsg = msg[i]
+			let hasError = false
+			switch (ruleName) {
+				case 'required': hasError = validator.isNullOrEmpty(val); break
+				case 'isMobile': hasError = !validator.isMobile(val); break
+				case 'isEmail': hasError = !validator.isEmail(val); break
+				case 'isIdCard': hasError = !validator.isIdCard(val); break
+				case 'isCarNo': hasError = !validator.isCarNo(val); break
+				case 'isAmount': hasError = !validator.isAmount(val); break
+				case 'isNum': hasError = !validator.isNum(val); break
+				case 'isUrl': hasError = !validator.isUrl(val); break
+			}
+			if (hasError) return errorMsg
+		}
+	}
+	return ''
+}
+
+export const validation = { validate, validator }
+
+/**
+ * 剪贴板读写工具对象 (Clipboard)
+ */
+export const clipboard = {
+	/**
+	 * 复制指定文本到系统剪贴板 (兼容 H5 / 小程序 / App)
+	 * @param {string} data - 需要复制的内容字符串
+	 * @returns {Promise<boolean>} 复制是否成功
+	 */
+	copy(data) {
+		return new Promise((resolve) => {
+			// #ifdef APP-PLUS || MP
+			uni.setClipboardData({
+				data,
+				success() { resolve(true) },
+				fail() { resolve(false) }
+			})
+			// #endif
+
+			// #ifdef H5
+			try {
+				const textarea = document.createElement('textarea')
+				textarea.value = data
+				textarea.style.position = 'fixed'
+				textarea.style.left = '-9999px'
+				document.body.appendChild(textarea)
+				textarea.select()
+				const ok = document.execCommand('copy')
+				document.body.removeChild(textarea)
+				resolve(ok)
+			} catch (e) {
+				if (navigator.clipboard && navigator.clipboard.writeText) {
+					navigator.clipboard.writeText(data).then(() => resolve(true)).catch(() => resolve(false))
+				} else {
+					resolve(false)
+				}
+			}
+			// #endif
+		})
+	},
+
+	/**
+	 * 读取系统剪贴板中的文本内容 (兼容 H5 / 小程序 / App)
+	 * @returns {Promise<string>} 剪贴板中的文本内容
+	 */
+	read() {
+		return new Promise((resolve) => {
+			// #ifdef APP-PLUS || MP
+			uni.getClipboardData({
+				success(res) { resolve(res.data || '') },
+				fail() { resolve('') }
+			})
+			// #endif
+
+			// #ifdef H5
+			if (navigator.clipboard && navigator.clipboard.readText) {
+				navigator.clipboard.readText().then(text => resolve(text)).catch(() => resolve(''))
+			} else {
+				resolve('')
+			}
+			// #endif
+		})
+	}
+}
+
+/**
+ * 颜色进制转换与混合计算工具对象 (Color)
+ */
+export const color = {
+	/**
+	 * RGB 颜色分量转 Hex 十六进制颜色值 (例如: 99, 102, 241 -> #6366F1)
+	 * @param {number} r - 红色分量 (0~255)
+	 * @param {number} g - 绿色分量 (0~255)
+	 * @param {number} b - 蓝色分量 (0~255)
+	 * @returns {string} Hex 格式颜色字符串
+	 */
+	rgbToHex(r, g, b) {
+		const toHex = (n) => {
+			n = Math.max(0, Math.min(255, parseInt(n, 10)))
+			return '0123456789ABCDEF'.charAt((n - n % 16) / 16) + '0123456789ABCDEF'.charAt(n % 16)
+		}
+		return '#' + toHex(r) + toHex(g) + toHex(b)
+	},
+
+	/**
+	 * Hex 十六进制颜色转 RGB 颜色对象 (例如: #6366F1 -> { r: 99, g: 102, b: 241 })
+	 * @param {string} hex - Hex 十六进制颜色值
+	 * @returns {Object|null} { r, g, b } 分量对象
+	 */
+	hexToRgb(hex) {
+		const result = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(hex)
+		return result ? {
+			r: parseInt(result[1], 16),
+			g: parseInt(result[2], 16),
+			b: parseInt(result[3], 16)
+		} : null
+	},
+
+	/**
+	 * 两种颜色按权重比例按混合计算 (常用于渐变色或按压颜色生成)
+	 * @param {string} color1 - 第一种颜色 (#Hex)
+	 * @param {string} color2 - 第二种颜色 (#Hex)
+	 * @param {number} [weight=0.5] - 第一种颜色的占比权重 (0~1)
+	 * @returns {string} 混合后的 rgb(r, g, b) 颜色值
+	 */
+	mix(color1, color2, weight = 0.5) {
+		const c1 = color.hexToRgb(color1)
+		const c2 = color.hexToRgb(color2)
+		if (!c1 || !c2) return color1
+		const r = Math.round(c1.r * weight + c2.r * (1 - weight))
+		const g = Math.round(c1.g * weight + c2.g * (1 - weight))
+		const b = Math.round(c1.b * weight + c2.b * (1 - weight))
+		return `rgb(${r},${g},${b})`
+	}
+}
+
+// 挂载命令式关闭子函数
+util.toast.hide = () => uni.$emit('mu-toast-hide')
+util.toast.close = () => uni.$emit('mu-toast-hide')
+
+util.notify.hide = () => uni.$emit('mu-notify-close')
+util.notify.close = () => uni.$emit('mu-notify-close')
+
+util.loadingPage.hide = () => uni.$emit('mu-loading-page-hide')
+util.loadingPage.close = () => uni.$emit('mu-loading-page-hide')
+
+/**
+ * 全局统一导出核心入口对象 (mu)
+ */
+export const mu = {
+	http,
+	util,
+	validation,
+	clipboard,
+	color,
+
+	// 常用高频函数快捷别名解构
+	toast: util.toast,
+	notify: util.notify,
+	loadingPage: util.loadingPage,
+	showLoading: util.showLoading,
+	hideLoading: util.hideLoading,
+	formatDate: util.formatDate,
+	formatMoney: util.formatMoney,
+	maskPhone: util.maskPhone,
+	debounce: util.debounce,
+	throttle: util.throttle,
+	deepClone: util.deepClone,
+	copy: clipboard.copy,
+	read: clipboard.read,
+	validate,
+	validator,
+
+	/**
+	 * Vue 3 插件式安装主入口 (支持 app.use(MuZhiYuUI, options))
+	 * @param {Object} app - Vue app 实例
+	 * @param {Object} [options={}] - 插件选项 (含 baseURL, requestInterceptor, responseInterceptor)
+	 */
+	install(app, options = {}) {
+		if (options.baseURL) {
+			http.setBaseURL(options.baseURL)
+		}
+		if (typeof options.requestInterceptor === 'function') {
+			http.interceptors.request.use(options.requestInterceptor)
+		}
+		if (typeof options.responseInterceptor === 'function') {
+			http.interceptors.response.use(options.responseInterceptor)
+		}
+
+		app.config.globalProperties.$mu = mu
+		if (typeof uni !== 'undefined') {
+			uni.$mu = mu
+			uni.$toast = mu.toast
+			uni.showToast = function(opts) {
+				mu.toast(opts)
+			}
+			uni.hideToast = function() {
+				uni.$emit('mu-toast-hide')
+			}
+		}
+	}
+}
+
+if (typeof uni !== 'undefined') {
+	uni.$mu = mu
+	uni.$toast = mu.toast
+	uni.showToast = function(opts) {
+		mu.toast(opts)
+	}
+	uni.hideToast = function() {
+		uni.$emit('mu-toast-hide')
+	}
+}
+
+export default mu