@zcrkey/js-utils 0.0.11 → 0.0.15

package/dist/types/color.d.ts

@@ -0,0 +1,303 @@
+export interface RGB {
+    r: number;
+    g: number;
+    b: number;
+    a?: number;
+}
+export interface HSV {
+    h: number;
+    s: number;
+    v: number;
+    a?: number;
+}
+export type CrColorAsType = 'string' | 'object';
+export type CrColorInputType = 'hex' | 'rgb' | 'hsv' | 'object';
+export type CrColorOutputType<T extends 'string' | 'object' | undefined, R> = T extends 'object' ? R : string;
+export declare class CrColorUtil {
+    private static readonly HEX_COLOR_REGEXP;
+    private static readonly HEX_VALUE_REGEXP;
+    private static readonly RGB_FUNCTION_REGEXP;
+    private static readonly HSV_FUNCTION_REGEXP;
+    /**
+     * 判断是否为合法的 HEX / HEXA 颜色值
+     * @param hex 必须 # 开头
+     * @returns
+     */
+    static isHexColor(hex: string): boolean;
+    /**
+     * 判断是否为合法的 RGB / RGBA 颜色值
+     * @param color
+     * @returns
+     */
+    static isRgbColor(color: string): boolean;
+    static isHsvColor(color: string): boolean;
+    private static clamp;
+    private static clampByte;
+    private static clampAlpha;
+    private static toFixedNumber;
+    private static toHexByte;
+    private static normalizeHue;
+    private static normalizeHex;
+    private static isRgbLike;
+    private static isHsvLike;
+    private static normalizeRgb;
+    private static normalizeHsv;
+    private static rgbToHsv;
+    private static hsvToRgb;
+    private static splitColorFunctionArgs;
+    private static parseRgbChannel;
+    private static parsePercentChannel;
+    private static parseAlpha;
+    static parse(input: string | RGB | HSV): RGB | null;
+    static parseHex(hex: string): RGB | null;
+    static parseRgb(str: string): RGB | null;
+    static parseHsv(str: string): RGB | null;
+    static toRgb<T extends 'string' | 'object' | undefined = 'string'>(input: string | RGB | HSV, as?: T): CrColorOutputType<T, RGB> | null;
+    static toHex<T extends 'string' | 'object' | undefined = 'string'>(input: string | RGB | HSV, as?: T): CrColorOutputType<T, RGB> | null;
+    static toHsv<T extends 'string' | 'object' | undefined = 'string'>(input: string | RGB | HSV, as?: T): CrColorOutputType<T, HSV> | null;
+    /**
+     * 转换为 ARGB 格式（Android / Windows 标准：0xAARRGGBB）
+     * @param input 任意颜色
+     * @param as 'string' | 'number' 输出 16进制字符串 或 整型数字
+     * @returns 0xAARRGGBB 格式
+     */
+    static toArgb<T extends 'string' | 'number' = 'string'>(input: string | RGB | HSV, as?: T): (T extends 'string' ? string : number) | null;
+    /**
+     * 内部增强解析：获取颜色对象 + 原始来源类型
+     */
+    static parseWithSource(input: string | RGB | HSV): {
+        rgb: RGB | null;
+        sourceType: CrColorInputType;
+    };
+    /**
+     * 根据来源类型自动格式化输出
+     */
+    static formatOutputBySource<T extends 'string' | 'object' | undefined>(rgb: RGB, sourceType: CrColorInputType, as?: T): CrColorOutputType<T, RGB | HSV> | null;
+    /**
+     * 设置 / 追加透明度
+     * @param input
+     * @param alpha
+     * @param as
+     * @returns
+     */
+    static setAlpha<T extends 'string' | 'object' | undefined = 'string'>(input: string | RGB | HSV, alpha: number, as?: T): CrColorOutputType<T, RGB | HSV> | null;
+    /**
+     * 移除透明度
+     * @param input
+     * @param as
+     * @returns
+     */
+    static removeAlpha<T extends 'string' | 'object' | undefined = 'string'>(input: string | RGB | HSV, as?: T): CrColorOutputType<T, RGB | HSV> | null;
+    /**
+     * 颜色加深处理
+     * @param input
+     * @param level 加深程度 0-1  0不变 1最深(接近黑色)
+     */
+    static darkenColor(input: string, level: number): string | null;
+    /**
+     * 颜色减淡/提亮处理
+     * @param input
+     * @param level 减淡程度 0-1  0不变 1最亮(接近白色)
+     */
+    static lightenColor(input: string, level: number): string | null;
+    /**
+     * 调整颜色饱和度
+     * @param hex 目标颜色
+     * @param level 调整程度 0-2  1=不变  <1=降低饱和度  >1=提高饱和度
+     * @returns 调整后的hex颜色
+     */
+    static adjustSaturation(hex: string, level: number): string | null;
+    /**
+     * 调整颜色明度
+     * @param hex 目标颜色
+     * @param level 调整程度 0-2  1=不变  <1=降低明度  >1=提高明度
+     * @returns 调整后的hex颜色
+     */
+    static adjustBrightness(hex: string, level: number): string | null;
+    /**
+     * 反色处理 - 取颜色的补色（比如黑色→白色，白色→黑色）
+     * @param hex 目标颜色
+     * @returns 反色hex
+     */
+    static reverseColor(hex: string): string | null;
+    /**
+     * 生成随机Hex颜色
+     * @param withHash 是否带 # 前缀，默认 true
+     * @returns 随机hex颜色
+     */
+    static randomHexColor(withHash?: boolean): string;
+    private static parseLegacyHex;
+    /**
+     * hex 转 rgb 数组 [r,g,b]  r/g/b范围 0-255
+     * @param hex 支持 #fff / #ffffff / fff / ffffff 格式
+     * @deprecated 即将移除，使用 {@link CrColorUtil.toRgb} 替代
+     */
+    static hexToRgb(hex: string): number[];
+    /**
+     * rgb 转 hex 标准格式
+     * @param r 0-255
+     * @param g 0-255
+     * @param b 0-255
+     * @deprecated 即将移除，使用 {@link CrColorUtil.toHex} 替代
+     */
+    static rgbToHex(r: number, g: number, b: number): string;
+    /**
+     * 将 rgb 格式转为 hsv 格式
+     * input: r,g,b in [0,1], out: h in [0,360) and s,v in [0,1]
+     * @param r 0-1
+     * @param g 0-1
+     * @param b 0-1
+     * @deprecated 即将移除，使用 {@link CrColorUtil.toHsv} 替代
+     */
+    static rgb2hsv(r: number, g: number, b: number): number[];
+    /**
+     * 将 hsv 格式转为 rgb 格式
+     * input: h in [0,360] and s,v in [0,1] - output: r,g,b in [0,1]
+     * @param h 0-360
+     * @param s 0-1
+     * @param v 0-1
+     * @deprecated 即将移除，使用 {@link CrColorUtil.toRgb} 替代
+     */
+    static hsv2rgb(h: number, s: number, v: number): number[];
+    /**
+     * hex 转 rgba 格式字符串 可直接用于css
+     * @param hex 支持 #fff / #ffffff / fff / ffffff 格式
+     * @param alpha 透明度 0-1  默认1(完全不透明)
+     * @returns 例: rgba(255,255,255,0.5)
+     * @deprecated 即将移除，使用 {@link CrColorUtil.setAlpha} 替代
+     */
+    static hexToRgba(hex: string, alpha?: number): string;
+    /**
+     * 给hex颜色添加透明度，返回 8位带透明通道的hex格式 #RRGGBBAA (CSS常用)
+     * @param hex 支持 #fff / #ffffff / fff / ffffff 格式
+     * @param alpha 透明度 0-1  默认1(完全不透明)
+     * @returns 例: #ffffff80  #ff000033
+     * @deprecated 即将移除，使用 {@link CrColorUtil.setAlpha} 替代
+     */
+    static hexAddAlpha(hex: string, alpha?: number): string;
+    /**
+     * rgba 转 hex 格式
+     * @param r 0-255
+     * @param g 0-255
+     * @param b 0-255
+     * @param alpha 兼容旧调用，转换时会忽略透明度
+     * @deprecated 即将移除，使用 {@link CrColorUtil.toHex} 替代
+     */
+    static rgbaToHex(r: number, g: number, b: number, alpha?: number): string;
+    /**
+     * hsv 转 hex 十六进制颜色
+     * @param h 色相 0-360
+     * @param s 饱和度 0-1
+     * @param v 明度 0-1
+     * @deprecated 即将移除，使用 {@link CrColorUtil.toHex} 替代
+     */
+    static hsvToHex(h: number, s: number, v: number): string;
+    /**
+     * hex 转 hsv 格式
+     * @param hex 支持 #fff / #ffffff / fff / ffffff 格式
+     * @returns [h:0-360, s:0-1, v:0-1]
+     * @deprecated 即将移除，使用 {@link CrColorUtil.toHsv} 替代
+     */
+    static hexToHsv(hex: string): number[];
+    /**
+     * 解析8位带透明的hex #RRGGBBAA 为 普通hex + 透明度
+     * @param hex8 8位带透明的十六进制颜色 例：#ffffff80
+     * @returns { hex: '#ffffff', alpha: 0.5 }
+     * @deprecated 即将移除，使用 {@link CrColorUtil.parseHex} {@link CrColorUtil.parseRgb} 替代
+     */
+    static parseHex8(hex8: string): {
+        hex: string;
+        alpha: number;
+    };
+    /**
+     * rgb 数组 转 rgb/rgba 字符串
+     * @param rgb [r,g,b] 0-255
+     * @param alpha 透明度0-1 传则返回rgba，不传返回rgb
+     * @deprecated 即将移除，使用 {@link CrColorUtil.toRgb} 替代
+     */
+    static rgbToStr(rgb: number[], alpha?: number): string;
+    /**
+     * Hex颜色字符串 转 十进制数值（6位纯颜色值，无透明通道，专用于颜色运算）
+     * @param hex 支持 #fff / #ffffff / fff / ffffff 格式
+     * @returns 十进制数值 例：#ff0000 → 16711680，非法入参返回 0
+     * @deprecated 即将移除，使用 {@link CrColorUtil.toHex} 替代
+     */
+    static hexToNumber(hex: string): number;
+    /**
+     * 十进制数值 转回 Hex颜色字符串（无透明通道 标准6位）
+     * @param num 十进制数值 例：16711680 → #ff0000
+     * @returns 标准6位十六进制颜色 #RRGGBB 格式
+     * @deprecated 即将移除，使用 {@link CrColorUtil.toRgb} 替代
+     */
+    static numberToHex(num: number): string;
+    /**
+     * ARGB颜色字符串 转 十进制数值（8位带透明通道，专用于带透明的颜色运算）
+     * @param argb 支持 #AARRGGBB / AARRGGBB 格式 例：#80FFFFFF、80FFFFFF
+     * @returns 十进制数值 例：#80FFFFFF → 2147483647，非法入参/格式错误返回 0
+     * @deprecated 即将移除，使用 {@link CrColorUtil.toArgb} 替代
+     */
+    static argbToNumber(argb: string): number;
+    /**
+     * 十进制数值 转回 ARGB颜色字符串（8位带透明通道，标准#AARRGGBB格式）
+     * @param num 十进制数值 例：2147483647 → #80ffffff
+     * @returns 标准ARGB颜色字符串 #AARRGGBB 小写格式
+     * @deprecated 即将移除。生成 ARGB 请使用 {@link CrColorUtil.toArgb}；
+     * 已有 ARGB number 转 #AARRGGBB 的场景暂无简洁等价新 API，暂保留该兼容方法。
+     */
+    static numberToArgb(num: number): string;
+    /**
+     * 标准6位Hex颜色 转 ARGB 8位颜色格式 ( 核心：ARGB格式是 #AARRGGBB )
+     * @param hex 6位标准hex 支持 #ffffff / ffffff / #fff / fff
+     * @param alpha 透明度 0~1  默认 1 (完全不透明)
+     * @returns 8位ARGB格式颜色 例：#80FFFFFF  半透明白色
+     * @deprecated 即将移除，使用 {@link CrColorUtil.toArgb} 替代
+     */
+    static hexToArgb(hex: string, alpha?: number): string;
+    /**
+     * ARGB 8位颜色格式 转回 标准6位Hex颜色 + 独立的透明度值 ( 反向解析 )
+     * @param argb 8位ARGB格式颜色 必须是 #AARRGGBB 格式 例：#80FFFFFF
+     * @returns { hex: '#ffffff', alpha: 0.5 } 标准hex + 0~1的透明度
+     * @deprecated 即将移除。可用 {@link CrColorUtil.argbToRgbaHex} + {@link CrColorUtil.parseHex}
+     * 组合替代；若需要旧返回结构 { hex, alpha }，需自行从 parseHex 结果中拆出 a。
+     */
+    static argbToHex(argb: string): {
+        hex: string;
+        alpha: number;
+    };
+    /**
+     * ARGB格式(#AARRGGBB) 转 RRGGBBAA格式(#RRGGBBAA)
+     * @param argb #AARRGGBB
+     * @returns #RRGGBBAA
+     * @deprecated 即将移除。纯新 API 暂无单步等价；如已拆出 { hex, alpha }，
+     * 可用 {@link CrColorUtil.setAlpha} 生成 #RRGGBBAA。
+     */
+    static argbToRgbaHex(argb: string): string;
+    /**
+     * RRGGBBAA格式(#RRGGBBAA) 转 ARGB格式(#AARRGGBB)
+     * @param rgbaHex #RRGGBBAA
+     * @returns #AARRGGBB
+     * @deprecated 即将移除。可用 {@link CrColorUtil.parseHex} + {@link CrColorUtil.toArgb}
+     * 组合替代；toArgb 返回 0xAARRGGBB，若需要旧格式需将 0x 前缀替换为 #。
+     */
+    static rgbaHexToArgb(rgbaHex: string): string;
+    /**
+     * 普通6位Hex+透明度 → 直接返回ARGB对应的十进制数值
+     * @param hex 支持 #fff / #ffffff 格式
+     * @param alpha 透明度 0-1
+     * @returns ARGB十进制数值
+     * @deprecated 即将移除，使用 {@link CrColorUtil.setAlpha} + {@link CrColorUtil.toArgb}
+     * 替代：CrColorUtil.toArgb(CrColorUtil.setAlpha(hex, alpha, 'object')!, 'number')。
+     */
+    static hexAlphaToArgbNumber(hex: string, alpha?: number): number;
+    /**
+     * ARGB十进制数值 → 解析出 普通Hex + 0-1透明度
+     * @param num ARGB十进制数值
+     * @returns { hex: '#ffffff', alpha: 0.5 }
+     * @deprecated 即将移除。纯新 API 暂无简洁等价；可先将 number 转成 #RRGGBBAA，
+     * 再用 {@link CrColorUtil.parseHex} 解析，若需要旧返回结构需自行组装 { hex, alpha }。
+     */
+    static argbNumberToHexAlpha(num: number): {
+        hex: string;
+        alpha: number;
+    };
+}

package/dist/{cjs → types}/eventCenter.d.ts

@@ -1,13 +1,13 @@
-export type TSubscribers = {
+export interface TSubscribers {
     key: string;
     listeners: Array<(...args: any) => void>;
-};
-export type TSubscription = {
+}
+export interface TSubscription {
     key: string;
     listener: (...args: any) => void;
     remove: () => void;
-};
-export default class CrEventCenter {
+}
+export declare class CrEventCenter {
     /**
      * 储存订阅者
      */