dozy 1.0.67 → 1.0.69

package/dist/index.d.ts

@@ -14,6 +14,17 @@ export { customAlphabet, nanoid, urlAlphabet } from 'nanoid';
 type DozyConfigItem = {};
 type DozyConfig = Partial<DozyConfigItem>;
 declare class Dozy {
+    /**
+     * 将用户传入的配置合并到当前运行时配置对象中。
+     *
+     * 行为说明：
+     * - 通过 `$loadOpt` 逐字段合并。
+     * - 当两边字段都是对象时，会继续执行嵌套合并。
+     * - 现有属性可能会被新值覆盖。
+     *
+     * @param config 要合并进 `this.config` 的部分配置对象。
+     * @returns 无返回值；内部 `config` 会被原地更新。
+     */
     loadConfig(config: DozyConfig): void;
     config: DozyConfig;
 }
@@ -21,6 +32,18 @@ declare const dozy: Dozy;
 
 type Any = Items<any>;
 type Null = undefined | null | void;
+/**
+ * 判断一个值在本包语义下是否属于空值。
+ *
+ * 该函数会把以下值视为空值：
+ * - `null`
+ * - `undefined`
+ * - `void 0`
+ *
+     * @typeParam T 原始候选类型。
+     * @param v 要检测的值。
+     * @returns 当 `v` 是 `null` 或 `undefined` 时返回 `true`，否则返回 `false`。
+ */
 declare function isNull<T>(v: T | Null): v is Null;
 type Nullable<T> = T | Null;
 type Items<T> = {
@@ -33,60 +56,444 @@ type Coord3 = [number, number, number];
 type IOpt = Object | undefined;
 type Atoa<T> = (i: T) => T;
 
+/**
+ * 判断一个值是否为非 `null` 的对象。
+ *
+ * @param value 要检测的值。
+ * @returns 当值是对象且不为 `null` 时返回 `true`，否则返回 `false`。
+ */
 declare function $isObject(value: unknown): value is Record<string, unknown>;
+/**
+ * 使用当前运行环境中可用的最佳方式深拷贝一个值。
+ *
+ * 行为说明：
+ * - 优先使用 `structuredClone`。
+ * - 不可用时回退到 `JSON.stringify` / `JSON.parse`。
+ * - JSON 方案会丢失函数、`undefined`、循环引用以及部分类实例信息。
+ *
+ * @typeParam T 输入与返回值的类型。
+ * @param value 源值。
+ * @returns 返回深拷贝后的结果，但具体保真度取决于底层拷贝方案。
+ */
 declare function $deepClone<T>(value: T): T;
+/**
+ * 将字符串首字母转为大写。
+ *
+ * @param s 输入字符串。
+ * @returns 如果输入为空则原样返回；否则返回首字符大写后的字符串。
+ */
 declare function $capitalize(s: string): string;
+/**
+ * 将数字限制在闭区间 `[min, max]` 内。
+ *
+ * @param n 输入数字。
+ * @param min 最小值。
+ * @param max 最大值。
+ * @returns 小于最小值时返回 `min`，大于最大值时返回 `max`，否则返回原值。
+ */
 declare function $clamp(n: number, min: number, max: number): number;
+/**
+ * 将一个对象中的配置项合并到目标对象中。
+ *
+ * 行为说明：
+ * - 如果 `obj` 不存在，则直接返回 `thiz`。
+ * - 当源字段和目标字段都是对象时，会尝试调用目标上的 `$loadOpt` 继续递归合并。
+ * - 否则直接覆盖赋值。
+ *
+ * @param thiz 目标对象，会被原地修改。
+ * @param obj 可选的源对象。
+ * @returns 返回被修改后的目标对象 `thiz`。
+ */
 declare function $loadOpt(thiz: Object, obj?: Object): any;
+/**
+ * 抛出一个带指定消息的 `Error`。
+ *
+ * @param msg 错误消息。
+ * @returns 不会返回。
+ * @throws 始终抛出 `Error`。
+ */
 declare function errMsg(msg: string): void;
+/**
+ * 去掉 HTML 标记并返回纯文本内容。
+ *
+ * @param fragment HTML 片段字符串。
+ * @returns 返回去除换行并裁剪首尾空白后的纯文本。
+ */
 declare function $pureText(fragment: string): string;
+/**
+ * 判断一个值是否为普通对象记录。
+ *
+ * @param o 要检测的值。
+ * @returns 非 `null` 对象时返回 `true`，否则返回 `false`。
+ */
 declare function $oc(o: any): o is Record<string, any>;
+/**
+ * 判断一个值是否为字符串，并可选要求其非空。
+ *
+ * @param s 要检测的值。
+ * @param val 为真时，除了要求是字符串外，还要求 `!!s` 为真。
+ * @returns 是否满足对应的字符串条件。
+ */
 declare function $s(s: any, val?: boolean): s is string;
+/**
+ * 判断一个值是否为有限数字。
+ *
+ * @param n 要检测的值。
+ * @returns 只有在值是数字且不是 `NaN`、`Infinity`、`-Infinity` 时才返回 `true`。
+ */
 declare function $sc(n: any): n is number;
+/**
+ * 对循环索引执行加减步进，并保证结果始终落在循环范围内。
+ *
+ * @param v 当前值。
+ * @param t 循环长度，也可理解为上边界（不包含）。
+ * @param plus 步进值，默认为 `1`。
+ * @returns 返回落在 `[0, t)` 区间内的循环结果。
+ */
 declare function $lplus(v: number, t: number, plus?: number): number;
+/**
+ * 使用循环索引方式读取数组项。
+ *
+ * @param arr 源数组。
+ * @param i 目标索引，可以是负数，也可以超过数组长度。
+ * @returns 返回折算后的数组项；如果数组为空则返回 `undefined`。
+ */
 declare function $lindex(arr: Array<any>, i: number): any;
+/**
+ * 校验一个简单标识符是否合法。
+ *
+ * 允许字符：字母、数字、连字符 `-`、下划线 `_`。
+ *
+ * @param id 待校验的标识符。
+ * @returns 当 `id` 非空且符合规则时返回 `true`，否则返回 `false`。
+ */
 declare function $validName(id?: string): id is string;
 type FileType = 'text' | 'image' | 'audio' | 'video' | 'font' | 'unknown';
+/**
+ * 根据文件扩展名推断文件的大致类型。
+ *
+ * @param fileName 文件名或路径。
+ * @returns 可能返回 `text`、`image`、`audio`、`video`、`font` 或 `unknown`。
+ */
 declare function $getFileType(fileName: string): FileType;
+/**
+ * 判断一个字符串是否看起来像 URL，允许省略协议头。
+ *
+ * @param url 待检测的 URL 字符串。
+ * @returns 输入为空时返回 `false`；否则返回是否匹配内部 URL 规则。
+ */
 declare function $isValidOrBriefURL(url?: string): boolean;
+/**
+ * 将 tick 时间格式化为可读字符串。
+ *
+ * @param stampTicks 时间值，默认规则下 40 tick = 1 秒。
+ * @param short 为 `true` 时返回 `MM:SS`，否则返回 `HH:MM:SS`。
+ * @param unitS 为 `true` 时表示传入值单位是秒，函数内部会自动换算成 tick。
+ * @param exact 为 `true` 时会在末尾追加 `%xx`，表示更细的余数信息。
+ * @returns 返回格式化后的时间字符串；若输入不是有效数字，则按 `short` 返回 `00:00` 或 `00:00:00`。
+ */
 declare function $getTimeString(stampTicks: number, short: boolean, unitS?: boolean, exact?: boolean): string;
+/**
+ * 在指定范围内生成随机整数。
+ *
+ * 参数语义：
+ * - 只传 `start` 时，返回 `[0, start)` 范围内的整数。
+ * - 同时传 `start`、`end` 时，返回 `[start, end)` 范围内的整数。
+ *
+ * @param start 当 `end` 省略时表示上限；否则表示下限。
+ * @param end 可选的上限（不包含）。
+ * @returns 返回目标范围内的随机整数；当范围无效时返回 `0`。
+ */
 declare function $magic(start: number, end?: number): number;
+/**
+ * 生成指定长度的伪随机字母数字字符串。
+ *
+ * @param len 目标长度，小于 `1` 时会被强制改为 `1`。
+ * @returns 返回长度恰好为 `len` 的随机字符串。
+ */
 declare function $randomByte(len?: number): string;
+/**
+ * 解析 JSON 字符串，并读取其中某个点路径对应的值。
+ *
+ * @param s JSON 字符串。
+ * @param path 可选的点分隔路径，如 `a.b.c`。
+ * @param def 当输入为空或路径读取失败时使用的默认值。
+ * @returns 返回读取到的值；如果失败则返回 `def`。
+ */
 declare function $rsValue(s?: string, path?: string, def?: any): any;
+/**
+ * 按点路径给对象设置嵌套值。
+ *
+ * @param obj 目标对象。
+ * @param path 点分隔属性路径。
+ * @param value 要设置的值。
+ * @returns 返回最终写入的值。
+ */
 declare function $rsetValue(obj: Object, path: string, value: any): any;
+/**
+ * 使用点路径读取或设置对象中的嵌套属性。
+ *
+ * @param obj 目标对象。
+ * @param path 可选的点分隔路径；如果不传，则直接返回 `obj` 本身。
+ * @param def 默认值；在设置模式下也会作为要写入的值。
+ * @param sdef 为 `true` 时，缺失的中间对象或最终值可以按需用 `def` 创建。
+ * @param set 为 `true` 时强制进入设置模式，并把 `def` 写入最终路径。
+ * @returns 可能返回读取到的值、写入的值、默认值 `def`，或者原对象 `obj`，具体取决于路径情况与参数组合。
+ */
 declare function $rvalue(obj: Object, path?: string, def?: any, sdef?: boolean, set?: boolean): any;
+/**
+ * 判断对象是否直接拥有某个属性。
+ *
+ * @param obj 要检查的对象。
+ * @param key 属性名。
+ * @returns 只有当属性是对象自身属性时才返回 `true`。
+ */
 declare function $hasKey(obj: Object, key: string): boolean;
+/**
+ * `_maybeString` 的对外包装函数。
+ *
+ * @param a 要转成字符串的值。
+ * @param maxLength 最大输出长度，默认为 `600`。
+ * @returns 返回相对安全的字符串表示。
+ */
 declare function maybeString(a: any, maxLength?: number): string;
+/**
+ * 将未知错误尽量转换为可读的错误消息。
+ *
+ * @param e 未知的错误值。
+ * @returns 返回尽可能提取出的错误消息；若是 Axios 错误且响应中存在 `data.msg`，会优先使用它。
+ */
 declare function errToString(e: unknown): string;
+/**
+ * 以一个固定的小概率返回 `true`。
+ *
+ * @returns 当 `Math.random() > 0.8` 时返回 `true`，否则返回 `false`。
+ */
 declare function smallChance(): boolean;
+/**
+ * 判断一个值是否是指定构造函数的普通实例。
+ *
+ * @param obj 要检测的值。
+ * @param clas 期望的构造函数，默认为 `Object`。
+ * @returns 当 `obj` 非空且其 `constructor === clas` 时返回 `true`。
+ */
 declare function $isPlainClass(obj: any, clas?: Function): boolean;
+/**
+ * 将 Unicode 字符串编码为 Base64。
+ *
+ * @param str 源字符串。
+ * @returns 返回 Base64 字符串。
+ */
 declare function $encodeUnicodeToBase64(str: string): string;
+/**
+ * 将 Base64 字符串解码回 Unicode 文本。
+ *
+ * @param base64 Base64 编码字符串。
+ * @returns 返回解码后的 Unicode 字符串。
+ */
 declare function $decodeBase64ToUnicode(base64: string): string;
+/**
+ * 读取浏览器 `File`，并返回不带 data URL 前缀的纯 Base64 内容。
+ *
+ * @param file 要读取的文件对象。
+ * @returns 返回一个 Promise，成功时得到纯 Base64 字符串。
+ * @throws 当文件读取失败或结果不是字符串时，Promise 会被拒绝。
+ */
 declare function $fileToBase64(file: File): Promise<string>;
+/**
+ * 将 Base64 字符串解码为原始字节数组。
+ *
+ * @param base64 纯 Base64 字符串。
+ * @returns 返回解码后的 `Uint8Array`。
+ */
 declare function $decodeBase64ToBinary(base64: string): Uint8Array<ArrayBuffer>;
+/**
+ * 仅在边界值有效时，将数字限制到对应范围内。
+ *
+ * @param v 输入值。
+ * @param min 可选最小值。
+ * @param max 可选最大值。
+ * @returns 返回处理后的结果值。
+ */
 declare function $setRange(v: number, min?: number, max?: number): number;
+/**
+ * 判断一个值是否位于某个中心点的对称范围内。
+ *
+ * @param v 要检测的值。
+ * @param mid 中心值。
+ * @param range 左右两侧允许的偏移范围。
+ * @returns 当 `v` 位于 `[mid - range, mid + range]` 区间内时返回 `true`。
+ */
 declare function $inRange2(v: number, mid: number, range: number): boolean;
+/**
+ * 判断一个数是否位于可选的最小值和最大值之间。
+ *
+ * @param v 要检测的值。
+ * @param min 可选最小值。
+ * @param max 可选最大值。
+ * @returns 如果违反任一已提供边界则返回 `false`，否则返回 `true`。
+ */
 declare function $inRange(v: number, min?: number, max?: number): boolean;
+/**
+ * 按指定分隔符拆分字符串。
+ *
+ * @param str 原始字符串。
+ * @param cut 分隔符，默认为 `^`。
+ * @returns 返回 `str.split(cut)` 的结果数组。
+ */
 declare function $strings(str: string, cut?: string): string[];
+/**
+ * 生成一个按成对字符串参数进行处理的辅助函数。
+ *
+ * 规则说明：
+ * - 如果只传了一个参数且其中包含 `^`，会先按 `^` 拆分。
+ * - 然后按 `(s1, s2)` 两两配对执行处理。
+ * - 如果某组缺少第二项，运行时该参数会是 `undefined`。
+ *
+ * @param f 成对处理函数。
+ * @param gap 每组结果之间插入的分隔字符串。
+ * @returns 返回一个新函数，用于把字符串列表合成为最终字符串。
+ */
 declare function $genSSF(f: (s1: string, s2: string) => string, gap?: string): (...args: string[]) => string;
+/**
+ * 规范化多行字符串中的空白字符。
+ *
+ * @param s 输入字符串。
+ * @returns 返回压缩多余空行、规范行内空白并去除首尾空白后的字符串。
+ */
 declare function xtrim(s: string): string;
+/**
+ * 根据键值选择映射项，并在映射值为函数时执行它。
+ *
+ * @typeParam T 键类型。
+ * @typeParam V 非函数映射值类型。
+ * @param val 当前要选择的键。
+ * @param fs 键到函数或普通值的映射表。
+ * @returns 如果命中项是函数则返回函数执行结果，否则返回映射值本身。
+ */
 declare function $if<T extends string | number | symbol, V>(val: T, fs: Record<T, Function | V>): any;
+/**
+ * 获取数组或长度值对应的最后一个有效索引。
+ *
+ * @param items 数组本身或数字长度。
+ * @returns 返回 `max(length - 1, 0)` 的结果。
+ */
 declare function $lastIndex(items: Array<any> | number): number;
+/**
+ * 将稀疏数组中的空洞补成显式的 `undefined`。
+ *
+ * 注意：该函数会修改原数组，同时返回一个浅拷贝。
+ *
+ * @typeParam T 元素类型。
+ * @param arr 可能包含空洞的数组。
+ * @returns 返回浅拷贝后的数组。
+ */
 declare function $replaceHolesWithUndefined<T>(arr: Array<T | undefined>): Array<T | undefined>;
+/**
+ * 将字符串稳定映射到 `[0, max)` 范围内的整数。
+ *
+ * @param str 源字符串。
+ * @param max 上界（不包含）。
+ * @returns 返回确定性的整数结果；即使字符串为空，也会得到合法范围内的值。
+ */
 declare function $stringToRange(str: string, max: number): number;
+/**
+ * 去掉路径开头的 `/`。
+ *
+ * @param path 输入路径。
+ * @returns 如果路径有前导斜杠则返回去掉后的结果，否则原样返回。
+ */
 declare function $rmvSlash(path: string): string;
+/**
+ * 解析紧凑编码的路径参数字符串。
+ *
+ * 规则：
+ * - 单个 `-` 表示参数分隔。
+ * - 双 `--` 表示字面量 `-`。
+ * - `_` 与 `%20` 会被还原为空格。
+ * - 双下划线 `__` 用于保留字面量下划线。
+ *
+ * @param path 编码后的路径字符串。
+ * @returns 返回解码后的参数数组。
+ */
 declare function $parseParams(path: string): (string | undefined)[];
+/**
+ * 给数字或数字字符串添加千分位分隔符。
+ *
+ * @param num 数字或可转为字符串的数字值。
+ * @returns 返回带千分位逗号的字符串。
+ */
 declare function $formatWithCommas(num: number | string): string;
+/**
+ * 校验邮箱地址是否符合支持 Unicode 字母的规则。
+ *
+ * @param email 待校验邮箱。
+ * @returns 符合规则时返回 `true`，否则返回 `false`。
+ */
 declare function $isValidEmailWithUnicode(email?: string): boolean;
+/**
+ * 校验邮箱格式，不合法时直接抛错。
+ *
+ * @param email 待校验邮箱。
+ * @returns 合法时无返回值。
+ * @throws 当邮箱不合法时抛出错误。
+ */
 declare function $checkValidEmailWithUnicode(email?: string): void;
+declare const shanghaiDateFormatter: Intl.DateTimeFormat;
+/**
+ * 将日期输入格式化为 `YYYY年M月D日 HH:mm`。
+ *
+ * @param dateInput 任何可被 `Date` 构造函数接受的输入。
+ * @returns 返回格式化后的日期字符串。
+ */
 declare function $formatDate(dateInput: string | number | Date): string;
+/**
+ * 将错误转换成一个始终包含 `msg` 字段的对象。
+ *
+ * @typeParam T 附加字段对象类型。
+ * @param error 错误来源。
+ * @param defVal 可选的附加字段对象。
+ * @returns 返回 `{ msg }` 或 `{ msg, ...defVal }`。
+ */
 declare function errCode<T extends Any>(error: any, defVal?: T): {
     msg: string;
 };
+/**
+ * 抛出统一的“内容不正确”错误。
+ *
+ * @returns 不会返回。
+ * @throws 始终抛出错误。
+ */
 declare function errContent(): void;
+/**
+ * 抛出统一的“参数不正确”错误。
+ *
+ * @returns 不会返回。
+ * @throws 始终抛出错误。
+ */
 declare function errArg(): void;
+/**
+ * 抛出统一的“未登录”错误。
+ *
+ * @returns 不会返回。
+ * @throws 始终抛出错误。
+ */
 declare function errNotLoggedIn(): void;
+/**
+ * 抛出统一的“没有权限”错误。
+ *
+ * @returns 不会返回。
+ * @throws 始终抛出错误。
+ */
 declare function err403(): void;
+/**
+ * 判断当前 UTC 时间是否接近指定的 UTC 整点。
+ *
+ * 当前实现允许前后约 3 分钟误差，并处理跨天情况。
+ *
+ * @param targetHour 目标 UTC 小时，通常应在 `0-23` 范围内。
+ * @returns 如果当前 UTC 时间与目标小时足够接近，则返回 `true`。
+ */
 declare function isNowAroundUtcHour(targetHour: number): boolean;
 /**
  * 清洗 base64 输入，统一得到“纯 base64”（不含 data URL 前缀）。
@@ -129,7 +536,23 @@ declare const $getHue: (json: Object) => number;
 declare const $borderColor: (json: any) => string;
 declare const $backgroundColor: (json: any) => string;
 
+/**
+ * 将当前历史记录替换为规范化后的路径。
+ *
+ * @param s 目标路径；如果没有以 `/` 开头会自动补上。
+ * @returns 无返回值。
+ */
 declare function web$setPathTarget(s: string): void;
+/**
+ * 读取并规范化当前浏览器地址信息。
+ *
+ * 行为说明：
+ * - 会识别 `#/...` 这种 hash 路由跳转，并把地址改写成规范路径。
+ * - 会去掉 `path` 前导 `/` 以及结尾的 `.html` / `.htm`。
+ * - 会去掉 `search` 前面的 `?`。
+ *
+ * @returns 返回一个描述当前地址状态的对象，包含 `href`、`origin`、`target`、`host`、`path`、`search`、`standardJump` 等字段。
+ */
 declare function web$pathStartData(): {
     href: string;
     origin: string;
@@ -139,13 +562,74 @@ declare function web$pathStartData(): {
     search: string;
     standardJump: boolean;
 };
+/**
+ * 在浏览器中开启轻量级的生产环境防调试保护。
+ *
+ * 副作用包括：
+ * - 禁用右键菜单。
+ * - 阻止 `F12` 和 `Ctrl+Shift+I`。
+ * - 周期性检测开发者工具是否可能被打开，若触发则跳转离开当前页。
+ *
+ * @returns 无返回值；在服务端环境下不会执行任何逻辑。
+ */
 declare function web$enableProdProtector(): void;
+/**
+ * 在浏览器环境下把 `http:` 页面自动重定向到 `https:`。
+ *
+ * 例外情况：
+ * - `localhost`
+ * - `127.0.0.1`
+ *
+ * @returns 无返回值。
+ */
 declare function web$enableHttpsRedirect(): void;
+/**
+ * 将当前页面重定向到另一个域名，同时保留路径、查询参数和哈希。
+ *
+ * @param newDomain 目标域名，可以带或不带结尾斜杠。
+ * @returns 无返回值；在服务端环境下直接返回。
+ */
 declare function web$redirectToDomain(newDomain: string): void;
+/**
+ * 将文本复制到系统剪贴板。
+ *
+ * 行为说明：
+ * - 会先对传入内容执行 `trim()`。
+ * - 优先使用 `navigator.clipboard.writeText`。
+ * - 现代剪贴板接口失败时会回退到 `$fallbackCopy`。
+ * - 非浏览器环境下返回 `undefined`。
+ *
+ * @param content 要复制的文本内容。
+ * @returns 成功时返回 `true`，回退复制失败时返回 `false`，非浏览器环境下返回 `undefined`。
+ */
 declare function $copy(content: string): Promise<boolean | undefined>;
+/**
+ * 使用隐藏的 `<textarea>` 作为兼容方案执行复制。
+ *
+ * @param content 要复制的文本，会先被 `trim()` 处理。
+ * @returns 当 `document.execCommand('copy')` 返回成功时为 `true`，否则为 `false`。
+ */
 declare function $fallbackCopy(content: string): boolean;
+/**
+ * 将当前页面的路径、查询参数和哈希编码成一个 URI 片段字符串。
+ *
+ * @param hash 可选的替代 hash；如果传入时没有 `#` 前缀会自动补上。
+ * @returns 编码后的 URI 组件字符串。
+ * @throws 在非浏览器环境中会抛出空字符串。
+ */
 declare function web$encodeURI(hash?: string): string;
 declare const $compressImageDefaultOptions: Options;
+/**
+ * 压缩 Base64 图片并以 data URL 形式返回。
+ *
+ * 说明：
+ * - 同时支持纯 Base64 和已有 data URL 两种输入。
+ * - 如果输入无法被规范化为合法 data URL，则返回空字符串。
+ *
+ * @param base64 输入的图片数据。
+ * @param options 可选压缩配置，会覆盖默认配置。
+ * @returns 返回压缩后的 data URL；如果输入无效则返回空字符串。
+ */
 declare function $compressImageBase64(base64: string, options?: Options): Promise<string>;
 declare function $compressImage(file: File, options?: Options): Promise<File>;
 declare function $compressImage(files: File[], options?: Options): Promise<File[]>;
@@ -230,6 +714,16 @@ declare const $Response: {
     json(data: any, init?: ResponseInit): Response;
     redirect(url: string | URL, status?: number): Response;
 } | undefined;
+/**
+ * 输出一个值到控制台，并原样返回该值。
+ *
+ * 适合在表达式链中做内联调试。
+ *
+ * @typeParam T 第一个参数的类型。
+ * @param a 主要输出值，同时也是返回值。
+ * @param x 其余会继续传给 `console.log` 的附加参数。
+ * @returns 原样返回传入的 `a`。
+ */
 declare const $log: <T>(a?: T, ...x: any[]) => T | undefined;
 declare const $crypto: Crypto | undefined;
 
@@ -248,19 +742,50 @@ declare class Scaler {
     set scaleComputer(val: ScaleComputer);
     onMainScaleChange?: (scale: number) => void;
     innerContainer: HTMLElement;
+    /**
+     * 创建内部缩放器状态对象。
+     *
+     * @param innerContainer 需要接收宽度与 transform 更新的内部元素。
+     */
     constructor(innerContainer: HTMLElement);
 }
+/**
+ * 为固定宽度的内部容器启用响应式缩放行为。
+ *
+ * 典型结构：
+ * - `outerContainer` 作为高度占位容器。
+ * - 第一个子元素或显式传入的 `innerContainer` 会通过 CSS transform 进行视觉缩放。
+ *
+ * 运行时行为：
+ * - 在非浏览器环境下会直接返回 `undefined`。
+ * - 如果无法解析出有效的内部容器，会直接抛错。
+ * - 会挂载 `resize` 和 `ResizeObserver` 监听。
+ *
+ * @param outerContainer 外层包裹元素。
+ * @param initer 可选初始化器，用于配置内部 `Scaler` 实例。
+ * @param innerContainer 可选的内部缩放元素，默认取 `outerContainer.children[0]`。
+ * @returns 在浏览器环境下返回包含 `resizer`、`clean`、`setBase` 方法的对象；否则返回 `undefined`。
+ */
 declare function enableScaler(outerContainer: HTMLElement, initer?: ScaleIniter, innerContainer?: HTMLElement): {
     resizer: () => void;
     clean: () => void;
     setBase: (val: number) => void;
 } | undefined;
 /**
- * Hello
- * @param widthElement 容器
- * @param heightElement 容器
- * @param maxAspectRatio 请输入 Number(0.57) && 0.64
- * @returns
+ * 构建一个适用于常见视口布局的标准缩放初始化器。
+ *
+ * 返回的初始化器会配置宽高测量元素，并根据可用宽度与可选的最大宽高比计算缩放比例。
+ *
+ * @param args 初始化配置项。
+ * @param args.maxAspectRatio 计算可用宽度时允许的最大 `width / height` 比例，默认 `Infinity`。
+ * @param args.setFullScreenWidth 可选回调，用于接收计算后的可用宽度。
+ * @param args.setFullContentHeight 可选回调，用于接收缩放后的虚拟内容高度。
+ * @param args.setMainScale 可选回调，在主缩放值变化时触发。
+ * @param args.offsetHorizontal 可选的水平补偿值。
+ * @param args.heightElement 可选高度测量元素，默认使用 `document.documentElement`。
+ * @param args.widthElement 可选宽度测量元素，默认使用 `document.documentElement`。
+ * @param args.base 可选基础内容宽度。
+ * @returns 返回一个可供 `enableScaler` 使用的 `ScaleIniter` 函数。
  */
 declare const standardIniter: (args: {
     maxAspectRatio?: number;
@@ -276,9 +801,45 @@ declare const standardIniter: (args: {
 declare class StringObfuscator {
     key: string;
     length: number;
+    /**
+     * 创建一个基于 XOR + Base64 的字符串混淆器。
+     *
+     * @param key 用于逐字符 XOR 的密钥。
+     * @param length 可选的固定输出长度；传 `-1` 表示关闭固定长度模式。
+     */
     constructor(key: string, length?: number);
+    /**
+     * 用给定密钥对字符串的每个字符执行 XOR，必要时循环使用密钥。
+     *
+     * @param str 需要转换的源文本。
+     * @param key 循环参与 XOR 的密钥。
+     * @returns 返回 XOR 处理后的字符串；结果更像二进制文本，不保证可直接阅读。
+     */
     xors(str: string, key: string): string;
+    /**
+     * 将明文混淆成一个适合放在 URL 中的 Base64 风格字符串。
+     *
+     * 行为说明：
+     * - 固定长度模式下，输入会先用空格补齐再进行 XOR。
+     * - 结果会移除 `=` 补位，并把 `/` 替换为 `-`、`+` 替换为 `_`。
+     * - 固定长度模式下，Base64 输出还会被截断到配置长度。
+     *
+     * @param input 要混淆的明文。
+     * @returns 返回适合常见 URL/路径场景使用的混淆字符串。
+     */
     en(input: string): string;
+    /**
+     * 从混淆字符串中恢复原始明文。
+     *
+     * 说明：
+     * - 会先把 URL 安全替换恢复后再做 Base64 解码。
+     * - 反混淆后会去掉尾部空格，这对固定长度模式很重要。
+     * - 如果输入格式不正确，底层解码步骤可能会抛错。
+     *
+     * @param obfuscated 由 `en` 生成的混淆字符串。
+     * @returns 返回解码后的原文，尾部补位空格会被移除。
+     * @throws 输入无效时会继续向外抛出底层解码错误。
+     */
     de(obfuscated: string): string;
 }
 
@@ -305,77 +866,75 @@ declare let _res: (x: string) => string;
 declare function __GensDirectives(): Items<(...args: string[]) => string>;
 
 /**
- * Register a custom color alias.
- * @param name The name of the alias (e.g., 'abc', 'myColor')
- * @param color The valid color string it maps to (e.g., '#ff0000', 'red')
+ * 注册一个自定义颜色别名。
+ * @param name 别名名称，例如 `abc`、`myColor`。
+ * @param color 别名实际映射到的合法颜色字符串，例如 `#ff0000`、`red`。
  */
 declare function registerCustomColor(name: string, color: string): void;
 /**
- * Smartly parses a color string.
- * Supports:
- * - All standard CSS colors (names, hex, rgb, hsl, oklch, etc.) via culori.
- * - Hex strings without '#' (e.g., 'ff5555', 'abc', 'aabbccdd').
- * - Custom aliases registered via registerCustomColor.
- * - Existing Color objects (passed through).
+ * 智能解析颜色字符串。
+ * 支持：
+ * - 通过 culori 解析所有标准 CSS 颜色（名称、hex、rgb、hsl、oklch 等）。
+ * - 不带 `#` 的十六进制字符串（如 `ff5555`、`abc`、`aabbccdd`）。
+ * - 通过 `registerCustomColor` 注册的自定义别名。
+ * - 已经是 `Color` 对象的输入（直接透传）。
  *
- * @param input The color string or Color object to parse.
- * @param fallback Optional fallback color string if parsing fails.
- * @returns The parsed Color object or undefined if invalid.
+ * @param input 要解析的颜色字符串或 `Color` 对象。
+ * @param fallback 解析失败时可选的兜底颜色字符串。
+ * @returns 解析成功时返回 `Color` 对象，失败时返回 `undefined`。
  */
 declare function smartParse(input: string | Color | any, fallback?: string): Color | undefined;
 /**
- * Smartly parses a color and returns a CSS string.
- * Defaults to Hex for sRGB colors, or CSS function for others (like oklch).
- * @param input The color string or object.
+ * 智能解析颜色并返回对应的 CSS 字符串。
+ * 对 sRGB 颜色通常会输出 Hex，其它颜色空间可能输出 CSS 函数形式（如 oklch）。
+ * @param input 颜色字符串或颜色对象。
  */
 declare function smartString(input: string | Color | any, fallback?: string): string | undefined;
 /**
- * Check if a color string is valid (smartly).
- * @param input The color string or object.
+ * 智能判断一个颜色输入是否有效。
+ * @param input 颜色字符串或颜色对象。
  */
 declare function isValidColor(input: string | Color | any): boolean;
 /**
- * Calculates the brightness of a color.
- * Uses the Rec. 601 luma formula: (R * 299 + G * 587 + B * 114) / 1000.
- * Returns a value between 0 (black) and 1 (white).
+ * 计算颜色的亮度。
+ * 使用 Rec. 601 亮度公式：`(R * 299 + G * 587 + B * 114) / 1000`。
+ * 返回值范围通常在 0（黑）到 1（白）之间。
  *
- * @param input The color string or object to check.
- * @returns The brightness value (0-1), or 0 if invalid.
+ * @param input 要检测的颜色字符串或对象。
+ * @returns 返回亮度值（0-1）；如果颜色无效则返回 `0`。
  */
 declare function getBrightness(input: string | Color | any): number;
 /**
- * Converts a color to an RGBA array [r, g, b, a].
- * RGB values are 0-255, Alpha is 0-1.
+ * 将颜色转换为 RGBA 数组 `[r, g, b, a]`。
+ * 其中 RGB 范围是 0-255，Alpha 范围是 0-1。
  *
- * @param input The color string or object to convert.
- * @returns [r, g, b, a] or undefined if invalid.
+ * @param input 要转换的颜色字符串或对象。
+ * @returns 转换成功时返回 `[r, g, b, a]`，无效时返回 `undefined`。
  */
 declare function toRgbaArray(input: string | Color | any): [number, number, number, number] | undefined;
 /**
- * Converts a color to a Hex string.
- * @param input The color string or object.
- * @returns Hex string (e.g. #ff0000) or undefined.
+ * 将颜色转换为 Hex 字符串。
+ * @param input 颜色字符串或颜色对象。
+ * @returns 成功时返回如 `#ff0000` 这样的字符串，失败时返回 `undefined`。
  */
 declare function toHexString(input: string | Color | any): string | undefined;
 /**
- * Converts a color to an RGB/RGBA string.
- * Uses modern comma-separated syntax for compatibility if preferred, or standard CSS.
- * Note: culori's formatRgb might use space-separated syntax (CSS Color 4).
- * This function forces comma-separated legacy syntax: rgb(r, g, b) or rgba(r, g, b, a).
+ * 将颜色转换为 RGB/RGBA 字符串。
+ * 为兼容性考虑，这里强制输出旧式逗号分隔语法：`rgb(r, g, b)` 或 `rgba(r, g, b, a)`。
  *
- * @param input The color string or object.
- * @returns RGB/RGBA string or undefined.
+ * @param input 颜色字符串或颜色对象。
+ * @returns 成功时返回 RGB/RGBA 字符串，失败时返回 `undefined`。
  */
 declare function toRgbString(input: string | Color | any): string | undefined;
 /**
- * Converts a color to an HSL/HSLA string.
- * Forces legacy comma-separated syntax: hsl(h, s%, l%) or hsla(h, s%, l%, a).
+ * 将颜色转换为 HSL/HSLA 字符串。
+ * 这里强制输出旧式逗号分隔语法：`hsl(h, s%, l%)` 或 `hsla(h, s%, l%, a)`。
  *
- * @param input The color string or object.
- * @returns HSL/HSLA string or undefined.
+ * @param input 颜色字符串或颜色对象。
+ * @returns 成功时返回 HSL/HSLA 字符串，失败时返回 `undefined`。
  */
 declare function toHslString(input: string | Color | any): string | undefined;
 
-declare const DOZY = "1.0.67";
+declare const DOZY = "1.0.69";
 
-export { $Headers, $Request, $Response, $URL, $URLSearchParams, $arrayFrom, $arrayIsArray, $assign, $backgroundColor, $borderColor, $capitalize, $checkValidEmailWithUnicode, $clamp, $clearInterval, $clearTimeout, $clone, $compressImage, $compressImageBase64, $compressImageDefaultOptions, $copy, $crypto, $date, $decodeBase64ToBinary, $decodeBase64ToUnicode, $deepClone, $defineProperty, $document, $encodeUnicodeToBase64, $entries, $escapeHTML, $fallbackCopy, $fetch, $fileToBase64, $formatDate, $formatWithCommas, $freeze, $genSSF, $getFileType, $getHue, $getTimeString, $hasKey, $if, $inRange, $inRange2, $inferMimeTypeFormPureBase64, $is, $isObject, $isPlainClass, $isValidEmailWithUnicode, $isValidOrBriefURL, $jsonParse, $jsonStringify, $keys, $lastIndex, $lindex, $loadOpt, $location, $log, $lplus, $magic, $math, $now, $numberIsFinite, $numberIsNaN, $oc, $open, $parseParams, $promise, $pureText, $purifyBase64, $randomByte, $replaceHolesWithUndefined, $rmvSlash, $rsValue, $rsetValue, $rvalue, $s, $sc, $setInterval, $setRange, $setTimeout, $stringFromCharCode, $stringFromCodePoint, $stringToRange, $strings, $toDataUrlFromBase64, $validName, $values, $window, type Any, type Atoa, type Coord, type Coord3, DOZY, type DozyConfig, type DozyConfigItem, type FileType, Gens, type Hel, type IOpt, type Items, type Null, type Nullable, RainbowGen, type ScaleComputer, type ScaleIniter, StringObfuscator, type UNumber, __GensDirectives, _res, boxShadow, dozy, enableScaler, err403, errArg, errCode, errContent, errMsg, errNotLoggedIn, errToString, getBrightness, getColorMap, isNowAroundUtcHour, isNull, isValidColor, maybeString, registerCustomColor, s, smallChance, smartParse, smartString, standardIniter, textShadow, toHexString, toHslString, toRgbString, toRgbaArray, web$enableHttpsRedirect, web$enableProdProtector, web$encodeURI, web$pathStartData, web$redirectToDomain, web$setPathTarget, xtrim };
+export { $Headers, $Request, $Response, $URL, $URLSearchParams, $arrayFrom, $arrayIsArray, $assign, $backgroundColor, $borderColor, $capitalize, $checkValidEmailWithUnicode, $clamp, $clearInterval, $clearTimeout, $clone, $compressImage, $compressImageBase64, $compressImageDefaultOptions, $copy, $crypto, $date, $decodeBase64ToBinary, $decodeBase64ToUnicode, $deepClone, $defineProperty, $document, $encodeUnicodeToBase64, $entries, $escapeHTML, $fallbackCopy, $fetch, $fileToBase64, $formatDate, $formatWithCommas, $freeze, $genSSF, $getFileType, $getHue, $getTimeString, $hasKey, $if, $inRange, $inRange2, $inferMimeTypeFormPureBase64, $is, $isObject, $isPlainClass, $isValidEmailWithUnicode, $isValidOrBriefURL, $jsonParse, $jsonStringify, $keys, $lastIndex, $lindex, $loadOpt, $location, $log, $lplus, $magic, $math, $now, $numberIsFinite, $numberIsNaN, $oc, $open, $parseParams, $promise, $pureText, $purifyBase64, $randomByte, $replaceHolesWithUndefined, $rmvSlash, $rsValue, $rsetValue, $rvalue, $s, $sc, $setInterval, $setRange, $setTimeout, $stringFromCharCode, $stringFromCodePoint, $stringToRange, $strings, $toDataUrlFromBase64, $validName, $values, $window, type Any, type Atoa, type Coord, type Coord3, DOZY, type DozyConfig, type DozyConfigItem, type FileType, Gens, type Hel, type IOpt, type Items, type Null, type Nullable, RainbowGen, type ScaleComputer, type ScaleIniter, StringObfuscator, type UNumber, __GensDirectives, _res, boxShadow, dozy, enableScaler, err403, errArg, errCode, errContent, errMsg, errNotLoggedIn, errToString, getBrightness, getColorMap, isNowAroundUtcHour, isNull, isValidColor, maybeString, registerCustomColor, s, shanghaiDateFormatter, smallChance, smartParse, smartString, standardIniter, textShadow, toHexString, toHslString, toRgbString, toRgbaArray, web$enableHttpsRedirect, web$enableProdProtector, web$encodeURI, web$pathStartData, web$redirectToDomain, web$setPathTarget, xtrim };