@polyv/utils-dom 3.0.0

package/interfaces.d.ts

@@ -0,0 +1,27 @@
+import { DOMWrapMember } from './types';
+import { EventWrap } from './event-wrap';
+/**
+ * Get first set all 操作中，设置值的函数。
+ */
+export interface IValueFunction<T> {
+    (this: DOMWrapMember, node: DOMWrapMember, value: T, index: number): T;
+}
+/**
+ * 事件监听回调函数。
+ */
+export interface IEventHandler {
+    (this: EventTarget, evt: EventWrap): unknown;
+}
+/**
+ * 表示元素在页面中的位置。
+ */
+export interface IPosition {
+    /**
+     * 与页面上边界的距离。
+     */
+    top: number;
+    /**
+     * 与页面左边界的距离。
+     */
+    left: number;
+}

package/internal/data-space.d.ts

@@ -0,0 +1,96 @@
+/**
+ * 为 DOM 节点提供数据空间。
+ * @packageDocumentation
+ * @internal
+ */
+/**
+ * 数据空间复制回调原型。
+ */
+interface ICloneCallback {
+    (this: DataSpace, target: unknown, source: unknown): void;
+}
+/**
+ * 数据空间类选项。
+ */
+export interface IDataSpaceOptions {
+    /**
+     * 是否可被复制。
+     */
+    cloneable?: boolean;
+    /**
+     * 复制时的回调。
+     */
+    onClone?: ICloneCallback;
+}
+/**
+ * 数据空间类。
+ */
+export declare class DataSpace {
+    /**
+     * 内部存储空间。
+     */
+    protected readonly _space: {
+        [key: string]: {
+            [key: string]: unknown;
+        };
+    };
+    /**
+     * 是否可被复制。
+     */
+    protected readonly _cloneable: boolean;
+    /**
+     * 克隆时的回调。
+     */
+    protected readonly _onClone: ICloneCallback | undefined;
+    /**
+     * 构造函数。
+     * @param options 选项。
+     */
+    constructor(options?: IDataSpaceOptions);
+    /**
+     * 返回指定对象的数据空间。
+     * @param obj 指定对象。
+     * @returns 指定对象的数据空间。
+     */
+    protected findSpace(obj: unknown): {
+        [key: string]: unknown;
+    } | undefined;
+    /**
+     * 获取指定对象的所有数据项名。
+     * @param obj 指定对象。
+     * @returns 指定对象的所有数据项名。
+     */
+    keys(obj: unknown): string[];
+    /**
+     * 获取指定对象特定数据项的值。
+     * @param obj 指定对象。
+     * @param key 数据项的键。
+     * @returns 数据项的值。
+     */
+    getData(obj: unknown, key: string): unknown;
+    /**
+     * 设置指定对象特定数据项的值。
+     * @param obj 指定对象。
+     * @param key 数据项的键。
+     * @param value 数据项的值。
+     */
+    setData(obj: unknown, key: string, value: unknown): void;
+    /**
+     * 清理指定对象的数据空间。
+     * @param obj 指定对象。
+     */
+    clearData(obj: unknown): void;
+    /**
+     * 删除指定对象特定数据项。
+     * @param obj 指定对象。
+     * @param key 数据项的键。
+     */
+    removeData(obj: unknown, key: string): void;
+    /**
+     * 把源对象的数据项复制到目标对象。
+     * @param target 源对象。
+     * @param source 目标对象。
+     */
+    cloneData(target: unknown, source: unknown): void;
+}
+export {};

package/internal/dom-attr.d.ts

@@ -0,0 +1,35 @@
+import { DOMWrapMember } from '../types';
+/**
+ * 获取指定节点特性值。
+ * @param node 指定节点。
+ * @param name 特性名。
+ * @returns 特性值。
+ */
+export declare function getProp(node: DOMWrapMember, name: string): unknown;
+/**
+ * 设置指定节点特性值。
+ * @param element 指定节点。
+ * @param name 特性名。
+ * @param value 特性值。
+ */
+export declare function setProp(node: DOMWrapMember, name: string, value: unknown): void;
+/**
+ * 获取指定节点的属性值。
+ * @param node 指定节点。
+ * @param name 属性名。
+ * @returns 属性值。
+ */
+export declare function getAttr(node: DOMWrapMember, name: string): string;
+/**
+ * 移除指定节点的属性。
+ * @param nodes 指定节点。
+ * @param names 属性名。
+ */
+export declare function removeAttr(nodes: ArrayLike<DOMWrapMember>, names: string | string[]): void;
+/**
+ * 设置指定节点的属性值。
+ * @param node 指定节点。
+ * @param name 属性名。
+ * @param value 属性值。
+ */
+export declare function setAttr(node: DOMWrapMember, name: string, value: string | boolean): void;

package/internal/dom-base.d.ts

@@ -0,0 +1,77 @@
+import { DOMWrapMember } from '../types';
+import { IValueFunction } from '../interfaces';
+/**
+ * 检查指定对象是否 window 对象。
+ * @param obj 指定对象。
+ * @returns `obj` 是否 window 对象。
+ */
+export declare function isWindow(obj: any): obj is Window;
+/**
+ * 检查指定对象是否 DOM 节点。
+ * @param obj 指定对象。
+ * @returns `obj` 是否 DOM 节点。
+ */
+export declare function isNode(obj: any): obj is Node;
+/**
+ * 检查指定对象是否 Document 节点。
+ * @param obj 指定对象。
+ * @returns `obj` 是否 Document 节点。
+ */
+export declare function isDocument(obj: any): obj is Document;
+/**
+ * 检查指定对象是否 HTML 元素节点。
+ * @param obj 指定对象。
+ * @returns `obj` 是否 HTML 元素节点。
+ */
+export declare function isHTMLElement(obj: any): obj is HTMLElement;
+/**
+ * 获取节点所在的 window。
+ * @param node 节点。
+ * @returns 节点所在的 window。如果不存在，则返回 null。
+ */
+export declare function getWindow(node: DOMWrapMember | null | undefined): Window | null;
+/**
+ * 把指定字符串以一个或多个空格为分隔符分割为数组。
+ * @param str 指定字符串（如果传入数组，则不执行分割）。
+ * @returns 字符串数组。
+ */
+export declare function splitBySpace(str: string | string[] | null | undefined): string[];
+/**
+ * 指定数组中的节点为 HTML 元素时才执行指定函数。
+ * @param nodes 指定节点数组。
+ * @param fn 指定函数。
+ */
+export declare function ifIsHTMLElement(nodes: ArrayLike<DOMWrapMember>, fn: (elem: HTMLElement) => void): void;
+/**
+ * 指定节点为 HTML 元素时才执行指定函数。
+ * @param node 指定节点。
+ * @param fn 指定函数。
+ * @returns 指定函数的返回值。
+ */
+export declare function ifIsHTMLElement(node: DOMWrapMember, fn: (elem: HTMLElement) => unknown): unknown;
+/**
+ * Get First Set All 访问器接口定义。
+ */
+interface IAccessor<T> {
+    get: (this: ArrayLike<DOMWrapMember>, node: DOMWrapMember, key: string) => T;
+    set: (this: ArrayLike<DOMWrapMember>, node: DOMWrapMember, key: string, value: T) => void;
+}
+/**
+ * Get First Set All 机制的核心函数。
+ * @param nodes 被访问节点。
+ * @param key 键名或键值对。为键值对时，则对每一对键值递归调用本函数。
+ * @param value 值。如果为 undefined，则为 get first 操作，否则为 set all 操作。
+ * @param isExec 当 value 为函数时，是否执行函数并以函数返回值作为最终值。
+ * @param accessor 访问器。
+ * @returns Get first 操作返回第一个节点键名对应的值；Set all 操作返回被访问节点。
+ */
+export declare function access<T>(nodes: ArrayLike<DOMWrapMember>, key: string | {
+    [key: string]: T | IValueFunction<T>;
+}, value: any, isExec: boolean | undefined, accessor: IAccessor<T>): any;
+/**
+ * 对指定节点数组进行排序，并过滤重复节点。
+ * @param nodes 指定节点数组。
+ * @returns 有序且无重复节点的节点数组。
+ */
+export declare function uniqueSort<T>(nodes: T[]): T[];
+export {};

package/internal/dom-class.d.ts

@@ -0,0 +1,26 @@
+import { DOMWrapMember } from '../types';
+/**
+ * 判断指定节点是否包含指定样式类。
+ * @param node 指定节点。
+ * @param className 样式类。
+ * @returns 指定节点是否包含指定样式类。
+ */
+export declare function hasClass(node: DOMWrapMember, className: string): boolean;
+/**
+ * 给指定节点添加样式类。
+ * @param nodes 指定节点。
+ * @param classNames 样式类。
+ */
+export declare function addClass(nodes: ArrayLike<DOMWrapMember>, classNames: string | string[]): void;
+/**
+ * 移除指定节点样式类。
+ * @param nodes 指定节点。
+ * @param classNames 样式类。不传时移除所有样式类。
+ */
+export declare function removeClass(nodes: ArrayLike<DOMWrapMember>, classNames?: string | string[]): void;
+/**
+ * 如果指定节点包含指定样式类，则移除；如果指定节点不包含指定样式类，则添加。
+ * @param nodes 指定节点。
+ * @param classNames 样式类。
+ */
+export declare function toggleClass(nodes: ArrayLike<DOMWrapMember>, classNames: string | string[]): void;

package/internal/dom-data.d.ts

@@ -0,0 +1,43 @@
+import { DataSpace, IDataSpaceOptions } from './data-space';
+/**
+ * 创建数据空间。
+ * @param options 空间配置。
+ * @returns 数据空间对象。
+ */
+export declare function createDataSpace(options?: Readonly<IDataSpaceOptions>): DataSpace;
+/**
+ * 清空指定对象在所有数据空间的数据。
+ * @param obj 指定对象。
+ */
+export declare function clearAll(obj: unknown): void;
+/**
+ * 克隆指定对象在所有数据空间的数据。
+ * @param target 目标对象。
+ * @param source 源对象。
+ */
+export declare function cloneAll(target: unknown, source: unknown): void;
+/**
+ * 获取指定对象的自定义数据项值。
+ * @param obj 指定对象。
+ * @param key 数据项名。
+ * @returns 数据项值。
+ */
+export declare function getData(obj: unknown, key: string): unknown;
+/**
+ * 设置指定对象的自定义数据项。
+ * @param elem 指定对象。
+ * @param key 数据项名。
+ * @param value 数据项值。
+ */
+export declare function setData(obj: unknown, key: string, value: unknown): void;
+/**
+ * 移除指定对象的自定义数据项。
+ * @param list 指定对象的数组。
+ * @param keys 数据项名。
+ */
+export declare function removeData(list: ArrayLike<unknown>, keys: string | string[]): void;
+/**
+ * 移除指定对象的所有自定义数据项。
+ * @param list 指定对象的数组。
+ */
+export declare function clearData(list: ArrayLike<unknown>): void;

package/internal/dom-event.d.ts

@@ -0,0 +1,24 @@
+import { DOMWrapMember } from '../types';
+import { IEventHandler } from '../interfaces';
+/**
+ * 给指定节点的指定事件注册监听函数。
+ * @param nodes 指定节点。
+ * @param types 事件类型。
+ * @param selector 代理元素的选择器。
+ * @param handler 回调函数。
+ */
+export declare function onEvent(nodes: ArrayLike<DOMWrapMember>, types: string | string[], selector: string, handler?: IEventHandler): void;
+/**
+ * 给指定节点移除指定事件的监听函数。
+ * @param nodes 指定节点。
+ * @param types 事件类型。
+ * @param selector 代理元素的选择器。
+ * @param handler 回调函数。
+ */
+export declare function offEvent(nodes: ArrayLike<DOMWrapMember>, types?: string | string[], selector?: string, handler?: IEventHandler): void;
+/**
+ * 触发指定节点的事件。
+ * @param nodes 指定节点。
+ * @param type 事件类型。
+ */
+export declare function triggerEvent(nodes: ArrayLike<DOMWrapMember>, type: string): void;

package/internal/dom-id.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 维护 DOM 节点的唯一 id。
+ * @packageDocumentation
+ * @internal
+ */
+/**
+ * 获取指定元素的唯一 id。
+ * @param obj 指定元素。
+ * @param doNotSet 不存在唯一 id 时，是否不进行设置。
+ * @returns 唯一 id。
+ */
+export declare function getId(obj: any, doNotSet?: boolean): number | undefined;
+/**
+ * 移除指定元素的唯一 id。
+ * @param obj 指定元素。
+ */
+export declare function removeId(obj: unknown): void;

package/internal/dom-insertion.d.ts

@@ -0,0 +1,35 @@
+import { DOMWrapMember, InsertTarget } from '../types';
+/**
+ * 根据HTML创建节点。
+ * @param html HTML代码。
+ * @param ownerDocument 所属文档对象，默认为当前文档对象。
+ * @return 节点数组。
+ */
+export declare function htmlToNodes(html: string, ownerDocument: Document | undefined | null): Node[];
+/**
+ * 复制节点。
+ * @param elem 被复制节点。
+ * @param withData 是否复制节点数据。
+ * @param deepWithData 是否复制所有后代节点的数据。
+ * @returns 节点的副本。
+ */
+export declare function cloneNode(node: Node, withData?: boolean, deepWithData?: boolean): Node;
+export declare function insertToRefs(target: InsertTarget, refs: ArrayLike<DOMWrapMember>, howToInsert: (target: Node, ref: Node) => void, condition?: (node: Node) => boolean): void;
+export declare function insertRefsTo(target: InsertTarget, refs: ArrayLike<DOMWrapMember>, howToInsert: (target: Node, ref: Node) => void, condition?: (node: Node) => boolean): Node[];
+export declare function hasParent(node: Node): boolean;
+export declare function canHasChild(node: Node): boolean;
+export declare function appendChild(target: Node, parent: Node): void;
+export declare function prependChild(target: Node, parent: Node): void;
+export declare function insertBefore(target: Node, ref: Node): void;
+export declare function insertAfter(target: Node, ref: Node): void;
+export declare function replaceWith(target: Node, ref: Node): void;
+/**
+ * 把指定节点从文档中移除，并清理所有相关数据。
+ * @param nodes 指定节点。
+ */
+export declare function removeNodes(nodes: ArrayLike<DOMWrapMember>): void;
+/**
+ * 移除指定节点的所有后代节点，并清理后代节点的相关数据。
+ * @param nodes 指定节点。
+ */
+export declare function removeDescendantNodes(nodes: ArrayLike<DOMWrapMember>): void;

package/internal/dom-offset.d.ts

@@ -0,0 +1,8 @@
+import { DOMWrapMember } from '../types';
+import { IPosition } from '../interfaces';
+/**
+ * 获取指定节点相对于 document 的位置。
+ * @param node 指定节点。
+ * @returns 指定节点相对于 document 的位置。
+ */
+export declare function getOffset(node: DOMWrapMember): IPosition;

package/internal/dom-scroll.d.ts

@@ -0,0 +1,16 @@
+import { DOMWrapMember } from '../types';
+export type ScrollDistanceType = 'scrollTop' | 'scrollLeft';
+/**
+ * 获取指定节点的滚动距离。
+ * @param node 指定节点。
+ * @param type 滚动距离类型。
+ * @returns 滚动距离。
+ */
+export declare function getScroll(node: DOMWrapMember | null, type: string): number;
+/**
+ * 设置指定节点的滚动距离。
+ * @param node 指定节点。
+ * @param type 滚动距离类型。
+ * @param value 滚动距离。
+ */
+export declare function setScroll(node: DOMWrapMember, type: string, value: number): void;

package/internal/dom-size.d.ts

@@ -0,0 +1,11 @@
+import { DOMWrapMember } from '../types';
+/**
+ * 计算指定节点尺寸。
+ * @param elem 指定节点。
+ * @param which 尺寸维度。
+ * @param includePadding 是否包含 padding。
+ * @param includeBorder 是否包含 border。
+ * @param includeMargin 是否包含 margin。
+ * @returns 尺寸（px）。
+ */
+export declare function computeSize(elem: DOMWrapMember, which: 'Width' | 'Height', includePadding?: boolean, includeBorder?: boolean, includeMargin?: boolean): number;

package/internal/dom-style.d.ts

@@ -0,0 +1,25 @@
+import { DOMWrapMember } from '../types';
+/**
+ * 获取指定节点的样式属性值。
+ * @param node 指定节点。
+ * @param name 样式属性名。
+ * @returns 样式属性值。
+ */
+export declare function getStyle(node: DOMWrapMember, name: string): string;
+/**
+ * 设置指定节点的样式属性值。
+ * @param node 指定节点。
+ * @param name 样式属性名。
+ * @param value 样式属性值。
+ */
+export declare function setStyle(node: DOMWrapMember, name: string, value: string | number): void;
+/**
+ * 显示指定节点。
+ * @param nodes 指定节点。
+ */
+export declare function show(nodes: ArrayLike<DOMWrapMember>): void;
+/**
+ * 隐藏指定节点。
+ * @param node 指定节点。
+ */
+export declare function hide(nodes: ArrayLike<DOMWrapMember>): void;

package/internal/dom-traversal.d.ts

@@ -0,0 +1,46 @@
+import { DOMWrapMember, TraversalUntil } from '../types';
+/**
+ * 生成由上下文节点及其所有后代节点组成的数组。
+ * @param ctx 上下文节点。
+ * @returns 由上下文节点及其所有后代节点组成的数组。
+ */
+export declare function selfAndDescendants(ctx: Node): Array<Node>;
+type DOMPosition = 'nextElementSibling' | 'previousElementSibling' | 'parentNode' | 'firstElementChild';
+/**
+ * 按照上下文元素的相对位置查找元素，直到遇到符合特定规则的元素为止。
+ * @param ctxNodes 上下文节点。
+ * @param position 相对位置。
+ * @param until 截止选择器或截止元素。
+ * @param filter 过滤选择器。不为空时仅返回符合选择器规则的元素。
+ */
+export declare function findElementsUntil(ctxNodes: ArrayLike<DOMWrapMember>, position: DOMPosition, until?: TraversalUntil, filter?: string): HTMLElement[];
+/**
+ * 按照上下文元素的相对位置查找节点。
+ * @param ctxNodes 上下文元素。
+ * @param position 相对位置。
+ * @param filter 过滤选择器。不为空时仅返回符合选择器规则的元素。
+ * @param onlyFirst 是否只查找每个上下文元素的第一个相对位置元素。
+ * @returns 查找结果。
+ */
+export declare function findElements(ctxNodes: ArrayLike<DOMWrapMember>, position: DOMPosition, filter?: string, onlyFirst?: boolean): HTMLElement[];
+/**
+ * 获取指定上下文节点的子节点。
+ * @param ctxNodes 上下文节点。
+ * @param selector 选择器。不为空时仅返回符合选择器规则的子节点。
+ * @returns 子节点数组。
+ */
+export declare function getChildren(ctxNodes: ArrayLike<DOMWrapMember>, selector?: string): HTMLElement[];
+/**
+ * 获取指定上下文元素的所有同级元素。
+ * @param ctxNodes 上下文元素。
+ * @param selector 选择器。不为空时仅返回符合选择器规则的同级元素。
+ * @returns 同级元素数组。
+ */
+export declare function getSiblings(ctxNodes: ArrayLike<DOMWrapMember>, selector?: string): HTMLElement[];
+/**
+ * 获取指定节点在同级元素中的序号。
+ * @param node 指定元素。
+ * @returns 位置序号。
+ */
+export declare function getIndex(node: DOMWrapMember): number;
+export {};

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@polyv/utils-dom",
+  "version": "3.0.0",
+  "description": "DOM utilities for Polyv frontend development.",
+  "type": "module",
+  "main": "./index.js",
+  "module": "./index.js",
+  "types": "./index.d.ts",
+  "miniprogram": "./",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js",
+      "require": "./index.cjs"
+    }
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "@polyv/utils-array": "3.0.0",
+    "@polyv/utils-object": "3.0.0"
+  }
+}

package/selector.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 原生选择器接口的封装。
+ * @packageDocumentation
+ */
+/**
+ * 通过选择器和上下文匹配元素（querySelectorAll 的打补丁版）。
+ * @param selector 选择器。
+ * @param context 上下文。
+ * @returns 匹配到的元素。
+ */
+export declare function querySelectorAll(selector: string, context?: HTMLElement | Document): ArrayLike<HTMLElement>;
+/**
+ * 检查指定节点能否匹配指定选择器。
+ * @param node 指定节点。
+ * @param selector 指定选择器。
+ * @returns 指定节点能否匹配指定选择器。
+ */
+export declare function matchesSelector(node: Node, selector: string): boolean;

package/types.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 类型声明。
+ * @packageDocumentation
+ */
+/**
+ * 节点 或 Window。
+ */
+export type DOMWrapMember = Node | Window;
+/**
+ * 遍历 DOM 元素时的截止元素，或截止元素的选择
+ */
+export type TraversalUntil = string | HTMLElement | Array<HTMLElement>;
+/**
+ * 插入 DOM 节点时可接受的目标类型。
+ */
+export type InsertTarget = string | DOMWrapMember | ArrayLike<DOMWrapMember>;