@semi-kit/utils 1.2.3 → 1.2.5

package/lib/axios.d.mts

@@ -1,14 +1,18 @@
 import { ParamsSerializerOptions } from "axios";
 /**
- * @description: 过滤请求参数：null undefined '' {} []
- * @param {object} data  { name: 'Tom', age: null, link: '', address: undefined, items: [], info: {} }
- * @return {*}   { name:'Tom' }
+ * 过滤请求参数中空值
+ * @param data - 需要过滤的数据对象
+ * @returns 过滤后的对象,只保留有效值
+ * @example
+ * useOmitNilRequestParams({ name: 'Tom', age: null, link: '', address: undefined, items: [], info: {} })
+ * -> { name: 'Tom' }
  */
 declare const useOmitNilRequestParams: (data: object) => object;
 /**
- * @description: Axios 参数序列化
- * @param {*} ParamsSerializerOptions
- * @return {*}
+ * Axios 参数序列化配置
+ * @returns Axios 参数序列化选项,数组参数使用 repeat 格式
+ * @example
+ * 参数 { ids: [1, 2, 3] } 会被序列化为 'ids=1&ids=2&ids=3'
  */
 declare const useParamsSerializer: () => ParamsSerializerOptions;
 export { useOmitNilRequestParams, useParamsSerializer };

package/lib/color.d.mts

@@ -1,25 +1,29 @@
 /**
- * 将 Hex 颜色值转换为 RGB 格式
- * @param hex - 十六进制颜色值,例如 '#ffffff' 或 'ffffff'
- * @returns RGB 对象,包含 r、g、b 三个属性
+ * 将 Hex 颜色值转换为 RGB/RGBA 格式
+ * @param hex - 十六进制颜色值,支持 6 位或 8 位格式,例如 '#ffffff'、'ffffff'、'#ffffffFF'
+ * @returns RGB/RGBA 对象,包含 r、g、b 和可选的 a 属性
  * @example
  * hexToRgb('#ff0000') -> { r: 255, g: 0, b: 0 }
+ * hexToRgb('#14443080') -> { r: 20, g: 68, b: 48, a: 0.5 }
  */
 declare const hexToRgb: (hex: string) => {
   r: number;
   g: number;
   b: number;
+  a?: number;
 };
 /**
- * 将 RGB 颜色值转换为 Hex 格式
+ * 将 RGB/RGBA 颜色值转换为 Hex 格式
  * @param r - 红色值 (0-255)
  * @param g - 绿色值 (0-255)
  * @param b - 蓝色值 (0-255)
+ * @param a - 可选的透明度值 (0-1)
  * @returns 十六进制颜色值字符串
  * @example
  * rgbToHex(255, 0, 0) -> '#ff0000'
+ * rgbToHex(20, 68, 48, 0.5) -> '#14443080'
  */
-declare const rgbToHex: (r: number, g: number, b: number) => string;
+declare const rgbToHex: (r: number, g: number, b: number, a?: number) => string;
 /**
  * 随机生成一个 Hex 颜色值
  * @returns 随机的十六进制颜色值字符串

package/lib/color.mjs

@@ -1 +1 @@
-const hexToRgb=e=>{let t=/^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(e);return{r:parseInt(t?.[1]??`0`,16),g:parseInt(t?.[2]??`0`,16),b:parseInt(t?.[3]??`0`,16)}},rgbToHex=(e,t,n)=>`#${((1<<24)+(e<<16)+(t<<8)+n).toString(16).slice(1)}`,randomHex=()=>`#${Math.floor(Math.random()*16777215).toString(16).padEnd(6,`0`)}`;export{hexToRgb,randomHex,rgbToHex};
+const hexToRgb=e=>{let t=/^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})?$/i.exec(e),n={r:parseInt(t?.[1]??`0`,16),g:parseInt(t?.[2]??`0`,16),b:parseInt(t?.[3]??`0`,16)};return t?.[4]?{...n,a:parseInt(t[4],16)/255}:n},rgbToHex=(e,t,n,r)=>{let i=`#${((1<<24)+(e<<16)+(t<<8)+n).toString(16).slice(1)}`;return r===void 0?i:`${i}${Math.round(r*255).toString(16).padStart(2,`0`)}`},randomHex=()=>`#${Math.floor(Math.random()*16777215).toString(16).padEnd(6,`0`)}`;export{hexToRgb,randomHex,rgbToHex};

package/lib/datetime.d.mts

@@ -1,40 +1,70 @@
 import { DateLike } from "@vueuse/core";
 interface FormatDateRangeParamsType {
-  endTimeType?: "now" | "full";
+  endTimeType?: 'now' | 'full';
   format?: string;
 }
+/**
+ * 查找给定日期是一年中的第几天
+ * @param date - 日期对象或可转换为日期的值, 默认为当前日期
+ * @returns 一年中的第几天
+ * @example
+ * getDayOfYear(new Date('2024-01-01')) -> 1
+ * getDayOfYear(new Date('2024-12-31')) -> 366
+ */
 declare const getDayOfYear: (date?: DateLike) => number | undefined;
+/**
+ * 判断给定日期是否是工作日
+ * @param date - 日期对象或可转换为日期的值
+ * @returns 如果是工作日返回 true, 周末返回 false
+ * @example
+ * isWeekday(new Date('2024-12-05')) -> true
+ * isWeekday(new Date('2024-12-07')) -> false
+ */
 declare const isWeekday: (date?: DateLike) => boolean;
 /**
- * @description: 时间转换为标准时间
- * @param {*} name：时间戳
- * @param {*} type：生成时间格式
- * @return {*} 14:25:59
+ * 时间转换为标准时间格式
+ * @param time - 时间戳或日期对象, 默认为当前时间
+ * @param type - 生成时间格式, 默认为 'HH:mm:ss'
+ * @returns 格式化后的时间字符串
+ * @example
+ * useFormatTime(new Date()) -> '14:25:59'
+ * useFormatTime(1638345600000, 'HH:mm') -> '14:25'
  */
 declare const useFormatTime: (time?: DateLike, type?: string) => string;
 /**
- * @description: 时间转换为标准日期
- * @param {*} name：时间
- * @param {*} type：生成时间格式
- * @return {*}  2022-11-09
+ * 时间转换为标准日期格式
+ * @param time - 时间戳或日期对象, 默认为当前时间
+ * @param type - 生成日期格式, 默认为 'YYYY-MM-DD'
+ * @returns 格式化后的日期字符串
+ * @example
+ * useFormatDate(new Date()) -> '2022-11-09'
+ * useFormatDate(1638345600000, 'YYYY/MM/DD') -> '2021/12/01'
  */
 declare const useFormatDate: (time?: DateLike, type?: string) => string;
 /**
- * @description: 日期时间 -> 日期时间请求参数
- * @param {string} timestamp：时间数据
- * @param {*} field：日期时间字段名称
- * @param {*} start：开始字段名称
- * @param {*} end：结束字段名称
- * @return {*}
+ * 将日期时间范围转换为请求参数格式
+ * @param timestamp - 时间范围数组 [开始时间, 结束时间]
+ * @param field - 原日期时间字段名称, 默认为 'timestamp'
+ * @param start - 开始时间字段名称, 默认为 'startTime'
+ * @param end - 结束时间字段名称, 默认为 'endTime'
+ * @returns 包含开始和结束时间的对象, 原字段设为 undefined
+ * @example
+ * useFormatDateTimeParams(['2024-01-01', '2024-12-31'])
+ * -> { timestamp: undefined, startTime: '2024-01-01', endTime: '2024-12-31' }
  */
 declare const useFormatDateTimeParams: (timestamp: string[] | null | undefined, field?: string, start?: string, end?: string) => {
   [x: string]: string | undefined;
 } | undefined;
 /**
- * @description: 转换为标准时间范围
- * @param {*} day 往前推*天数
- * @param {FormatDateRangeParamsType}
- * @return {*}
+ * 生成标准时间范围
+ * @param day - 往前推的天数, 默认为 7 天
+ * @param options - 配置选项
+ * @param options.endTimeType - 结束时间类型: 'full' 表示当天结束时刻, 'now' 表示当前时刻
+ * @param options.format - 时间格式,默认为 'YYYY-MM-DD HH:mm:ss'
+ * @returns 时间范围数组 [开始时间, 结束时间]
+ * @example
+ * useFormatDateRange(7) -> ['2024-11-28 00:00:00', '2024-12-05 23:59:59']
+ * useFormatDateRange(3, { endTimeType: 'now' }) -> ['2024-12-02 00:00:00', '2024-12-05 14:30:00']
  */
 declare const useFormatDateRange: (day?: number, {
   endTimeType,

package/lib/extra.d.mts

@@ -7,6 +7,10 @@
  * useOmitExtraParams({ a: 1, b: 2, c: 3 }, { a: 1 })
  */
 declare const useOmitExtraParams: (sourceData: object, targetData: object) => Pick<object, never>;
-/** 占位符, 表示未定义 */
+/**
+ * 占位符常量,表示未定义的值
+ * @example
+ * const value = __ // undefined
+ */
 declare const __: undefined;
 export { __, useOmitExtraParams };

package/lib/rules.d.mts

@@ -1,42 +1,82 @@
 import { FormItemRule } from "naive-ui";
+/**
+ * 预设验证规则类型
+ */
 type PresetRules = 'onlyNotChineseRule' | 'onlyChineseRule' | 'onlyNegativeIntRule' | 'onlyPositiveIntRule' | 'onlyPositiveIntZeroRule' | 'officePhoneRule' | 'mobilePhoneRule' | 'emailRule' | 'onlyNumbersRule' | 'onlyLetterRule' | 'onlyLowercaseRule' | 'onlyUppercaseRule' | 'ipRule' | 'onlyIntRule';
+/**
+ * 验证触发时机类型
+ */
 type ValidationTrigger = 'input' | 'change' | 'input-number';
+/**
+ * 验证触发时机对应的提示前缀类型
+ */
 type PrefixType = { [K in ValidationTrigger]: string };
+/**
+ * 规则选项类型
+ */
 interface RuleOptionsType {
+  /** 是否必填 */
   required?: boolean;
+  /** 自定义错误消息 */
   message?: string;
 }
+/**
+ * 创建表单验证规则
+ * @param trigger - 验证触发时机: 'input' | 'change' | 'input-number'
+ * @param message - 错误提示消息或预设规则名称
+ * @param options - 规则选项
+ * @param options.required - 是否必填, 默认为 true
+ * @param options.message - 自定义错误消息
+ * @returns 表单验证规则对象
+ * @example
+ * // 使用自定义消息
+ * useRules('input', '用户名')
+ * // 使用预设规则
+ * useRules('input', 'emailRule', { required: true })
+ */
 declare function useRules(trigger: ValidationTrigger, message: string, options?: RuleOptionsType): FormItemRule;
 declare function useRules(trigger: ValidationTrigger, message: PresetRules, options?: RuleOptionsType): FormItemRule;
 /**
  * 字符串输入长度限制规则
- * @param {number} [min=0] - 最小长度，默认为 0
- * @param {number} [max] - 最大长度，未指定时使用 AppProvider 中的 stringLength 配置
- * @param {string} [message] - 自定义错误消息
- * @returns {FormItemRule} 表单验证规则对象
+ * @param min - 最小长度, 默认为 0
+ * @param max - 最大长度, 未指定时使用 AppProvider 中的 stringLength 配置
+ * @param message - 自定义错误消息
+ * @returns 表单验证规则对象
+ * @example
+ * useRuleStringLength(0, 50) // 最大长度 50
+ * useRuleStringLength(5, 20, '长度必须在 5-20 之间')
  */
 declare const useRuleStringLength: (min?: number, max?: number, message?: string) => FormItemRule;
 /**
- * 数字输入长度限制规则（基于位数）
- * @param {number} [min=0] - 最小位数，默认为 0
- * @param {number} [max] - 最大位数，未指定时使用 AppProvider 中的 numberLength 配置
- * @param {string} [message] - 自定义错误消息
- * @returns {FormItemRule} 表单验证规则对象
+ * 数字输入长度限制规则(基于位数)
+ * @param min - 最小位数, 默认为 0
+ * @param max - 最大位数, 未指定时使用 AppProvider 中的 numberLength 配置
+ * @param message - 自定义错误消息
+ * @returns 表单验证规则对象
+ * @example
+ * useRuleNumberLength(0, 6)  // 最多 6 位数字
+ * useRuleNumberLength(3, 10) // 3-10 位数字
  */
 declare const useRuleNumberLength: (min?: number, max?: number, message?: string) => FormItemRule;
 /**
- * 数字输入大小限制规则（基于数值范围）
- * @param {number} [min=0] - 最小值，默认为 0
- * @param {number} [max] - 最大值的指数（10 的 max 次方 -1），未指定时使用 AppProvider 中的 numberSize 配置
- * @param {string} [message] - 自定义错误消息
- * @returns {FormItemRule} 表单验证规则对象
+ * 数字输入大小限制规则
+ * @param min - 最小值, 默认为 0
+ * @param max - 最大值的指数 (10 的 max 次方 -1), 未指定时使用 AppProvider 中的 numberSize 配置
+ * @param message - 自定义错误消息
+ * @returns 表单验证规则对象
+ * @example
+ * useRuleNumberSize(0, 3)  // 0-999
+ * useRuleNumberSize(10, 5) // 10-99999
  */
 declare const useRuleNumberSize: (min?: number, max?: number, message?: string) => FormItemRule;
 /**
  * 小数位数限制规则
- * @param {number} [place=2] - 允许的最大小数位数，未指定时使用 AppProvider 中的 decimalPlace 配置
- * @param {string} [message] - 自定义错误消息
- * @returns {FormItemRule} 表单验证规则对象
+ * @param place - 允许的最大小数位数, 未指定时使用 AppProvider 中的 decimalPlace 配置,默认为 2
+ * @param message - 自定义错误消息
+ * @returns 表单验证规则对象
+ * @example
+ * useRuleDecimalPlace(2) // 最多 2 位小数
+ * useRuleDecimalPlace(4, '最多保留4位小数')
  */
 declare const useRuleDecimalPlace: (place?: number, message?: string) => FormItemRule;
 export { PrefixType, PresetRules, ValidationTrigger, useRuleDecimalPlace, useRuleNumberLength, useRuleNumberSize, useRuleStringLength, useRules };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@semi-kit/utils",
-  "version": "1.2.3",
+  "version": "1.2.5",
   "description": "General-purpose tool function library",
   "type": "module",
   "license": "MIT",