工具¶

UI-PROTOTYPE 提供了一些常用的工具，所有工具均位于 src/shared/utils 中。

API¶

dom¶

提供更简便的 DOM 操作方法。

类：`Dom`¶

一个类似 JQ 的 DOM 操作类。

class Dom<T extends HTMLElement = HTMLElement> {
  constructor(...args: (string | T | Dom<T>)[]);
}

接受任意数量的参数，每个参数可以是字符串、DOM 元素或 Dom 实例。
string 类型的参数将作为函数 document.querySelectorAll 的参数，查询结果将存入 Dom 实例中。
可简写为 $()。

静态函数：`pug`¶

function pug<T extends HTMLElement = HTMLElement>(
  pug: string,
  options?: any
): Dom<T>;

使用 pug 模板引擎编译 pug 字符串，并返回一个 Dom 实例。

静态函数：`html`¶

function html<T extends HTMLElement = HTMLElement>(html: string): Dom<T>;

将 HTML 字符串转换为 Dom 实例。

静态函数：`layout`¶

function layout<T extends HTMLElement = HTMLElement>(
  name: string,
  options?: any,
  shared: boolean = false
): Dom<T>;

使用 pug 模板引擎编译 pug 模板文件，并返回一个 Dom 实例。

静态函数：`from`¶

function from<T extends HTMLElement = HTMLElement>(
  ...args: (string | T | Dom<T>)[]
): Dom<T>;

将任意数量的参数转换为 Dom 实例。
string 类型的参数将作为 HTML 字符串创建为 HTMLElement 元素。

静态函数：`new`¶

function new<K extends keyof DOMTagNameMap>(
  tagName: K,
  pack?: false
): DOMTagNameMap[K];
function new<K extends keyof DOMTagNameMap>(
  tagName: K,
  pack: true
): Dom<DOMTagNameMap[K]>;
function new<K extends keyof DOMTagNameMap>(
  tagName: K,
  pack: boolean = false
): DOMTagNameMap[K] | Dom<DOMTagNameMap[K]>;

创建一个 DOM 元素。
pack 参数决定是否包装为 Dom 实例，默认 false。

方法：`filter`¶

function filter(callback: (value: T, index: number, array: T[]) => boolean): Dom<T>;

使用回调函数过滤出新的 DOM 实例。

方法：`query`¶

function query<T extends HTMLElement = HTMLElement>(selector: string): Dom<T>;

使用 CSS 选择器在当前 Dom 实例中的所有元素查询 DOM 元素，并返回新的 Dom 实例。

方法：`map`¶

function map(callback: (value: T, index: number, array: T[]) => T): Dom<T>;

使用回调函数遍历当前 Dom 实例中的所有元素，并返回新的 Dom 实例。

方法：`clone`¶

function clone(deep?: boolean): Dom<T>;

克隆当前 Dom 实例中的所有元素，并返回新的 Dom 实例。 deep 参数决定是否深度克隆，默认 false。

方法：`at`¶

function at(i: number): T;

返回当前 Dom 实例中的第 i 个元素。

方法：`forEach`¶

function forEach(callback: (value: T, index: number, array: T[]) => void): void;

使用回调函数遍历当前 Dom 实例中的所有元素。

方法：`every`¶

function every(callback: (value: T, index: number, array: T[]) => boolean): boolean;

使用回调函数判断当前 Dom 实例中的所有元素是否都符合条件。

方法：`any`¶

function any(callback: (value: T, index: number, array: T[]) => boolean): boolean;

使用回调函数判断当前 Dom 实例中的所有元素是否至少有一个符合条件。

方法：`before`¶

function before(...args: (Dom | HTMLElement | string)[]): void;

在当前 Dom 实例中的所有元素之前插入新的元素。

方法：`prepend`¶

function prepend(...args: (Dom | HTMLElement | string)[]): void;

在当前 Dom 实例中的所有元素的第一个子节点之前插入新的元素。

方法：`append`¶

function append(...args: (Dom | HTMLElement | string)[]): void;

在当前 Dom 实例中的所有元素的最后一个子节点之后插入新的元素。

方法：`after`¶

function after(...args: (Dom | HTMLElement | string)[]): void;

在当前 Dom 实例中的所有元素之后插入新的元素。

方法：`on`¶

function on<K extends keyof HTMLElementEventMap>(
  type: K,
  listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any,
  options?: boolean | AddEventListenerOptions
): void;
function on(
  type: string,
  listener: EventListenerOrEventListenerObject,
  options?: boolean | AddEventListenerOptions
): void;

在当前 Dom 实例中的所有元素上添加事件监听器。

方法：`off`¶

function off<K extends keyof HTMLElementEventMap>(
  type: K,
  listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any,
  options?: boolean | EventListenerOptions
): void;
function off(
  type: string,
  listener: EventListenerOrEventListenerObject,
  options?: boolean | EventListenerOptions
): void;

在当前 Dom 实例中的所有元素上移除事件监听器。

方法：`push`¶

function push(...doms: (T | Dom<T>)[]): void;

向当前 Dom 实例添加新的元素。

方法：`remove`¶

function remove(...doms: (T | Dom<T> | number)[]): void;

从当前 Dom 实例中移除元素。

属性：`children`¶

type children = Dom<HTMLElement>;

只读属性，返回当前 Dom 实例中的所有子元素组成的 Dom 实例。

属性：`class`¶

type class = IDomClass<T extends HTMLElement = HTMLElement>;

只读属性，返回用于管理 Dom 实例中所有元素类名的接口 IDomClass。

属性：`attr`¶

type attr = IDomAttribute<T extends HTMLElement = HTMLElement>;

只读属性，返回用于管理 Dom 实例中所有元素属性的接口 IDomAttribute。

属性：`length`¶

type length = number;

只读属性，返回当前 Dom 实例中的元素数量。

属性：`rect`¶

type rect = DOMRect[];

只读属性，返回当前 Dom 实例中的所有元素的 DOMRect 对象。

属性：`data`¶

type data = { [key: string]: string };

只读属性，返回用于修改当前 Dom 实例中的所有元素数据属性的对象。
注意：该对象的 get 方法不稳定。

使用示例：

let dom = new Dom('body');
// 设置元素数据属性
dom.data.name = 'test';
// 获取第一个元素的数据属性（不稳定）
let name = dom.data.name;
// 删除元素数据属性
delete dom.data.name;
// 检查是否有元素数据属性
let hasName = 'name' in dom.data;

属性：`style`¶

type style = CSSTokens;

只读属性，返回用于修改当前 Dom 实例中的所有元素样式属性的对象。
注意：该对象的 get 方法不稳定；部分行为与 CSSStyleDeclaration 对象不同。

使用示例：

let dom = new Dom('body');
// 设置元素样式属性
dom.style.color = 'red';
// 获取第一个元素的样式属性（不稳定）
let color = dom.style.color;
// 删除元素样式属性
delete dom.style.color;
// 检查是否有元素样式属性
let hasColor = 'color' in dom.style;

// 设置元素样式变量
dom.style['--color'] = 'red';
// 获取第一个元素的样式变量（不稳定）
color = dom.style.['--color'];
// 删除元素样式变量
delete dom.style.['--color'];
// 检查是否有元素样式变量
hasColor = '--color' in dom.style;

属性：`doms`¶

type doms = Array<T extends HTMLElement = HTMLElement>;

只读属性，返回当前 Dom 实例中的所有元素。

属性：`id`¶

type id = string;

注意：不稳定。
获取当前 Dom 实例中的第一个元素的 ID。修改当前 Dom 实例中的所有元素的 ID。

函数：`$`¶

function $<T extends HTMLElement = HTMLElement>(
  ...args: (string | T | Dom<T>)[]
): Dom<T>;

接受任意数量的参数，每个参数可以是字符串、DOM 元素或 Dom 实例。
string 类型的参数将作为函数 document.querySelectorAll 的参数，查询结果将存入 Dom 实例中。
该函数为 new Dom() 简写。

除此之外，还有其他简写：

简写函数	原函数
`$.pug`	`Dom.pug`
`$.html`	`Dom.html`
`$.layout`	`Dom.layout`
`$.from`	`Dom.from`
`$.new`	`Dom.new`

接口：`IDomClass`¶

该接口类似于 DOMTokenList，但是只有方法可以使用。

方法：`add`¶

function add(...args: string[]): void;

添加一个或多个类名到当前 Dom 实例中的所有元素。

方法：`contains`¶

function contains(name: string): boolean;

检查当前 Dom 实例中的所有元素是否包含指定类名。

方法：`remove`¶

function remove(...args: string[]): void;

移除一个或多个类名到当前 Dom 实例中的所有元素。

方法：`replace`¶

function replace(name: string, newName: string): void;

替换当前 Dom 实例中的所有元素的指定类名。

方法：`toggle`¶

function toggle(name: string, force?: boolean): void;

切换当前 Dom 实例中的所有元素的指定类名。

方法：`setClassText`¶

function setClassText(text: string): void;

直接设置当前 Dom 实例中的所有元素的类名。

接口：`IDomAttribute`¶

方法：`get`¶

function get(name: string): (string | null)[];

获取当前 Dom 实例中的所有元素的指定属性。

方法：`set`¶

function set(name: string, value: string): void;

设置当前 Dom 实例中的所有元素的指定属性。

方法：`remove`¶

function remove(name: string): void;

移除当前 Dom 实例中的所有元素的指定属性。

id¶

提供生成唯一 ID 的函数。

函数：`unid`¶

function unid(): string

根据时间和一个随机数，生成包含 26 位字母和数值的不定长的唯一 ID。

math¶

提供额外的数学计算工具。

函数：`range`¶

function range(from: number, to: number, step: number = 1): number[];

生成一个包含指定范围内的所有数字的数组。

函数：`clamp`¶

function clamp(min: number, value: number, max: number): number;

限制一个数值在指定范围内。

path¶

提供路径计算工具。

函数：`distPath`¶

function distPath(...path: string[]): string;

将相对路径转换为编译产物的绝对路径。

函数：`pathNormalize`¶

function pathNormalize(...path: string[]): string;

将路径转换为合法文件名。

position¶

提供设置元素位置工具。

函数：`setPosition`¶

function setPosition(
  target: HTMLElement,
  size: Size,
  around: OutlineRect,
  align: Align = 'v-corner'
): Side;

设置元素的位置。
若要调整显示安全区，请修改 config/ui.json 中的参数 safetyZone，顺序为“上、右、下、左”。

函数：`getScaleFactor`¶

function getScaleFactor(w: number, h: number, increment: number): number;

计算增加指定尺寸后，元素的缩放比例。

类型：`Size`¶

type Size = {
  width: number;
  height: number;
};

表示矩形大小的对象。

类型：`OutlineRect`¶

type OutlineRect = {
  top: number;
  right: number;
  bottom: number;
  left: number;
};

表示矩形外框大小、位置的对象。

类型：`Align`¶

type Side = {
  v: 'top' | 'bottom';
  h: 'left' | 'right';
};

表示对齐的边的位置的对象。只有角落对齐时，这些参数才有实际意义。
v 为纵向对齐上或下边。
h 为横向对齐左边或右边。

类型：`Side`¶

type Align =
  | 'corner'
  | 'h-corner'
  | 'v-corner'
  | 'h-center'
  | 'v-center';

表示对齐位置的对象。

值	说明
`corner`	角落
`h-corner`	横向角落
`v-corner`	纵向角落
`h-center`	横向中心
`v-center`	纵向中心

timer¶

提供定时器工具。

函数：`sleep`¶

function sleep(ms: number = 0): Promise<void>;

返回一个 Promise 对象，在指定毫秒后兑现。

函数：`frame`¶

function frame(): Promise<void>;

返回一个 Promise 对象，当浏览器下次重绘时兑现。

function¶

函数执行相关工具。

函数：`run`¶

function run<T = any, Args extends Array<any> = any[]>(
  fn: any,
  ...args: Args
): Promise<T | Error>;

异步地执行目标函数，且不会抛出错误。
args 为尝试执行的函数的参数。

返回一个 Promise 对象。若函数成功执行，兑现值为函数返回值；若函数执行失败，兑现值为 Error 对象。

函数：`runSequence`¶

function runSequence(
  sequence: OperationSequence,
  ignoreError: boolean
): void;

依次执行任务队列，若发生错误，则停止执行。
sequence 为需要执行的任务队列。
ignoreError 为是否忽略错误，默认值 false。

类型：`OperationNode`¶

type OperationNode = Function | number;

当为 Function 时，表示一个函数。
当为 number 时，表示一个延时时间。

类型：`OperationSequence`¶

type OperationSequence = OperationNode[];

包含数个任务节点 OperationNode 的任务队列。

工具¶

API¶

dom¶

类：Dom¶

静态函数：pug¶

静态函数：html¶

静态函数：layout¶

静态函数：from¶

静态函数：new¶

方法：filter¶

方法：query¶

方法：map¶

方法：clone¶

方法：at¶

方法：forEach¶

方法：every¶

方法：any¶

方法：before¶

方法：prepend¶

方法：append¶

方法：after¶

方法：on¶

方法：off¶

方法：push¶

方法：remove¶

属性：children¶

属性：class¶

属性：attr¶

属性：length¶

属性：rect¶

属性：data¶

属性：style¶

属性：doms¶

属性：id¶

函数：$¶

接口：IDomClass¶

方法：add¶

方法：contains¶

方法：remove¶

方法：replace¶

方法：toggle¶

方法：setClassText¶

接口：IDomAttribute¶

方法：get¶

方法：set¶

方法：remove¶

id¶

函数：unid¶

math¶

函数：range¶

函数：clamp¶

path¶

函数：distPath¶

函数：pathNormalize¶

position¶

函数：setPosition¶

函数：getScaleFactor¶

类型：Size¶

类型：OutlineRect¶

类型：Align¶

类型：Side¶

timer¶

函数：sleep¶

函数：frame¶

function¶

函数：run¶

函数：runSequence¶

类型：OperationNode¶

类型：OperationSequence¶

类：`Dom`¶

静态函数：`pug`¶

静态函数：`html`¶

静态函数：`layout`¶

静态函数：`from`¶

静态函数：`new`¶

方法：`filter`¶

方法：`query`¶

方法：`map`¶

方法：`clone`¶

方法：`at`¶

方法：`forEach`¶

方法：`every`¶

方法：`any`¶

方法：`before`¶

方法：`prepend`¶

方法：`append`¶

方法：`after`¶

方法：`on`¶

方法：`off`¶

方法：`push`¶

方法：`remove`¶

属性：`children`¶

属性：`class`¶

属性：`attr`¶

属性：`length`¶

属性：`rect`¶

属性：`data`¶

属性：`style`¶

属性：`doms`¶

属性：`id`¶

函数：`$`¶

接口：`IDomClass`¶

方法：`add`¶

方法：`contains`¶

方法：`remove`¶

方法：`replace`¶

方法：`toggle`¶

方法：`setClassText`¶

接口：`IDomAttribute`¶

方法：`get`¶

方法：`set`¶

方法：`remove`¶

函数：`unid`¶

函数：`range`¶

函数：`clamp`¶

函数：`distPath`¶

函数：`pathNormalize`¶

函数：`setPosition`¶

函数：`getScaleFactor`¶

类型：`Size`¶

类型：`OutlineRect`¶

类型：`Align`¶

类型：`Side`¶

函数：`sleep`¶

函数：`frame`¶

函数：`run`¶

函数：`runSequence`¶

类型：`OperationNode`¶

类型：`OperationSequence`¶