# harmony-utils

**Repository Path**: Fie_Ryan/harmony-utils

## Basic Information

- **Project Name**: harmony-utils
- **Description**: HarmonyOS工具库，集成了开发中常用的一系列的功能和操作，封装了常用的工具类，能够满足各种不同的开发需求。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-02
- **Last Updated**: 2025-10-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: 鸿蒙, ArkTS, 常用工具类

## README

# @ryan/harmony-utils (API12+)

HarmonyOS工具库，集成了开发中常用的一系列的功能和操作，封装了常用的工具类，能够满足各种不同的开发需求。

## 安装

### 安装

```
ohpm i @ryan/harmony-utils
```

## CommonUtils 工具类

```extendtypescript
/**
 * 公共工具类
 */
export default class CommonUtils {
  /**
   * 检查目标是否为null或undefined
   * @param target 要检查的目标
   * @returns 如果是null或undefined则返回true，否则返回false
   */
  public static isNullOrUndefined<T>(target: T | null | undefined): boolean;

  /**
   * 检查目标是否为空值（null/undefined/空字符串/空数组/空对象）
   * @param target 要检查的目标
   * @returns 如果为空则返回true，否则返回false
   */
  public static isEmpty(target: object): boolean;

  /**
   * 检查目标是否为非空值（与isEmpty相反）
   * @param target 要检查的目标
   * @returns 如果为非空则返回true，否则返回false
   */
  public static isNotEmpty(target: object): boolean;

  /**
   * 安全地将值转换为数组，如果已经是数组则返回原值，否则包装为数组
   * @param value 要转换的值
   * @returns 数组
   */
  public static toArray<T>(value: object): T[];
}
```

## MapUtils 工具类

```extendtypescript
/**
 * Map 对象工具类，提供各种 Map 与数组/对象之间的转换及 Map 元素操作方法
 */
export default class MapUtils extends CommonUtils {
  /**
   * 将 Map 转换为包含键值对的二维数组
   * @param map 要转换的 Map 对象
   * @returns 包含键值对的二维数组，格式为 [[key1, value1], [key2, value2], ...]
   */
  public static map2Array<K, V>(map: Map<K, V>): [K, V][];


  /**
   * 获取 Map 中所有键值对条目
   * @param map 目标 Map 对象
   * @returns 包含所有键值对的数组
   */
  public static mapEntries2Array<K, V>(map: Map<K, V>): [K, V][];

  /**
   * 获取 Map 中所有键
   * @param map 目标 Map 对象
   * @returns 包含所有键的数组
   */
  public static mapKeys2Array<K, V>(map: Map<K, V>): K[];

  /**
   * 获取 Map 中所有值
   * @param map 目标 Map 对象
   * @returns 包含所有值的数组
   */
  public static mapValues2Array<K, V>(map: Map<K, V>): V[];

  /**
   * 获取 Map 中的最后一个条目
   * @param map 目标 Map 对象
   * @returns Map 中的最后一个键值对，若 Map 为空则返回 undefined
   */
  public static lastEntry<K, V>(map: Map<K, V>): [K, V] | undefined;

  /**
   * 获取 Map 中的第一个条目
   * @param map 目标 Map 对象
   * @returns Map 中的第一个键值对，若 Map 为空则返回 undefined
   */
  public static firstEntry<K, V>(map: Map<K, V>): [K, V] | undefined;

  /**
   * 将对象转换为 Map
   * @param obj 要转换的对象
   * @returns 转换后的 Map 对象
   */
  public static fromObject<K extends string | number, V>(obj: Record<K, V>): Map<K, V>;

  /**
   * 将 Map 转换为对象
   * @param map 要转换的 Map 对象
   * @returns 转换后的对象
   */
  public static toObject<K extends string | number, V>(map: Map<K, V>): Record<K, V>;

  /**
   * 检查 Map 是否包含指定的键
   * @param map 目标 Map 对象
   * @param key 要检查的键
   * @returns 如果包含指定的键则返回 true，否则返回 false
   */
  public static hasKey<K, V>(map: Map<K, V>, key: K): boolean;

  /**
   * 检查 Map 是否包含指定的值
   * @param map 目标 Map 对象
   * @param value 要检查的值
   * @returns 如果包含指定的值则返回 true，否则返回 false
   */
  public static hasValue<K, V>(map: Map<K, V>, value: V): boolean;

  /**
   * 检查 Map 是否为空
   * @param map 目标 Map 对象
   * @returns 如果为空则返回 true，否则返回 false
   */
  public static isEmpty<K, V>(map: Map<K, V>): boolean;

  /**
   * 检查 Map 是否不为空
   * @param map 目标 Map 对象
   * @returns 如果不为空则返回 true，否则返回 false
   */
  public static isNotEmpty<K, V>(map: Map<K, V>): boolean;
}
```

## ColorUtils 工具类

```extendtypescript
/**
 * 颜色转换工具类
 * 提供HSV、RGB、HEX等颜色空间之间的相互转换功能
 */
export default class ColorUtils {
  // ========================== 类型定义 ==========================
  /** RGB颜色类型：[红(0-255), 绿(0-255), 蓝(0-255)] */
  public static readonly RGB = [0, 0, 0];
  /** HSV颜色类型：[色相(0-360), 饱和度(0-100), 明度(0-100)] */
  public static readonly HSV = [0, 0, 0];
  /** RGBA颜色类型：[红(0-255), 绿(0-255), 蓝(0-255), 透明度(0-1)] */
  public static readonly RGBA = [0, 0, 0, 1];
  /** HSVA颜色类型：[色相(0-360), 饱和度(0-100), 明度(0-100), 透明度(0-1)] */
  public static readonly HSVA = [0, 0, 0, 1];

  /**
   * 将HSV颜色值转换为RGB颜色值
   * @param h 色相 (0-360)
   * @param s 饱和度 (0-100)
   * @param v 明度 (0-100)
   * @returns RGB值数组 [红(0-255), 绿(0-255), 蓝(0-255)]
   */
  public static hsv2rgb(h: number, s: number, v: number): [number, number, number];

  /**
   * 将RGB颜色值转换为HEX颜色字符串
   * @param r 红色值 (0-255)
   * @param g 绿色值 (0-255)
   * @param b 蓝色值 (0-255)
   * @returns HEX颜色字符串 (如: #ff0088)
   */
  public static rgb2hex(r: number, g: number, b: number): string;

  /**
   * 将RGB颜色值转换为HSV颜色值
   * @param r 红色值 (0-255)
   * @param g 绿色值 (0-255)
   * @param b 蓝色值 (0-255)
   * @returns HSV值数组 [色相(0-360), 饱和度(0-100), 明度(0-100)]
   */
  public static rgb2hsv(r: number, g: number, b: number): [number, number, number];

  /**
   * 将HEX颜色字符串转换为RGB颜色值
   * @param hex HEX颜色字符串
   * @returns RGB值数组 [红(0-255), 绿(0-255), 蓝(0-255)]
   */
  public static hex2rgb(hex: string): [number, number, number];


  /**
   * 将HEX颜色字符串转换为HSV颜色值
   * @param hex HEX颜色字符串
   * @returns HSV值数组 [色相(0-360), 饱和度(0-100), 明度(0-100)]
   */
  public static hex2hsv(hex: string): [number, number, number];

  /**
   * 为HEX颜色添加透明度通道
   * @param hex HEX颜色字符串
   * @param alpha 透明度 (0-1)
   * @returns 带透明度的HEX颜色字符串
   */
  public static hex2hexa(hex: string, alpha: number): string;

  /**
   * 将HSVA颜色值转换为HEX颜色字符串
   * @param h 色相 (0-360)
   * @param s 饱和度 (0-100)
   * @param v 明度 (0-100)
   * @param alpha 透明度 (0-1，默认1)
   * @returns HEX颜色字符串
   */
  public static hsva2hex(h: number, s: number, b: number, alpha: number = 1): string;

  /**
   * 将HEX颜色字符串转换为HSVA颜色值
   * @param hex HEX颜色字符串
   * @returns HSVA值数组 [色相(0-360), 饱和度(0-100), 明度(0-100), 透明度(0-1)]
   */
  public static hex2hsva(hex: string): [number, number, number, number];
}

```

## RandomUtils 工具类

```extendtypescript
/**
 * 生成随机数工具类
 */
export default class RandomUtils {
  /**
   * 生成指定位数的随机字符串
   * @param length 要生成的随机字符长度，必须大于0
   * @param charset 可选，自定义字符集，默认包含大小写字母、数字和常用符号
   * @param secure 是否使用加密安全的随机生成器，默认false
   * @returns 生成的随机字符串
   * @throws {Error} 当要生成的随机字符串为0或字符集为空时抛出错误
   */
  public static generateRandomString(length: number, charset: string = RandomUtils.FULL_CHARSET,
    secure: boolean = false): string;

  /**
   * 生成指定范围内的随机整数
   * @param min 最小值（包含）
   * @param max 最大值（包含）
   * @param secure 是否使用加密安全的随机生成器，默认false
   * @returns 生成的随机整数
   */
  public static generateRandomInt(min: number, max: number, secure: boolean = false): number;

  /**
   * 生成只包含字母的随机字符串
   * @param length 字符串长度
   * @param includeUppercase 是否包含大写字母，默认true
   * @param secure 是否使用加密安全的随机生成器
   * @returns 生成的随机字母字符串
   */
  public static generateAlphaString(length: number, includeUppercase: boolean = true, secure: boolean = false): string;

  /**
   * 生成只包含数字的随机字符串
   * @param length 字符串长度
   * @param secure 是否使用加密安全的随机生成器
   * @returns 生成的随机数字字符串
   */
  public static generateNumericString(length: number, secure: boolean = false): string;

  /**
   * 从数组中随机选择一个元素
   * @param array 源数组
   * @param secure 是否使用加密安全的随机生成器
   * @returns 随机选中的元素
   * @throws {Error} 当源数组为空时抛出错误
   */
  public static pickRandom<T>(array: T[], secure: boolean = false): T;
}
```