@zero-library/common 2.1.10 → 2.1.11

package/dist/index.d.mts

@@ -284,7 +284,7 @@ interface RenderMarkdownProps {
  * Markdown渲染组件
  * 将Markdown文本转换为HTML并渲染为React组件
  * 支持自定义组件、搜索高亮、内容编辑等功能
- * @param props - 组件属性
+ * @param RenderMarkdownProps - 组件属性
  */
 declare const _default$1: ({ content, searchValue, customComponents, onChange, onPartialChange }: RenderMarkdownProps) => react_jsx_runtime.JSX.Element;
 
@@ -392,9 +392,15 @@ declare function useIframeRelayBridge(allowedOrigins?: string[]): {
 };
 
 /**
- * 通用的 Valtio Context 工厂
- * 支持：
- *  - useStore() 获取 store 实例
+ * 通用的 Valtio Context 创建工厂 Hook
+ * 创建 Valtio 状态管理的 Context 和 Provider
+ *
+ * 支持的操作：
+ * - ValtioProvider：包裹组件以提供 store 状态
+ * - useValtioStore：在组件中获取 store 实例
+ *
+ * @template T - Store 对象类型
+ * @returns Valtio Context 相关的工具函数
  */
 declare function useCreateValtioContext<T extends object>(): {
     ValtioProvider: ({ store, children }: {
@@ -402,27 +408,37 @@ declare function useCreateValtioContext<T extends object>(): {
         children?: ReactNode;
     }) => react_jsx_runtime.JSX.Element;
     useValtioStore: () => T;
+    Context: react.Context<T>;
 };
 
 /**
- * 防抖hook
- * @param func 需要执行的函数
- * @param wait 延迟时间
+ * 防抖 Hook
+ * 在指定时间内多次调用只执行最后一次，延迟指定时间后执行
+ *
+ * @param func - 需要防抖的函数
+ * @param wait - 延迟时间（毫秒），默认为400ms
+ * @returns 防抖处理后的函数，包含 flush 和 cancel 方法
  */
 declare function useDebounce<A extends Array<any>, R = void>(func: (..._args: A) => R, wait?: number): {
     (..._args: A): Promise<R>;
+    /** 添加额外方法到防抖函数 */
     flush: () => any;
     cancel: () => void;
 };
 
 /**
- * useDeepEffect
- * 深层对比依赖项的 useEffect
+ * 深度比较 useEffect Hook
+ * 使用深度比较算法来检测依赖项变化，避免不必要的重新渲染
+ *
+ * @param effect - 要执行的副作用函数
+ * @param deps - 依赖项数组
  */
 declare function useDeepEffect(effect: React.EffectCallback, deps: any[]): void;
 
 /**
- * 创建同时具有 ref 和 state 特性的状态
+ * 创建同时具有 ref 和 state 特性的状态 Hook
+ * 解决了 useState 在异步闭包中获取不到最新值的问题
+ *
  * @param init - 初始值
  * @returns [state, setState, getState] 元组，包含状态值、设置函数和获取函数
  */
@@ -431,6 +447,8 @@ declare function useRefState<T>(init: T): readonly [T, (newVal: T) => void, () =
 /**
  * 同步输入框组件和外部状态的 Hook
  * 解决输入中文时因连续渲染关闭中文输入法的问题
+ *
+ * @template T - 值类型
  * @param storeValue - 外部存储的值
  * @param setStoreValue - 设置外部存储值的函数
  * @returns 包含 inputValue 和 setInputValue 的对象
@@ -441,12 +459,18 @@ declare const useSyncInput: <T>(storeValue: T, setStoreValue: (value: T) => void
 };
 
 /**
- * 节流hook
- * @param func 需要执行的函数
- * @param wait 延迟时间
+ * 节流 Hook
+ * 在指定时间间隔内只执行一次函数，节流控制函数调用频率
+ *
+ * @template A - 函数参数类型
+ * @template R - 返回值类型
+ * @param func - 需要节流的函数
+ * @param wait - 节流间隔时间（毫秒）
+ * @returns 节流处理后的函数，包含 flush 和 cancel 方法
  */
 declare function useThrottle<A extends Array<any>, R = void>(func: (..._args: A) => R, wait: number): {
     (..._args: A): Promise<R>;
+    /** 添加额外方法到节流函数 */
     flush: () => any;
     cancel: () => void;
 };
@@ -508,18 +532,19 @@ declare const objToOptions: (obj: ObjectType<string>) => {
 declare const arrToObj: <T>(arr: T[], key: string) => {
     [key: string]: T;
 };
-/**
- * 使用 setTimeout 模拟 setInterval，避免 setInterval 的问题
- * @param fn - 要重复执行的函数
- * @param t - 间隔时间（毫秒）
- * @returns 控制对象，包含 isRun 和 cancel 方法
- */
 interface NsSetIntervalReturnType {
     /** 检查是否正在运行 */
     isRun: () => boolean;
     /** 取消定时器 */
     cancel: () => void;
 }
+/**
+ * 使用 setTimeout 模拟 setInterval 的返回类型接口
+ * 避免 setInterval 的内存泄漏问题
+ * @param fn - 要重复执行的函数
+ * @param t - 间隔时间（毫秒）
+ * @returns 控制对象，包含 isRun 和 cancel 方法
+ */
 declare const nsSetInterval: (fn: () => void, t: number) => NsSetIntervalReturnType;
 /**
  * 生成不重复的唯一ID
@@ -530,14 +555,22 @@ declare const genNonDuplicateID: () => string;
  * 复制文本到剪贴板
  * 优先使用 navigator.clipboard API，降级使用 execCommand
  * @param text - 要复制的文本
- * @returns Promise
+ * @param prompt - 提示语
+ * @returns void
  */
-declare const copyText: (text: string) => Promise<void>;
+declare const copyText: (text: string, prompt?: string) => void;
 /**
  * 把后台接口字段，返回的关于金额的数字，转换为千分符号分隔的数字
  * return string
  */
 declare function formatNumberWithCommas(number: number | string): string | number;
+/**
+ * 生成指定范围内的不重复随机数
+ * @param min - 最小值
+ * @param max - 最大值
+ * @param count - 生成数量
+ * @returns 不重复的随机数数组
+ */
 declare const generateRandomNumbers: (min: number, max: number, count: number) => number[];
 /**
  * 从文件路径中提取文件名
@@ -564,30 +597,55 @@ declare const textAreaView: (con?: string) => string;
  * @returns URL 查询参数字符串
  */
 declare const buildUrlParams: (obj: Record<string, any>, url?: string) => string;
+/**
+ * 下载文件到本地
+ * @param url - 文件下载地址
+ * @param name - 下载文件名，默认为'图片下载'
+ */
 declare const downloadFile: (url: string, name?: string) => void;
 /**
- * 给URL路径最后加/
+ * 给URL路径最后添加斜杠
+ * @param url - 要处理的URL，默认为空字符串
+ * @returns 处理后的URL
  */
 declare const addUrlLastSlash: (url?: string) => string;
 /**
- * 给url增加mainSource参数
+ * 给URL增加mainSource参数
+ * @param url - 目标URL
+ * @param preHref - 参考URL，用于获取mainSource参数
+ * @returns 处理后的URL
  */
 declare const getUrlMainSource: (url: string, preHref?: string) => string;
 /**
- * 获取 WebSocket 地址
- * @param path WebSocket 服务路径，比如 "/ws" 或 "/socket"
- * @param customHost 可选，指定 host:port；默认取当前 window.location.host
+ * 获取 WebSocket 连接地址
+ * @param path - WebSocket 服务路径，比如 "/ws" 或 "/socket"
+ * @param customHost - 可选，指定 host:port；默认取当前 window.location.host
+ * @returns 完整的 WebSocket URL
  */
 declare const getWebSocketUrl: (path: string, customHost?: string) => string;
+/**
+ * 对象转换函数，将源对象转换为目标对象
+ * @param source - 源对象
+ * @param fieldMap - 字段映射配置
+ * @returns 转换后的目标对象
+ */
 declare function transform<T extends object, U extends object>(source: T, fieldMap: {
     [K in keyof U]: keyof T | ((source: T) => U[K]) | U[K];
 }): U;
+/**
+ * 批量对象转换函数
+ * @param sources - 源对象数组
+ * @param fieldMap - 字段映射配置
+ * @returns 转换后的目标对象数组
+ */
 declare function transforms<T extends object, U extends object>(sources: T[], fieldMap: {
     [K in keyof U]: keyof T | ((source: T) => U[K]) | U[K];
 }): U[];
 
 type DateType = string | number | Date | dayjs.Dayjs | null;
+/** 默认日期时间格式：年-月-日 时:分:秒 */
 declare const DateFormatType = "YYYY-MM-DD HH:mm:ss";
+/** 默认日期格式：年-月-日 */
 declare const DateFormatType2 = "YYYY-MM-DD";
 /**
  * 获取一天的最早时间 '2023/10/17 00:00:00' 的时间戳
@@ -652,7 +710,9 @@ declare function isEmpty<T = unknown>(val: T): val is T;
 declare function isWindow(val: any): val is Window;
 declare function isElement(val: unknown): val is Element;
 declare function isMap(val: unknown): val is Map<any, any>;
+/** 判断是否为服务端环境（无 window 对象） */
 declare const isServer: boolean;
+/** 判断是否为客户端环境（有 window 对象） */
 declare const isClient: boolean;
 /**
  * 判断是否是外链
@@ -664,60 +724,191 @@ declare const isExternal: (path: string) => boolean;
 declare const isBlob: (val: unknown) => boolean;
 declare const isLocalhost: (host?: string) => boolean;
 
-interface UserInfo {
-    id: number;
-    orgName: string;
-    name: string;
-    username: string;
-    mobile: string;
-    avatar: string;
-    myInviteCode: string;
-    email?: string;
-    remark?: string;
-    roles: number[];
-    permissions: string[];
-}
+/**
+ * 设置当前用户信息到 sessionStorage（AES 加密存储）
+ * @param userInfo - 用户信息对象
+ */
 declare function setCurrentUser(userInfo: any): void;
+/**
+ * 从 sessionStorage 获取当前用户信息（AES 解密）
+ * @returns 用户信息对象或 null
+ */
 declare function getCurrentUser(): any;
+/**
+ * 清除 sessionStorage 中的用户信息
+ */
 declare function clearCurrentUser(): void;
+/**
+ * 获取或生成设备唯一标识
+ * @returns 设备ID字符串
+ */
 declare function getDeviceId(): string;
 
+/** 数学运算符类型 */
 type OperatorType = '+' | '-' | '*' | '/';
+/**
+ * 通用数学计算函数
+ * @param operator - 运算符：+、-、*、/
+ * @param args - 要计算的数值数组
+ * @returns 计算结果字符串
+ */
 declare const calculate: (operator: OperatorType, ...args: Decimal.Value[]) => string;
+/**
+ * 精确加法运算
+ * 调用：plus(arg1,arg2)
+ * 返回值：arg1加arg2的精确结果
+ */
 declare const plus: (...args: Decimal.Value[]) => string;
+/**
+ * 精确减法运算
+ * 调用：minus(arg1,arg2)
+ * 返回值：arg1减arg2的精确结果
+ */
 declare const minus: (...args: Decimal.Value[]) => string;
+/**
+ * 精确乘法运算
+ * 调用：times(arg1,arg2)
+ * 返回值：arg1乘以arg2的精确结果
+ */
 declare const times: (...args: Decimal.Value[]) => string;
+/**
+ * 精确除法运算
+ * 调用：dividedBy(arg1,arg2)
+ * 返回值：arg1除以arg2的精确结果
+ */
 declare const dividedBy: (...args: Decimal.Value[]) => string;
+/**
+ * 查看小数位数（不计算小数点最后末尾的0）
+ * @param arg1 - 要检查的数值
+ * @returns 小数位数
+ */
 declare const decimalPlaces: (arg1: Decimal.Value) => number;
+/**
+ * 查看数值总位数（包括整数和小数部分）
+ * @param arg1 - 要检查的数值
+ * @returns 总位数
+ */
 declare const precision: (arg1: Decimal.Value) => number;
+/**
+ * 取绝对值
+ * @param arg1 - 要处理的数值
+ * @returns 绝对值字符串
+ */
 declare const absVal: (arg1: Decimal.Value) => string;
+/**
+ * 数值比较函数
+ * @param arg1 - 第一个数值
+ * @param arg2 - 第二个数值
+ * @param type - 比较类型：>、>=、<、<=、==
+ * @returns 比较结果布尔值
+ */
 declare const compareNum: (arg1: Decimal.Value, arg2: Decimal.Value, type: string) => boolean;
+/**
+ * 四舍五入处理
+ * @param num - 要处理的数值
+ * @param decimals - 保留小数位数，默认为2
+ * @param fill - 是否补0，默认为true
+ * @returns 处理后的数字字符串
+ */
 declare const toFixed: (num: Decimal.Value, decimals?: number, fill?: boolean) => string;
+/**
+ * 判断是否为整数
+ * @param num - 要判断的数值
+ * @returns 是否为整数
+ */
 declare const isInteger: (num: Decimal.Value) => boolean;
+/**
+ * 判断是否为负数
+ * @param num - 要判断的数值
+ * @returns 是否为负数
+ */
 declare const isNegative: (num: Decimal.Value) => boolean;
 
+/** HTTP 状态码常量：成功 */
 declare const OK = 200;
+/** HTTP 状态码常量：服务器错误 */
 declare const ERROR = 500;
+/** HTTP 状态码常量：缺少参数 */
 declare const MISSING_PARAMETER = 400;
+/** HTTP 状态码常量：未授权 */
 declare const UNAUTHORIZED = 401;
+/** HTTP 状态码常量：禁止访问 */
 declare const FORBIDDEN = 403;
+/** HTTP 状态码常量：未找到资源 */
 declare const NOT_FOUND = 404;
+/** 业务错误码常量：权限拒绝 */
 declare const PERMISSION_DENIED = 13001;
+/**
+ * 创建 Axios 请求实例
+ * @param baseURL - API 基础路径，默认为 '/api'
+ * @returns 请求实例对象
+ */
 declare function createRequest(baseURL?: string): {
+    /**
+     * GET 请求方法
+     * @param url - 请求地址
+     * @param params - 查询参数
+     * @param options - Axios 配置选项
+     * @returns 响应数据
+     */
     get: (url: string, params?: any, options?: AxiosRequestConfig) => Promise<any>;
+    /**
+     * POST 请求方法
+     * @param url - 请求地址
+     * @param data - 请求数据
+     * @param options - Axios 配置选项
+     * @returns 响应数据
+     */
     post: (url: string, data?: any, options?: AxiosRequestConfig) => Promise<any>;
+    /**
+     * PUT 请求方法
+     * @param url - 请求地址
+     * @param data - 请求数据
+     * @param options - Axios 配置选项
+     * @returns 响应数据
+     */
     put: (url: string, data?: any, options?: AxiosRequestConfig) => Promise<any>;
+    /**
+     * DELETE 请求方法
+     * @param url - 请求地址
+     * @param data - 请求数据
+     * @param options - Axios 配置选项
+     * @returns 响应数据
+     */
     delete: (url: string, data?: any, options?: AxiosRequestConfig) => Promise<any>;
 };
 
+/** Token 存储键名 */
 declare const TOKEN_KEY = "NS-TOKEN";
+/**
+ * 设置访问令牌到 localStorage
+ * @param accessToken - 访问令牌
+ */
 declare function setToken(accessToken: string): void;
+/**
+ * 从 URL 查询参数中获取 Token
+ * @returns Token 字符串或空字符串
+ */
 declare function getUrlToken(): string;
+/**
+ * 获取当前有效的访问令牌
+ * 优先从 URL 参数获取，其次从 localStorage 获取
+ * @returns Token 字符串或空字符串
+ */
 declare function getToken(): string;
+/**
+ * 清除 localStorage 中的 Token
+ */
 declare function clearToken(): void;
+/**
+ * 获取登录页面路径
+ * @returns 登录路径，默认为 '/sign-in'
+ */
 declare function getSignPath(): string;
 
+/** 项目主色调 */
 declare const LgPrimaryColor: string;
+/** Ant Design 主题配置 */
 declare const themeConfig: ThemeConfig;
 
-export { _default$b as AudioPlayer, type AudioPlayerProps, type ComponentMapType, DateFormatType, DateFormatType2, ERROR, FORBIDDEN, _default$a as FileIcon, type FileIconProps, _default$9 as FilePreview, _default$8 as FilePreviewDrawer, type FilePreviewDrawerProps, type FilePreviewProps, _default$4 as Iframe, type IframeProps, _default$3 as LazyComponent, type LazyComponentProps, LgPrimaryColor, MISSING_PARAMETER, _default$2 as MarkdownEditor, type MarkdownEditorProps, _default$7 as MarkdownPreview, type MarkdownPreviewProps, NOT_FOUND, type NsSetIntervalReturnType, OK, PERMISSION_DENIED, type Params, _default$6 as PdfPreview, type PdfPreviewProps, type RenderControl, type RenderControlObj, _default$1 as RenderMarkdown, type RenderMarkdownProps, RenderWrapper, type RenderWrapperProps, TOKEN_KEY, UNAUTHORIZED, _default as UserAvatar, type UserAvatarProps, type UserInfo, _default$5 as VideoPlayer, type VideoPlayerProps, absVal, addUrlLastSlash, arrToObj, buildUrlParams, calculate, clearCurrentUser, clearToken, compareNum, copyText, createRequest, decimalPlaces, deepCopy, deepEqual, deepMerge, dividedBy, downloadFile, emit, emitToChild, formatDate, formatNumberWithCommas, genNonDuplicateID, generateRandomNumbers, getCurrentUser, getDeviceId, getEndOfTimestamp, getFileName, getFileSuffixName, getSignPath, getStartOfTimestamp, getTimestamp, getToken, getUrlMainSource, getUrlToken, getWebSocketUrl, is, isArray, isBlob, isBoolean, isClient, isDate, isDef, isElement, isEmpty, isEmptyObj, isExpire, isExternal, isFunction, isInteger, isLocalhost, isMap, isNegative, isNull, isNullOrUnDef, isNumber, isNumberNoNaN, isObject, isPromise, isRegExp, isServer, isString, isUnDef, isWindow, minus, nsSetInterval, objToOptions, plus, precision, propsMerge, setCurrentUser, setToken, shouldRender, textAreaView, themeConfig, times, toFixed, transform, transforms, useCreateValtioContext, useDebounce, useDeepEffect, useIframeRelayBridge, useRefState, useSyncInput, useThrottle, useWebSocket };
+export { _default$b as AudioPlayer, type AudioPlayerProps, type ComponentMapType, DateFormatType, DateFormatType2, ERROR, FORBIDDEN, _default$a as FileIcon, type FileIconProps, _default$9 as FilePreview, _default$8 as FilePreviewDrawer, type FilePreviewDrawerProps, type FilePreviewProps, _default$4 as Iframe, type IframeProps, _default$3 as LazyComponent, type LazyComponentProps, LgPrimaryColor, MISSING_PARAMETER, _default$2 as MarkdownEditor, type MarkdownEditorProps, _default$7 as MarkdownPreview, type MarkdownPreviewProps, NOT_FOUND, type NsSetIntervalReturnType, OK, PERMISSION_DENIED, type Params, _default$6 as PdfPreview, type PdfPreviewProps, type RenderControl, type RenderControlObj, _default$1 as RenderMarkdown, type RenderMarkdownProps, RenderWrapper, type RenderWrapperProps, TOKEN_KEY, UNAUTHORIZED, _default as UserAvatar, type UserAvatarProps, _default$5 as VideoPlayer, type VideoPlayerProps, absVal, addUrlLastSlash, arrToObj, buildUrlParams, calculate, clearCurrentUser, clearToken, compareNum, copyText, createRequest, decimalPlaces, deepCopy, deepEqual, deepMerge, dividedBy, downloadFile, emit, emitToChild, formatDate, formatNumberWithCommas, genNonDuplicateID, generateRandomNumbers, getCurrentUser, getDeviceId, getEndOfTimestamp, getFileName, getFileSuffixName, getSignPath, getStartOfTimestamp, getTimestamp, getToken, getUrlMainSource, getUrlToken, getWebSocketUrl, is, isArray, isBlob, isBoolean, isClient, isDate, isDef, isElement, isEmpty, isEmptyObj, isExpire, isExternal, isFunction, isInteger, isLocalhost, isMap, isNegative, isNull, isNullOrUnDef, isNumber, isNumberNoNaN, isObject, isPromise, isRegExp, isServer, isString, isUnDef, isWindow, minus, nsSetInterval, objToOptions, plus, precision, propsMerge, setCurrentUser, setToken, shouldRender, textAreaView, themeConfig, times, toFixed, transform, transforms, useCreateValtioContext, useDebounce, useDeepEffect, useIframeRelayBridge, useRefState, useSyncInput, useThrottle, useWebSocket };