org.eframework.uni.util
Version:
EFramework Utility for Unite 是一个轻量级、跨平台的工具集，提供了统一的 API 接口，确保在多平台环境下保持一致的运行结果。
2,152 lines (2,141 loc) • 62.6 kB
TypeScript
/**
* XCollect 提供了集合工具，实现了数组/列表的增删改查、排序等功能。
*
* 功能特性
* - 支持条件查找：通过传入条件函数查找特定元素或索引
* - 支持元素操作：增加、删除、插入元素到指定位置
* - 提供批量操作：批量添加、批量删除、截取范围
* - 实现排序功能：通过自定义比较函数对列表进行排序
*
* 使用手册
* 1. 元素查找
*
* 1.1 Find - 查找满足条件的元素
* ```typescript
* const list = [1, 2, 3];
* const item = XCollect.Find(list, x => x > 2); // 返回 3
* ```
*
* 1.2 Index - 查找满足条件的元素索引
* ```typescript
* const list = [1, 2, 3];
* const index = XCollect.Index(list, x => x > 2); // 返回 2
* ```
*
* 1.3 Exist - 检查是否存在满足条件的元素
* ```typescript
* const list = [1, 2, 3];
* const exists = XCollect.Exist(list, x => x > 2); // 返回 true
* ```
*
* 2. 元素操作
*
* 2.1 Insert - 在指定位置插入元素
* ```typescript
* const list = [1, 2, 3];
* XCollect.Insert(list, 4, 1); // 在索引1处插入元素4
* // list 变为 [1, 4, 2, 3]
* ```
*
* 2.2 Delete - 删除指定索引的元素
* ```typescript
* const list = [1, 2, 3];
* XCollect.Delete(list, 1);
* // list 变为 [1, 3]
* ```
*
* 2.3 Remove - 移除满足条件的第一个元素
* ```typescript
* const list = [1, 2, 3, 4];
* XCollect.Remove(list, x => x > 2); // 移除第一个大于2的元素
* // list 变为 [1, 2, 4]
* ```
*
* 3. 批量操作
*
* 3.1 AddRange - 批量添加元素
* ```typescript
* const list = [1, 2];
* XCollect.AddRange(list, [3, 4]);
* // list 变为 [1, 2, 3, 4]
* ```
*
* 3.2 DeleteRange - 批量删除元素
* ```typescript
* const list = [1, 2, 3, 4, 5];
* XCollect.DeleteRange(list, 1, 2);
* // list 变为 [1, 4, 5]
* ```
*
* 3.3 SubRange - 截取元素范围
* ```typescript
* const list = [1, 2, 3, 4, 5];
* const sub = XCollect.SubRange(list, 1, 3);
* // 返回 [2, 3, 4]
* ```
*
* 4. 元素排序
*
* 4.1 Sort - 自定义排序
* ```typescript
* const list = [3, 1, 4, 2];
* XCollect.Sort(list, (a, b) => a < b); // 升序排序
* // list 变为 [1, 2, 3, 4]
* ```
*
* 更多信息请参考模块文档。
*/
declare namespace XCollect {
/**
* 根据条件从列表中移除元素。
* 遍历列表查找第一个满足条件的元素并移除。
*
* @param list 列表实例。
* @param cond 条件函数，返回 true 表示要移除该元素。
* @returns 如果成功移除元素返回 true，否则返回 false。
* @example
* ```typescript
* const list = [1, 2, 3, 4];
* XCollect.Remove(list, x => x > 2); // 移除第一个大于2的元素
* // list 变为 [1, 2, 4]
* ```
*/
function Remove<T>(list: Array<T>, cond: (item: T) => boolean): boolean;
/**
* 将元素插入到列表的指定位置。
* 如果索引为 -1 或超出列表长度，则插入到列表末尾。
*
* @param list 列表实例。
* @param ele 要插入的元素。
* @param idx 插入位置的索引，默认为 -1（表示插入到列表末尾）。
* @example
* ```typescript
* const list = [1, 2, 3];
* XCollect.Insert(list, 4, 1); // 在索引1处插入元素4
* // list 变为 [1, 4, 2, 3]
* ```
*/
function Insert(list: Array<any>, ele: any, idx?: number): void;
/**
* 对列表进行排序。
* 使用自定义比较函数进行排序，原地修改列表。
*
* @param list 列表实例。
* @param func 排序函数，返回 true 表示 o1 应该排在 o2 前面。
* @example
* ```typescript
* const list = [3, 1, 4, 2];
* XCollect.Sort(list, (a, b) => a < b); // 升序排序
* // list 变为 [1, 2, 3, 4]
* ```
*/
function Sort<T>(list: T[], func: (o1: T, o2: T) => boolean): void;
/**
* 检查列表中是否存在满足条件的元素。
*
* @param list 列表实例。
* @param cond 条件函数，返回 true 表示找到目标元素。
* @returns 如果存在满足条件的元素返回 true，否则返回 false。
* @example
* ```typescript
* const list = [1, 2, 3];
* const exists = XCollect.Exist(list, x => x > 2); // true
* ```
*/
function Exist<T>(list: T[], cond: (item: T) => boolean): boolean;
/**
* 在列表中查找满足条件的第一个元素。
*
* @param list 列表实例。
* @param cond 条件函数，返回 true 表示找到目标元素。
* @returns 返回第一个满足条件的元素，如果没有找到则返回 null。
* @example
* ```typescript
* const list = [1, 2, 3];
* const item = XCollect.Find(list, x => x > 2); // 返回 3
* ```
*/
function Find<T>(list: T[], cond: (item: T) => boolean): T;
/**
* 在列表中查找满足条件的第一个元素的索引。
*
* @param list 列表实例。
* @param cond 条件函数，返回 true 表示找到目标元素。
* @returns 返回第一个满足条件的元素的索引，如果没有找到则返回 -1。
* @example
* ```typescript
* const list = [1, 2, 3];
* const index = XCollect.Index(list, x => x > 2); // 返回 2
* ```
*/
function Index<T>(list: T[], cond: (item: T) => boolean): number;
/**
* 从列表中删除指定索引位置的元素。
* 如果索引超出范围，则不执行任何操作。
*
* @param list 列表实例。
* @param idx 要删除元素的索引。
* @example
* ```typescript
* const list = [1, 2, 3];
* XCollect.Delete(list, 1);
* // list 变为 [1, 3]
* ```
*/
function Delete(list: Array<any>, idx: number): void;
/**
* 从列表中截取一段元素，返回新的数组。
* 不修改原列表。
*
* @param list 列表实例。
* @param start 开始索引，默认为 0。
* @param end 结束索引（包含），默认为 -1（表示截取到列表末尾）。
* @returns 返回截取的元素数组。
* @example
* ```typescript
* const list = [1, 2, 3, 4, 5];
* const sub = XCollect.SubRange(list, 1, 3); // 返回 [2, 3, 4]
* ```
*/
function SubRange<T>(list: T[], start?: number, end?: number): T[];
/**
* 将一组元素添加到列表末尾。
* 支持数组、Set、Map等可迭代对象。
*
* @param list 列表实例。
* @param eles 要添加的元素集合。
* @example
* ```typescript
* const list = [1, 2];
* XCollect.AddRange(list, [3, 4]);
* // list 变为 [1, 2, 3, 4]
* ```
*/
function AddRange<T>(list: Array<T>, eles: Iterable<T> | ArrayLike<T>): void;
/**
* 从列表中删除一段元素。
* 从指定索引开始删除指定数量的元素。
*
* @param list 列表实例。
* @param idx 开始删除的索引。
* @param length 要删除的元素数量，默认删除到列表末尾。
* @example
* ```typescript
* const list = [1, 2, 3, 4, 5];
* XCollect.DeleteRange(list, 1, 2);
* // list 变为 [1, 4, 5]
* ```
*/
function DeleteRange(list: Array<any>, idx: number, length?: number): void;
}
/**
* XEnv 是一个环境管理工具，支持多平台及运行时环境识别等功能。
*
* 功能特性
* - 环境检测：自动识别运行环境及平台等信息
* - 应用信息：获取产品名称、版本、作者、标识符等信息
*
* 使用手册
* 1. 环境检测
*
* 1.1 运行时类型
* ```typescript
* // 运行时类型枚举
* enum RuntimeType {
* Node, // Node.js 运行时
* Code, // VSCode 扩展运行时
* Cocos, // Cocos Creator 运行时
* Unity, // Unity 运行时
* Unreal, // Unreal Engine 运行时
* Electron,// Electron 运行时
* Dom // 浏览器 DOM 运行时
* }
*
* // 获取当前运行时类型
* const runtime = XEnv.Runtime; // 返回RuntimeType枚举值
*
* // 使用预定义常量检查特定运行时
* if (XEnv.IsNode) {
* // Node.js环境下的逻辑
* }
* if (XEnv.IsCocos) {
* // Cocos环境下的逻辑
* }
* ```
*
* 1.2 平台类型
* ```typescript
* // 平台类型枚举
* enum PlatformType {
* Unknown, // 未知平台
* Windows, // Windows 平台
* Linux, // Linux 平台
* macOS, // macOS 平台
* Android, // Android 平台
* iOS, // iOS 平台
* Browser // 浏览器平台
* }
*
* // 获取当前平台类型
* const platform = XEnv.Platform; // 返回PlatformType枚举值
*
* // 使用预定义常量检查特定平台
* if (XEnv.IsNative) {
* // 原生平台下的逻辑
* }
* if (XEnv.IsBrowser) {
* // 浏览器环境下的逻辑
* }
* ```
*
* 2. 应用信息
*
* 2.1 获取基本信息
* ```typescript
* // 获取产品信息
* const appName = XEnv.Product;
* const appVersion = XEnv.Version;
* const appAuthor = XEnv.Author;
* const appId = XEnv.Identifier;
* const appDesc = XEnv.Description;
*
* console.log(`${appName} v${appVersion} by ${appAuthor}`);
* ```
*
* 更多信息请参考模块文档。
*/
declare namespace XEnv {
/**
* 运行时类型。
* 用于标识当前代码运行的环境类型。
*/
enum RuntimeType {
/** Node.js 运行时 */
Node = 0,
/** VSCode 扩展运行时 */
Code = 1,
/** Cocos Creator 运行时 */
Cocos = 2,
/** Unity 运行时 */
Unity = 3,
/** Unreal Engine 运行时 */
Unreal = 4,
/** Electron 运行时 */
Electron = 5,
/** 浏览器 DOM 运行时 */
Dom = 6
}
/**
* 平台类型。
* 用于标识当前运行的操作系统平台。
*/
enum PlatformType {
/** 未知平台 */
Unknown = 0,
/** Windows 平台 */
Windows = 1,
/** Linux 平台 */
Linux = 2,
/** macOS 平台 */
macOS = 3,
/** Android 平台 */
Android = 4,
/** iOS 平台 */
iOS = 5,
/** 浏览器平台 */
Browser = 6
}
/**
* 当前平台类型。
*/
const Platform: PlatformType;
/**
* 当前运行时类型。
*/
const Runtime: RuntimeType;
/**
* 是否为 Node 或 VSCode 运行时。
*/
const IsNode: boolean;
/**
* 是否为 VSCode 扩展运行时。
*/
const IsCode: boolean;
/**
* 是否为 Cocos Creator 运行时。
*/
const IsCocos: boolean;
/**
* 是否为 Unity 运行时。
*/
const IsUnity: boolean;
/**
* 是否为 Unreal 运行时。
*/
const IsUnreal: boolean;
/**
* 是否为原生平台。
*/
const IsNative: boolean;
/**
* 是否为浏览器平台。
*/
const IsBrowser: boolean;
/**
* 不支持的运行时和平台错误。
*/
const Unsupport: Error;
/**
* 数据路径。
*/
const LocalPath: string;
/**
* 产品名称。
*/
const Product: string;
/**
* 作者名称。
*/
const Author: string;
/**
* 获取标识符。
*
* @returns 标识符。
*/
function getIdentifier(): string;
/**
* 应用标识符。
*/
const Identifier: string;
/**
* 应用版本。
*/
const Version: string;
/**
* 应用描述。
*/
const Description: string;
}
/**
* XEvent 是一个轻量级的事件管理器，支持多重监听、单次回调等功能。
*
* 功能特性
* - 事件管理：提供完整的事件注册、注销和通知机制
* - 单次回调：可注册执行一次后自动注销的事件回调
*
* 使用手册
* 1. 管理器
*
* 1.1 创建管理器
* ```typescript
* // 创建允许多回调的事件管理器（默认模式）
* const eventManager = new XEvent.Manager();
*
* // 创建单回调模式的事件管理器
* const singleManager = new XEvent.Manager(false);
* ```
*
* 1.2 查询事件
* ```typescript
* // 获取特定事件的所有回调
* const callbacks = eventManager.Get(1001);
* if (callbacks) {
* console.log(`事件1001有${callbacks.length}个回调`);
* }
* ```
*
* 1.3 清除所有事件
* ```typescript
* // 清除管理器中的所有事件注册
* eventManager.Clear();
* ```
*
* 2. 注册与注销
*
* 2.1 注册事件回调
* ```typescript
* // 注册普通事件
* eventManager.Reg(1001, (data) => {
* console.log('收到事件:', data);
* });
*
* // 注册一次性事件（触发一次后自动注销）
* eventManager.Reg(1002, (data) => {
* console.log('这个回调只会执行一次:', data);
* }, true);
* ```
*
* 2.2 注销事件回调
* ```typescript
* // 定义回调函数
* const callback = (data) => {
* console.log('收到事件:', data);
* };
*
* // 注册事件
* eventManager.Reg(1001, callback);
*
* // 注销特定回调
* eventManager.Unreg(1001, callback);
*
* // 注销事件的所有回调
* eventManager.Unreg(1001);
* ```
*
* 3. 事件通知
*
* 3.1 触发事件
* ```typescript
* // 触发事件并传递多个参数
* eventManager.Notify(1002, 'action', 123, { detail: 'info' });
* ```
*
* 更多信息请参考模块文档。
*/
declare namespace XEvent {
/**
* 事件回调函数类型。
*
* @param args 事件参数，支持任意类型和数量的参数。
*/
type Callback = (...args: any[]) => void;
/**
* 事件管理器。
* 负责事件的注册、注销、触发等生命周期管理。
*/
class Manager {
protected multiple: boolean;
protected callbacks: Map<number, Callback[]>;
protected onces: Map<Callback, boolean>;
protected batches: Callback[];
/**
* 构造函数。
*
* @param multiple 是否允许同一事件注册多个回调，默认为 true。
*/
constructor(multiple?: boolean);
/**
* 清除所有事件注册。
*/
Clear(): void;
/**
* 获取指定事件的所有回调函数。
*
* @param eid 事件标识。
* @returns 返回事件回调函数数组，如果事件未注册则返回 null。
* @example
* ```typescript
* const callbacks = manager.Get(1001);
* if (callbacks) {
* console.log(`事件1001有${callbacks.length}个回调`);
* }
* ```
*/
Get(eid: number): Callback[] | null;
/**
* 注册事件回调。
*
* @param eid 事件标识。
* @param callback 回调函数。
* @param once 是否为一次性事件，默认为 false。
* @returns 是否成功注册。
* @example
* ```typescript
* manager.Reg(1001, (data) => {
* console.log('收到事件:', data);
* });
* ```
*/
Reg(eid: number, callback: Callback, once?: boolean): boolean;
/**
* 注销事件回调。
*
* @param eid 事件标识。
* @param callback 要注销的回调函数，如果不指定则注销该事件的所有回调。
* @returns 是否成功注销。
* @example
* ```typescript
* // 注销特定回调
* manager.Unreg(1001, callback);
* // 注销事件所有回调
* manager.Unreg(1001);
* ```
*/
Unreg(eid: number, callback?: Callback): boolean;
/**
* 触发事件。
*
* @param eid 事件标识。
* @param args 要传递给回调函数的参数。
* @example
* ```typescript
* manager.Notify(1001, { type: 'update', data: 'new value' });
* ```
*/
Notify(eid: number, ...args: any[]): void;
}
}
/**
* XFile 实现了跨平台的文件管理系统，支持在不同运行环境下进行统一的文件和目录操作。
*
* 功能特性
* - 支持文件和目录基本操作：创建、读写、删除、复制
* - 提供路径处理：规范化路径、合并路径、获取路径组成部分
* - 提供压缩解压功能：支持zip、7z等格式的文件压缩和解压
*
* 使用手册
* 1. 前置条件
*
* - Windows 环境需要安装 [7-Zip](https://www.7-zip.org/) 或 [WinRAR](https://www.win-rar.com/)
* - macOS 环境需要安装 p7zip：`brew install p7zip`
*
* 2. 文件操作
*
* 2.1 读写文件
* ```typescript
* // 检查文件是否存在
* if (XFile.HasFile("config.json")) {
* // 读取二进制文件
* const data = XFile.OpenFile("data.bin");
*
* // 读取文本文件
* const text = XFile.OpenText("config.json");
*
* // 写入二进制数据
* const buffer = new ArrayBuffer(8);
* XFile.SaveFile("output.bin", buffer);
*
* // 写入文本数据
* XFile.SaveText("log.txt", "操作成功");
* }
* ```
*
* 2.2 删除和复制文件
* ```typescript
* // 删除文件
* XFile.DeleteFile("temp.txt");
*
* // 复制文件
* XFile.CopyFile("source.dat", "backup/source.dat");
* ```
*
* 3. 目录操作
*
* 3.1 目录的创建与检查
* ```typescript
* // 检查目录是否存在
* if (!XFile.HasDirectory("logs")) {
* // 创建目录（支持多级目录递归创建）
* XFile.CreateDirectory("logs/app/debug");
* }
* ```
*
* 3.2 删除和复制目录
* ```typescript
* // 删除目录（包括所有子目录和文件）
* XFile.DeleteDirectory("temp");
*
* // 复制目录（包括所有子目录和文件）
* XFile.CopyDirectory("source", "backup/source");
* ```
*
* 4. 路径处理
*
* 4.1 路径操作
* ```typescript
* // 规范化路径（处理 . 和 .. 并统一分隔符）
* const normalPath = XFile.NormalizePath("dir/../data/./file.txt");
* // 结果: "data/file.txt"
*
* // 合并路径
* const fullPath = XFile.PathJoin("base", "subdir", "file.txt");
* // 结果: "base/subdir/file.txt"
* ```
*
* 4.2 路径组成部分
* ```typescript
* // 获取父目录
* const parent = XFile.DirectoryName("/path/to/file.txt");
* // 结果: "/path/to"
*
* // 获取文件名（带扩展名）
* const filename = XFile.FileName("/path/to/file.txt");
* // 结果: "file.txt"
*
* // 获取文件名（不带扩展名）
* const basename = XFile.FileName("/path/to/file.txt", false);
* // 结果: "file"
*
* // 获取文件扩展名
* const ext = XFile.FileExtension("/path/to/file.txt");
* // 结果: ".txt"
* ```
*
* 5. 压缩和解压
*
* 5.1 压缩目录
* ```typescript
* // 压缩目录到默认位置（目录名.zip）
* XFile.Zip("./dist", null, () => {
* console.log("压缩完成");
* });
*
* // 压缩目录到指定位置
* XFile.Zip("./dist", "./releases/app-1.0.0.zip", () => {
* console.log("压缩完成");
* });
* ```
*
* 5.2 解压文件
* ```typescript
* // 解压到指定目录
* XFile.Unzip("data.zip", "./extracted", () => {
* console.log("解压完成");
* });
* ```
*
* 6. 其他功能
*
* 6.1 在系统资源管理器中显示文件
* ```typescript
* // 在文件浏览器中打开并选中文件
* XFile.ShowInExplorer("./logs/error.log");
* ```
*
* 6.2 Base64编码文件操作
* ```typescript
* // 读取Base64编码的文件
* const data = XFile.OpenBase64("encoded.txt");
*
* // 保存为Base64编码的文件
* XFile.SaveBase64("encoded.txt", "原始数据");
* ```
*
* 更多信息请参考模块文档。
*/
declare namespace XFile {
/**
* 路径分隔符（POSIX风格）。
* 统一使用正斜杠(/)作为路径分隔符，Windows 平台下会自动转换。
*/
const Separator: string;
/**
* 检查文件是否存在。
*
* @param file 文件路径。
* @returns 文件是否存在。
* @example
* ```typescript
* if (XFile.HasFile("config.json")) {
* // 处理文件
* }
* ```
*/
function HasFile(file: string): boolean;
/**
* 打开文件。
* 读取文件内容到内存。
*
* @param file 文件路径。
* @returns 返回文件数据的 ArrayBuffer，如果文件不存在则返回 null。
* @example
* ```typescript
* const data = XFile.OpenFile("data.bin");
* if (data) {
* // 处理二进制数据
* }
* ```
*/
function OpenFile(file: string): ArrayBuffer;
/**
* 保存文件。
* 将数据写入文件，如果文件不存在则创建。
*
* @param file 文件路径。
* @param data 要写入的数据。
* @example
* ```typescript
* const buffer = new ArrayBuffer(8);
* XFile.SaveFile("output.bin", buffer);
* ```
*/
function SaveFile(file: string, data: ArrayBuffer): void;
/**
* 删除文件。
*
* @param file 文件路径。
* @example
* ```typescript
* XFile.DeleteFile("temp.txt");
* ```
*/
function DeleteFile(file: string): void;
/**
* 检查目录是否存在。
*
* @param dir 目录路径。
* @returns 目录是否存在。
* @example
* ```typescript
* if (!XFile.HasDirectory("logs")) {
* XFile.CreateDirectory("logs");
* }
* ```
*/
function HasDirectory(dir: string): boolean;
/**
* 创建目录。
* 支持递归创建多级目录。
*
* @param dir 目录路径。
* @example
* ```typescript
* XFile.CreateDirectory("data/cache/temp");
* ```
*/
function CreateDirectory(dir: string): void;
/**
* 压缩目录。
* 支持 zip、7z 等格式。
*
* @param dir 要压缩的目录路径。
* @param zip 压缩文件输出路径，默认为目录名加 .zip。
* @param func 压缩完成后的回调函数。
* @example
* ```typescript
* XFile.Zip("./dist", "./dist.zip", () => {
* console.log("压缩完成");
* });
* ```
*/
function Zip(dir: string, zip?: string, func?: Function): void;
/**
* 解压文件。
* 支持 zip、7z 等格式。
*
* @param zip 压缩文件路径。
* @param unzip 解压目标路径。
* @param func 解压完成后的回调函数。
* @example
* ```typescript
* XFile.Unzip("data.zip", "./data", () => {
* console.log("解压完成");
* });
* ```
*/
function Unzip(zip: string, unzip: string, func?: Function): void;
/**
* 在文件浏览器中显示文件或目录。
*
* @param path 文件或目录路径。
* @example
* ```typescript
* XFile.ShowInExplorer("./logs/error.log");
* ```
*/
function ShowInExplorer(path: string): void;
/**
* 打开文本文件。
*
* @param file 文件路径。
* @returns 文件内容作为字符串。
*/
function OpenText(file: string): string;
/**
* 保存文本文件。
*
* @param file 文件路径。
* @param text 文本数据。
*/
function SaveText(file: string, text: string): boolean | void;
/**
* 打开 Base64 编码的文本文件。
*
* @param file 文件路径。
* @returns 解码后的文本内容。
*/
function OpenBase64(file: string): string;
/**
* 保存 Base64 编码的文本文件。
*
* @param file 文件路径。
* @param data 文件数据。
*/
function SaveBase64(file: string, data: string): void;
/**
* 拷贝文件。
*
* @param from 源路径。
* @param to 目标路径。
*/
function CopyFile(from: string, to: string): void;
/**
* 拷贝文件夹。
*
* @param from 源路径。
* @param to 目标路径。
*/
function CopyDirectory(from: string, to: string): void;
/**
* 删除文件夹。
*
* @param dir 文件夹路径。
* @returns 文件夹是否被删除。
*/
function DeleteDirectory(dir: string): boolean;
/**
* 归一化路径。
*
* @param path 文件（夹）路径。
* @returns 归一化后的路径。
*/
function NormalizePath(path: string): string;
/**
* 路径合并。
*
* @param paths 要合并的路径。
* @returns 合并后的路径。
*/
function PathJoin(...paths: string[]): string;
/**
* 获取文件（夹）的父路径。
*
* @param path 文件（夹）路径。
* @returns 父路径。
*/
function DirectoryName(path: string): string;
/**
* 获取文件名称。
*
* @param path 文件（夹）路径。
* @param includeExtension 是否包含扩展名。
* @returns 文件名称。
*/
function FileName(path: string, includeExtension?: boolean): string;
/**
* 获取文件扩展名。
*
* @param path 路径。
* @returns 文件扩展名。
*/
function FileExtension(path: string): string;
}
/**
* XLog 提供了一个遵循 RFC5424 标准的日志系统，支持多级别输出和内置堆栈追踪。
*
* 功能特性
* - 支持多级别日志：基于 RFC5424 标准实现 8 个严重程度等级
* - 提供格式化功能：支持使用占位符格式化日志信息
* - 内置堆栈追踪：支持获取调用堆栈信息
*
* 使用手册
* 1. 记录不同级别的日志
*
* 1.1 基本用法
* ```typescript
* // 记录各种级别的日志
* XLog.Debug("调试信息");
* XLog.Info("普通信息");
* XLog.Notice("需要关注的信息");
* XLog.Warn("警告信息");
* XLog.Error("错误信息");
* XLog.Critical("严重错误");
* XLog.Alert("需要立即处理的错误");
* XLog.Emergency("系统不可用");
* ```
*
* 1.2 使用格式化参数
* ```typescript
* // 使用占位符格式化日志
* XLog.Info("用户 {0} 登录成功，等级: {1}", "张三", 10);
* XLog.Error("加载文件 {0} 失败: {1}", "config.json", "文件不存在");
* ```
*
* 2. 异常处理
*
* 2.1 记录异常信息
* ```typescript
* try {
* // 可能抛出异常的代码
* throw new Error("出现未知错误");
* } catch (error) {
* // 输出异常信息
* XLog.Panic(error, "处理数据时出错");
* }
* ```
*
* 2.2 获取堆栈信息
* ```typescript
* // 获取当前调用堆栈
* const stackTrace = XLog.Trace();
* XLog.Debug("当前堆栈: " + stackTrace);
*
* // 指定堆栈层级和错误信息
* const customTrace = XLog.Trace(1, "自定义错误");
* XLog.Debug("自定义堆栈: " + customTrace);
* ```
*
* 3. 日志级别定义
*
* 3.1 LevelType枚举
* ```typescript
* enum LevelType {
* Emergency = 0, // 紧急：系统不可用
* Alert = 1, // 警报：需要立即采取行动
* Critical = 2, // 严重：严重故障
* Error = 3, // 错误：一般错误
* Warn = 4, // 警告：潜在问题
* Notice = 5, // 通知：重要但正常的情况
* Info = 6, // 信息：一般信息
* Debug = 7 // 调试：调试信息
* }
* ```
*
* 更多信息请参考模块文档。
*/
declare namespace XLog {
/**
* 日志等级。
* 基于 RFC5424 标准，包含结构化数据格式。
* 指定了八个严重程度等级，用于表示记录事件的严重性或紧急程度。
*/
enum LevelType {
/** 紧急（0）：系统不可用，通常用于灾难性故障。 */
Emergency = 0,
/** 警报（1）：必须立即采取行动，指示需要立即注意的情况。 */
Alert = 1,
/** 严重（2）：严重条件，指示需要立即注意的严重故障。 */
Critical = 2,
/** 错误（3）：错误条件，指示应该解决的错误。 */
Error = 3,
/** 警告（4）：警告条件，指示潜在问题，如果不解决可能会导致错误。 */
Warn = 4,
/** 通知（5）：正常但重要的情况，指示值得注意但不一定有问题的事件。 */
Notice = 5,
/** 信息（6）：信息消息，用于系统操作的一般信息。 */
Info = 6,
/** 调试（7）：调试级别的消息，用于调试和故障排除目的的消息。 */
Debug = 7
}
/**
* 异常输出。
*
* @param exception 异常信息。
* @param extras 附加信息。
*/
function Panic(exception: Error, extras?: string): void;
/**
* 紧急（0）：系统不可用，通常用于灾难性故障。
*
* @param data 日志内容。
* @param args 格式参数。
*/
function Emergency(data: any, ...args: any[]): void;
/**
* 警报（1）：必须立即采取行动，指示需要立即注意的情况。
*
* @param data 日志内容。
* @param args 格式参数。
*/
function Alert(data: any, ...args: any[]): void;
/**
* 严重（2）：严重条件，指示需要立即注意的严重故障。
*
* @param data 日志内容。
* @param args 格式参数。
*/
function Critical(data: any, ...args: any[]): void;
/**
* 记录错误级别日志。
*
* @param data 日志内容。
* @param args 格式参数。
* @example
* ```typescript
* XLog.Error("Failed to load file: {0}", filename);
* ```
*/
function Error(data: any, ...args: any[]): void;
/**
* 记录警告级别日志。
*
* @param data 日志内容。
* @param args 格式参数。
* @example
* ```typescript
* XLog.Warn("Memory usage high: {0}%", memoryUsage);
* ```
*/
function Warn(data: any, ...args: any[]): void;
/**
* 通知（5）：正常但重要的情况，指示值得注意但不一定有问题的事件。
*
* @param data 日志内容。
* @param args 格式参数。
*/
function Notice(data: any, ...args: any[]): void;
/**
* 记录信息级别日志。
*
* @param data 日志内容。
* @param args 格式参数。
* @example
* ```typescript
* XLog.Info("Application started, version: {0}", version);
* ```
*/
function Info(data: any, ...args: any[]): void;
/**
* 记录调试级别日志。
*
* @param data 日志内容。
* @param args 格式参数。
* @example
* ```typescript
* XLog.Debug("Processing item {0} of {1}", current, total);
* ```
*/
function Debug(data: any, ...args: any[]): void;
/**
* 处理日志。
*
* @param fmt 日志格式。
* @param level 日志等级。
* @param args 格式化参数。
*/
function Print(fmt: any, level: LevelType, ...args: Array<any>): void;
/**
* 获取堆栈信息。
*
* @param stack 堆栈层级。
* @param err 错误信息。
* @returns 堆栈信息。
*/
function Trace(stack?: number, err?: string): string;
}
/**
* XObject 提供了对象操作工具集，支持类型判断、函数绑定、方法劫持等功能。
*
* 功能特性
* - 支持类型判断：判断对象是值类型、引用类型、函数类型或类
* - 实现方法劫持：替换和恢复对象方法
* - 提供对象复制：深度克隆对象及计算哈希码
* - 支持函数绑定：确保方法调用时保持正确的 this 引用
*
* 使用手册
* 1. 类型判断
*
* 1.1 基本类型判断
* ```typescript
* // 判断值类型（数字、字符串、布尔值）
* XObject.IsValue(123); // true
* XObject.IsValue("abc"); // true
* XObject.IsValue(true); // true
* XObject.IsValue(new Date()); // false
*
* // 判断引用类型（对象、数组等非值类型）
* XObject.IsObject({}); // true
* XObject.IsObject([]); // true
* XObject.IsObject(new Date()); // true
* XObject.IsObject(123); // false
* ```
*
* 1.2 函数和类判断
* ```typescript
* // 判断函数类型
* function fn() {}
* XObject.IsFunction(fn); // true
* XObject.IsFunction(() => {}); // true
*
* // 判断类
* class MyClass {}
* XObject.IsClass(MyClass); // true
* XObject.IsClass(fn); // false
* ```
*
* 2. 反射操作
*
* 2.1 键值访问
* ```typescript
* // 获取枚举值对应的键名
* enum Color { Red = 1, Green = 2, Blue = 3 }
* XObject.Key(Color, 2); // 返回 "Green"
*
* // 获取对象中键对应的值
* const obj = { name: "张三", age: 25 };
* XObject.Value(obj, "name"); // 返回 "张三"
* ```
*
* 2.2 反射调用
* ```typescript
* // 通过字符串调用对象方法
* const calculator = {
* add: (a, b) => a + b
* };
* XObject.Invoke(calculator, "add", 1, 2); // 返回 3
* ```
*
* 3. 对象操作
*
* 3.1 对象克隆
* ```typescript
* // 深度克隆对象
* const original = {
* name: "张三",
* info: { age: 25, scores: [90, 85, 92] },
* secret: "密码"
* };
* // 克隆时排除某些字段
* const cloned = XObject.Clone(original, "secret");
* // cloned 包含 name 和 info，但不包含 secret
* ```
*
* 3.2 计算哈希码
* ```typescript
* // 计算对象哈希码
* XObject.HashCode("abc"); // 计算字符串哈希
* XObject.HashCode([1, 2, 3]); // 计算数组哈希
* XObject.HashCode({a: 1, b: 2}); // 计算对象哈希
* ```
*
* 4. 方法劫持
*
* 4.1 替换和恢复方法
* ```typescript
* // 替换对象方法
* const obj = {
* greet() { console.log("你好"); }
* };
*
* // 保存原始方法并替换
* const original = XObject.Hook(obj, "greet", function() {
* console.log("替换后的问候");
* });
*
* obj.greet(); // 输出 "替换后的问候"
*
* // 恢复原始方法
* XObject.Unhook(obj, "greet");
* obj.greet(); // 输出 "你好"
* ```
*
* 5. 函数绑定
*
* 5.1 使用装饰器
* ```typescript
* class MyComponent extends XObject.Base {
* name = "组件1";
*
* @XObject.This()
* getName() {
* return this.name;
* }
* }
*
* const comp = new MyComponent();
* const getName = comp.getName;
* getName(); // 返回 "组件1"，即使脱离了对象上下文
* ```
*
* 5.2 继承Base类
* ```typescript
* // 继承Base类自动为标记的方法绑定this
* class Controller extends XObject.Base {
* status = "在线";
*
* @XObject.This()
* getStatus() {
* return this.status;
* }
* }
* ```
*
* 更多信息请参考模块文档。
*/
declare namespace XObject {
/**
* 函数this实例绑定器。
* 用于确保方法在任何上下文中调用时都保持正确的 this 引用。
*
* @returns 装饰器函数。
* @example
* ```typescript
* class MyClass {
* @XObject.This()
* myMethod() {
* // this 总是指向 MyClass 实例
* }
* }
* ```
*/
function This(): (target: any, propertyKey: string) => void;
/**
* 基础类型。
* 用于标识 JavaScript 的基本数据类型。
*/
class Base {
constructor();
}
/**
* 判断对象是否为值类型。
*
* @param obj 要判断的对象。
* @returns 如果是值类型返回 true，否则返回 false。
* @example
* ```typescript
* XObject.IsValue(123); // true
* XObject.IsValue(new Date()); // false
* ```
*/
function IsValue(obj: any): boolean;
/**
* 检查对象是否为引用类型。
*
* @param obj 对象实例。
* @returns 对象是否为引用类型。
*/
function IsObject(obj: any): boolean;
/**
* 检查对象是否为函数类型。
*
* @param obj 对象实例。
* @returns 对象是否为函数类型。
*/
function IsFunction(obj: any): boolean;
/**
* 判断对象是否为类。
*
* @param obj 要判断的对象。
* @returns 如果是类返回 true，否则返回 false。
* @example
* ```typescript
* class MyClass {}
* XObject.IsClass(MyClass); // true
* XObject.IsClass({}); // false
* ```
*/
function IsClass(obj: any): boolean;
/**
* 获取对象中某个值的键。
*
* @param obj 对象实例。
* @param value 值。
* @returns 值的键。
*/
function Key(obj: any, value: any): string;
/**
* 获取对象中某个键的值。
*
* @param obj 对象实例。
* @param key 键。
* @returns 键的值。
*/
function Value(obj: any, key: string): any;
/**
* 反射调用函数。
*
* @param obj 对象实例。
* @param key 键名称。
* @param args 参数。
* @returns 函数调用的结果。
*/
function Invoke(obj: any, key: string, ...args: any[]): any;
/**
* 对象克隆。
*
* @param obj 对象实例。
* @param exclude 忽略字段。
* @returns 克隆的对象。
*/
function Clone<T>(obj: any, ...exclude: Array<string>): T;
/**
* 对象实例哈希。
*
* @param obj 对象实例。
* @returns 哈希码。
*/
function HashCode(obj: any): number;
/**
* 替换对象的方法。
*
* @param obj 目标对象。
* @param from 要替换的方法名。
* @param to 新的方法实现。
* @returns 原始方法。
* @example
* ```typescript
* const obj = { method() { console.log('original'); } };
* XObject.Hook(obj, 'method', function() { console.log('hooked'); });
* ```
*/
function Hook(obj: any, from: string, to: Function): Function;
/**
* 恢复对象的原始方法。
*
* @param obj 目标对象。
* @param from 要恢复的方法名。
* @returns 原始方法。
* @example
* ```typescript
* XObject.Unhook(obj, 'method'); // 恢复原始方法
* ```
*/
function Unhook(obj: any, from: string): Function;
}
/**
* XString 提供了字符串处理工具集，支持查找、替换、格式化以及编码转换等功能。
*
* 功能特性
* - 支持字符串基本操作：判空、查找、截取、分割等常用功能
* - 提供字符串匹配检测：包含、前缀、后缀检查
* - 实现字符串格式化：使用占位符进行文本格式化
* - 提供编码转换：Base64 编码解码、文本与二进制互转
*
* 使用手册
* 1. 字符串基本操作
*
* 1.1 判空与检查
* ```typescript
* // 检查字符串是否为空
* XString.IsNullOrEmpty(""); // true
* XString.IsNullOrEmpty(null); // true
* XString.IsNullOrEmpty("hello"); // false
*
* // 字符串常量
* const emptyStr = XString.Empty; // 空字符串
* ```
*
* 1.2 查找与索引
* ```typescript
* // 查找子字符串位置
* XString.IndexOf("hello world", "world"); // 返回 6
* XString.LastIndexOf("hello.world.js", "."); // 返回 10
*
* // 检查是否包含子字符串
* XString.Contains("hello world", "world"); // true
* XString.Contains("hello world", "xyz"); // false
* ```
*
* 1.3 截取与分割
* ```typescript
* // 截取子字符串
* XString.Sub("hello world", 0, 5); // 返回 "hello"
*
* // 分割字符串
* XString.Split("a,b,c", ","); // 返回 ["a", "b", "c"]
* XString.Split("hello world", " "); // 返回 ["hello", "world"]
* ```
*
* 2. 字符串处理
*
* 2.1 修饰与替换
* ```typescript
* // 去除首尾空格
* XString.Trim(" hello "); // 返回 "hello"
*
* // 替换字符串
* XString.Replace("hello world", "world", "universe"); // 返回 "hello universe"
* ```
*
* 2.2 前缀后缀检查
* ```typescript
* // 检查前缀
* XString.StartsWith("hello world", "hello"); // true
* XString.StartsWith("hello world", "world"); // false
*
* // 检查后缀
* XString.EndsWith("hello world", "world"); // true
* XString.EndsWith("hello world", "hello"); // false
* ```
*
* 3. 字符串格式化
*
* 3.1 使用占位符格式化
* ```typescript
* // 简单替换
* XString.Format("Hello {0}!", "world"); // 返回 "Hello world!"
*
* // 多参数替换
* XString.Format("{0} + {1} = {2}", 1, 2, 3); // 返回 "1 + 2 = 3"
*
* // 复杂对象格式化
* const user = { name: "张三" };
* XString.Format("用户: {0}", user); // 返回 "用户: [object Object]"
* ```
*
* 4. 版本号处理
*
* 4.1 版本号转换
* ```typescript
* // 字符串版本号转为数字
* XString.ToVersion("1.2.3"); // 返回数字表示
* XString.ToVersion("v1.2"); // 同样可以处理
*
* // 数字版本号转为字符串
* XString.FromVersion(10203); // 返回 "1.2.3"
* ```
*
* 5. 编码转换
*
* 5.1 Base64编码
* ```typescript
* // 文本转Base64
* XString.ToBase64("Hello"); // 返回 "SGVsbG8="
*
* // Base64解码
* XString.FromBase64("SGVsbG8="); // 返回 "Hello"
* ```
*
* 5.2 二进制转换
* ```typescript
* // 字符串转ArrayBuffer
* const buffer = XString.ToBuffer("Hello");
*
* // ArrayBuffer转字符串
* const text = XString.FromBuffer(buffer); // 返回 "Hello"
* ```
*
* 更多信息请参考模块文档。
*/
declare namespace XString {
/**
* 空字符串。
*/
const Empty: string;
/**
* 判断字符串是否为空。
*
* @param str 要检查的字符串。
* @returns 如果字符串为 null、undefined 或空字符串返回 true。
* @example
* ```typescript
* XString.IsNullOrEmpty(""); // true
* XString.IsNullOrEmpty(null); // true
* XString.IsNullOrEmpty("hello"); // false
* ```
*/
function IsNullOrEmpty(str: string): boolean;
/**
* 字符串索引。
*
* @param str 源字符串。
* @param sub 要查找的子字符串。
* @returns 子字符串的索引，如果未找到返回 -1。
* @example
* ```typescript
* XString.IndexOf("hello world", "world"); // 返回 6
* XString.IndexOf("hello world", "xyz"); // 返回 -1
* ```
*/
function IndexOf(str: string, sub: string): number;
/**
* 查找子字符串最后一次出现的位置。
*
* @param str 源字符串。
* @param sub 要查找的子字符串。
* @returns 子字符串最后一次出现的索引，如果未找到返回 -1。
* @example
* ```typescript
* XString.LastIndexOf("hello.world.js", "."); // 返回 10
* XString.LastIndexOf("hello world", "o"); // 返回 7
* ```
*/
function LastIndexOf(str: string, sub: string): number;
/**
* 截取字符串的一部分。
*
* @param str 源字符串。
* @param start 起始位置。
* @param end 结束位置（不包含）。
* @returns 截取的子字符串。
* @example
* ```typescript
* XString.Sub("hello world", 0, 5); // 返回 "hello"
* ```
*/
function Sub(str: string, from: number, to: number): string;
/**
* 字符串替换。
*
* @param str 字符串实例。
* @param from 源字符串。
* @param to 目标字符串。
* @returns 替换后的字符串。
*/
function Replace(str: string, from: string, to: string): string;
/**
* 字符串裁剪。
*
* @param str 字符串实例。
* @returns 裁剪后的字符串。
*/
function Trim(str: string): string;
/**
* 字符串分割。
*
* @param str 源字符串。
* @param sep 分隔符。
* @returns 分割后的子字符串数组。
* @example
* ```typescript
* XString.Split("a,b,c", ","); // 返回 ["a", "b", "c"]
* XString.Split("hello world", " "); // 返回 ["hello", "world"]
* ```
*/
function Split(str: string, sep: string): string[];
/**
* 字符串是否包含。
*
* @param str 源字符串。
* @param sub 要查找的子字符串。
* @returns 是否包含指定的子字符串。
* @example
* ```typescript
* XString.Contains("hello world", "world"); // 返回 true
* XString.Contains("hello world", "xyz"); // 返回 false
* ```
*/
function Contains(str: string, sub: string): boolean;
/**
* 字符串头部匹配。
*
* @param str 源字符串。
* @param prefix 前缀字符串。
* @returns 是否以指定字符串开头。
* @example
* ```typescript
* XString.StartsWith("hello world", "hello"); // 返回 true
* XString.StartsWith("hello world", "world"); // 返回 false
* ```
*/
function StartsWith(str: string, prefix: string): boolean;
/**
* 字符串尾部匹配。
*
* @param str 源字符串。
* @param suffix 后缀字符串。
* @returns 是否以指定字符串结尾。
* @example
* ```typescript
* XString.EndsWith("hello world", "world"); // 返回 true
* XString.EndsWith("hello world", "hello"); // 返回 false
* ```
*/
function EndsWith(str: string, suffix: string): boolean;
/**
* 格式化字符串。
* 使用 {n} 作为占位符，n 为参数索引。
*
* @param format 格式字符串。
* @param args 格式化参数。
* @returns 格式化后的字符串。
* @example
* ```typescript
* XString.Format("Hello {0}!", "world"); // 返回 "Hello world!"
* XString.Format("{0} + {1} = {2}", 1, 2, 3); // 返回 "1 + 2 = 3"
* ```
*/
function Format(fmt: string, ...args: Array<any>): string;
/**
* 将字符串转换为版本号。
* 支持多级版本号格式。
*
* @param str 版本号字符串。
* @returns 标准化的版本号字符串。
* @example
* ```typescript
* XString.ToVersion("1.2.3"); // 返回 "1.2.3"
* XString.ToVersion("v1.2"); // 返回 "1.2.0"
* ```
*/
function ToVersion(version: string): number;
/**
* 数字转版本号。
*
* @param version 版本号数字。
* @returns 版本号字符串。
*/
function FromVersion(version: number): string;
/**
* 将字符串转换为 ArrayBuffer。
*
* @param str 要转换的字符串。
* @returns ArrayBuffer 对象。
* @example
* ```typescript
* const buffer = XString.ToBuffer("Hello");
* ```
*/
function ToBuffer(str: string): ArrayBuffer;
/**
* 将 ArrayBuffer 转换为字符串。
*
* @param buffer ArrayBuffer 对象。
* @returns 转换后的字符串。
* @example
* ```typescript
* const str = XString.FromBuffer(buffer);
* ```
*/
function FromBuffer(buf: ArrayBuffer): string;
/**
* 将字符串转换为 Base64 编码。
*
* @param str 要编码的字符串。
* @returns Base64 编码的字符串。
* @example
* ```typescript
* XString.ToBase64("Hello"); // 返回 "SGVsbG8="
* ```
*/
function ToBase64(str: string): string;
/**
* 将 Base64 编码转换为字符串。
*
* @param str Base64 编码的字符串。
* @returns 解码后的字符串。
* @example
* ```typescript
* XString.FromBase64("SGVsbG8="); // 返回 "Hello"
* ```
*/
function FromBase64(str: string): string;
}
/**
* XTest 提供了轻量级测试框架，支持 Jest 集成和独立运行两种模式。
*
* 功能特性
* - 提供断言功能：丰富的值比较和类型检查断言
* - 提供详细日志：自动记录环境信息和执行时间
*
* 使用手册
* 1. 基本测试
*
* 1.1 创建测试用例
* ```typescript
* // 定义一个简单的测试用例
* XTest.Test("加法测试", async () => {
* const result = 1 + 2;
* XTest.Expect(result).ToBe(3);
* });
* ```
*
* 1.2 运行测试
* ```typescript
* // 在Jest环境中自动运行
* // 在独立环境中需要手动执行返回的函数
*
* // 创建并立即执行测试
* (XTest.Test("独立环境测试", async () => {
* // 测试代码
* }))();
* ```
*
* 2. 断言功能
*
* 2.1 值比较断言
* ```typescript
* // 等值比较
* XTest.Expect(2 + 2).ToBe(4);
*
* // 大小比较
* XTest.Expect(5).ToBeGreaterThan(3);
* XTest.Expect(5).ToBeGreaterThanOrEqual(5);
* XTest.Expect(3).ToBeLessThan(5);
* XTest.Expect(3).ToBeLessThanOrEqual(3);
* ```
*
* 2.2 类型检查断言
* ```typescript
* // null检查
* XTest.Expect(null).ToBeNull();
* XTest.Expect(undefined).Not.ToBeNull();
*
* // undefined检查
* XTest.Expect(undefined).ToBeUndefined();
* XTest.Expect("hello").Not.ToBeUndefined();
*
* // NaN检查
* XTest.Expect(NaN).ToBeNaN();
* XTest.Expect(123).Not.ToBeNaN();
* ```
*
* 3. 断言标签
*
* 3.1 使用标签提高可读性
* ```typescript
* // 添加描述性标签
* const score = 85;
* XTest.Expect(score, "考试分数").ToBeGreaterThan(60);
*
* // 添加额外参数提供上下文
* const user = { name: "张三", age: 25 };
* XTest.Expect(user.age, "用户年龄", user).ToBeGreaterThan(18);
* ```
*
* 3.2 否定断言
* ```typescript
* // 使用Not属性进行否定断言
* XTest.Expect("hello").Not.ToBe("world");
* XTest.Expect(null).Not.ToBeUndefined();
* ```
*
* 4. 完整测试示例
*
* 4.1 综合应用
* ```typescript
* XTest.Test("用户验证测试", async () => {
* // 模拟用户数据
* const user = {
* id: 1001,
* name: "张三",
* age: 25,
* isActive: true
* };
*
* // 执行多个断言
* XTest.Expect(user.id, "用户ID").ToBeGreaterThan(0);
* XTest.Expect(user.name, "用户名称").Not.ToBeNull();
* XTest.Expect(user.age, "用户年龄").ToBeGreaterThanOrEqual(18);
* XTest.Expect(user.isActive, "账户状态").ToBe(true);
* });
* ```
*
* 更多信息请参考模块文档。
*/
declare namespace XTest {
/**
* Jest环境。
*/
const IsJest: boolean;
/**
* 定义一个测试用例。
*
* @param name 测试用例名称。
* @param fn 测试用例函数。
* @example
* ```typescript
* XTest.Test("should add numbers", async () => {
* const result = 1 + 2;
* XTest.Expect(result).ToBe(3);
* });
* ```
*/
function Test(name: string, fn: () => Promise<void>): () => Promise<void>;
/**
* 创建一个测试断言。
*
* @param obj 要测试的对象。
* @param tag 断言标签，用于标识断言的来源。
* @param args 附加参数，用于提供更多上下文信息。
* @returns 断言对象。
* @example
* ```typescript
* XTest.Expect(value, "计算结果").ToBe(expected);
* XTest.Expect(array.length, "数组长度").ToBeGreaterThan(0);
* ```
*/
function Expect(obj: any, tag?: string, ...args: any[]): Assert;
/**
* 测试断言类。
* 提供丰富的断言方法，支持值比较、类型检查等。
*/
class Assert {
Obj: any;
Tag: string;
Args: any[];
IsNot: boolean;
private mJObj;
/**
* 构造函数。
*
* @param obj 测试对象。
* @param tag 可选标签。
* @param args 可选参数。
*/
constructor(obj: any, tag?: string, ...args: any[]);
/**
* 否定断言。
* 反转下一个断言的结果。
*
* @returns 当前断言实例。
* @example
* ```typescript
* XTest.Expect(value).Not.ToBeNull();
* XTest.Expect(array).Not.ToBe(empty);
* ```
*/
get Not(): Assert;
/**
* 检查对象是否等于预期值。
* 使用严格相等(===)进行比较。
*
* @param expected 预期值。
* @returns 断言是否通过。
* @example
* ```typescript
* XTest.Expect(2 + 2).ToBe(4);
* XTest.Expect("hello").Not.ToBe("world");
* ```
*/
ToBe(expected: any): boolean;
/**
* 检查对象是否大于预期值。
*
* @param expected 预期值。
* @returns 断言是否通过。
* @example
* ```typescript
* XTest.Expect(5).ToBeGreaterThan(3);
* XTest.Expect(score).ToBeGreaterThan(passingScore);
* ```
*/
ToBeGreaterThan(expected: number): boolean;
/**
* 检查对象是否大于或等于预期值。
*
* @param expected 预期值。
* @returns 断言是否通过。
*/
ToBeGreaterThanOrEqual(expected: number): boolean;
/**
* 检查对象是否小于预期值。
*
* @param expected 预期值。
* @returns 断言是否通过。
*/
ToBeLessThan(expected: number): boolean;
/**
* 检查对象是否小于或等于预期值。
*
* @param expected 预期值。
* @returns 断言是否通过。
*/
ToBeLessThanOrEqual(expected: number): boolean;
/**
* 检查对象是否为 null。
*
* @returns 断言是否通过。
* @example
* ```typescript
* XTest.Expect(null).ToBeNull();
* XTest.Expect(value).Not.ToBeNull();
* ```
*/
ToBeNull(): boolean;
/**
* 检查对象是否为 undefined。
*
* @returns 断言是否通过。
*/
ToBeUndefined(): boolean;
/**
* 检查对象是否为 NaN。
*
* @returns 断言是否通过。
*/
ToBeNaN(): boolean;
}
}
/**
* XTime 提供了时间处理工具，支持日期格式化和时间戳转换等常用时间操作。
*
* 功能特性
* - 日期格式化：支持自定义格式模板的日期展示
* - 时间戳转换：支持获取秒级和毫秒级时间戳
*
* 使用手册
* 1. 日期格式化
*
* 1.1 基本用法
* ```typescript
* // 格式化当前日期
* const now = new Date();
* const formattedDate = XTime.Format(now, "yyyy-MM-dd hh:mm:ss"); // 例如："2025-01-28 14:30:00"
* const chineseDate = XTime.Format(now, "yyyy年MM月dd日"); // 例如："2025年01月28日"
* ```
*
* 1.2 支持的格式化占位符
* - yyyy: 年份
* - MM: 月份，补零
* - dd: 日期，补零
* - hh: 小时，补零
* - mm: 分钟，补零
* - ss: 秒钟，补零
* - SSS: 毫秒，补零
* - q: 季度
*
* 2. 获取时间戳
*
* 2.1 基本用法
* ```typescript
* // 获取秒级时间戳
* const timestampInSeconds = XTime.GetTimestamp(); // 例如：1706428800
*
* // 获取毫秒级时间戳
* const timestampInMilliseconds = XTime.GetMilliSecond(); // 例如：1706428800000
* ```
*
* 更多信息请参考模块文档。
*/
declare namespace XTime {
/**
* 格式化日期时间。
* 支持以下格式化占位符：
* - yyyy: 年份
* - MM: 月份，补零
* - dd: 日期，补零
* - hh: 小时，补零
* - mm: 分钟，补零
* - ss: 秒钟，补零
* - SSS: 毫秒，补零
* - q: 季度
*
* @param date 要格式化的日期对象。
* @param fmt 格式化模板字符串。
* @returns 格式化后的日期字符串。
* @example
* ```typescript
* const now = new Date();
* XTime.Format(now, "yyyy-MM-dd hh:mm:ss"); // "2025-01-28 14:30:00"
* XTime.Format(now, "yyyy年MM月dd日"); // "2025年01月28日"
* ```
*/
function Format(date: Date, fmt: string): string;
/**
* 获取当前时间戳（秒）。
* 返回自 1970-01-01 00:00:00 UTC 以来的秒数。
*
* @returns 当前时间戳，单位：秒。
* @example
* ```typescript
* const timestamp = XTime.GetTimestamp(); // 1706428800
* ```
*/
function GetTimestamp(): number;
/**
* 获取当前时间戳（毫秒）。
* 返回自 1970-01-01 00:00:00 UTC 以来的毫秒数。
*
* @returns 当前时间戳，单位：毫秒。
* @example
* ```typescript
* const ms = XTime.GetMilliSecond(); // 1706428800000
* ```
*/
function GetMilliSecond(): number;
}
/**
* XUtility 提供了一组通用工具集，支持 UUID 生成、可执行文件查找和随机数生成等常用操作。
*
* 功能特性
* - UUID 生成：符合 RFC4122 v4 标准的标识符生成
* - 进程执行：提供配置子进程执行环境的选项
* - 文件查找：在系统 PATH 和自定义路径中查找可执行文件
* - 随机数生成：支持生成指定范围内的随机整数
*
* 使用手册
* 1. UUID生成
*
* 1.1 基本用法
* ```typescript
* const uuid = XUtility.GenUUID(); // "550e8400-e29b-41d4-a716-446655440000"
* ```
*
* 2. 进程执行选项
*
* 2.1 基本用法
* ```typescript
* const options = XUtility.ExecOpt("./project");
* require("child_process").exec("npm install", options);
* ```
*
* 2.2 选项配置说明
* - encoding: "utf8"
* - timeout: 0（无超时限制）
* - maxBuffer: 1GB
* - killSignal: "SIGTERM"
* - cwd: 指定的工作目录
* - env: 继承自当前进程的环境变量
*
* 3. 查找可执行文件
*
* 3.1 基本用法
* ```typescript
* const gitPath = XUtility.FindBin("git", "C:/Program Files/Git/bin");
* if (gitPath) {
* console.log("Git found at:", gitPath);
* }
* ```
*
* 3.2 平台特性
* - 在Windows系统上，会自动尝试查找带`.exe`和`.bat`扩展名的文件
* - 支持在系统PATH和自定义路径中查找
*
* 4. 随机数生成
*
* 4.1 基本用法
* ```typescript
* const roll = XUtility.RandomRange(1, 6); // 生成1到6之间的随机数（骰子）
* const percent = XUtility.RandomRange(0, 100); // 生成0到100之间的随机数（百分比）
* ```
*
* 更多信息请参考模块文档。
*/
declare namespace XUtility {
/**
* 生成 UUID。
* 生成符合 RFC4122 v4 标准的 UUID。
*
* @returns 生成的 UUID 字符串。
* @example
* ```typescript
* const uuid = XUtility.GenUUID(); // "550e8400-e29b-41d4-a716-446655440000"
* ```
*/
function GenUUID(): string;
/**
* 生成进程执行选项。
* 用于配置子进程的执行环境和参数。
*
* @param cwd 工作目录路径。
* @returns 进程执行选项对象。
* @example
* ```typescript
* const options = XUtility.ExecOpt("./project");
* require("child_process").exec("npm install", options);
* ```
*/
function ExecOpt(cwd: string): any;
/**
* 查找可执行文件。
* 在系统 PATH 和指定目录中查找可执行文件。
*
* @param cmd 可执行文件名。
* @param extras 附加搜索路径列表。
* @returns 可执行文件的完整路径，如果未找到则返回 null。
* @example
* ```typescript
* const gitPath = XUtility.FindBin("git", "C:/Program Files/Git/bin");
* if (gitPath) {
* console.log("Git found at:", gitPath);
* }
* ```
*/
function FindBin(cmd: string, ...extras: string[]): string;
/**
* 生成指定范围内的随机整数。
* 包含最小值和最大值。
*
* @param min 最小值（闭区间）。
* @param max 最大值（闭区间）。
* @returns 生成的随机整数。
* @example
* ```typescript
* const roll = XUtility.RandomRange(1, 6); // 生成1到6之间的随机数
* const percent = XUtility.RandomRange(0, 100); // 生成0到100之间的随机数
* ```
*/
function RandomRange(min: number, max: number): number;
}
export { XCollect, XEnv, XEvent, XFile, XLog, XObject, XString, XTest, XTime, XUtility };