ph-utils/lib/dom.d.ts

js 开发工具集，前后端都可以使用(commonjs和es module)

/**
 * web(浏览器端) DOM 文件操作
 * 现今不推荐在使用这种方式，现在开发前端的时候，推荐使用一些成熟的框架例如：React、Preact、Vue、Angular、Svelte、Ember、Knockout等
 * 在使用这些框架的时候额外的一些不可避免的 dom 操作时才使用这个工具；如果确实需要使用原生开发推荐使用 jquery 或者想要更精简的话可以使用 https://github.com/finom/bala 封装
 */
/**
 * 根据选择器获取节点
 * @param {string} selector 选择器
 */
type FormatStyleParam =
  | (string | undefined | null)[]
  | Record<string, boolean | string | undefined | null>
  | string;
type FormatClassParam =
  | (string | undefined | null | boolean)[]
  | Record<string, boolean | string | undefined | null | boolean>
  | string;
type DocumentContext = HTMLElement | ShadowRoot | Document;
type NodeChildren =
  | HTMLElement
  | DocumentFragment
  | HTMLElement[]
  | NodeListOf<HTMLElement>
  | HTMLCollection;
export declare function elem(selector: string | HTMLElement, dom?: DocumentContext): HTMLElement[];
/**
 * 根据选择器获取 DOM 元素。
 * @param selector - 选择器字符串或 HTMLElement 实例。
 * @param dom - 可选参数，指定在哪个 DOM 节点下查找元素，默认为 document。
 * @returns 返回匹配到的 HTMLElement 实例。
 */
export declare function $(selector: string | HTMLElement, dom?: DocumentContext): HTMLElement[];
/**
 * 创建一个 HTML 元素，支持通过标签名或 HTML 字符串创建。
 * @param tag - 元素标签名或 HTML 字符串。
 * @param option - 元素的属性、样式、文本内容等配置。所有不是指定的属性，都会通过 setAttribute 设置
 * @param children - 子节点
 * @returns 创建的 HTML 元素。
 */
export declare function create(
  tag: string,
  option?: {
    class?: FormatClassParam;
    style?: FormatStyleParam;
    textContent?: string;
    innerHTML?: string;
    outerHTML?: string;
    [index: string]: any;
  },
  children?: NodeChildren,
): HTMLElement;
/** 创建节点 */
export declare function $$(
  tag: string,
  option?: {
    class?: FormatClassParam;
    style?: FormatStyleParam;
    textContent?: string;
    innerHTML?: string;
    outerHTML?: string;
    [index: string]: any;
  },
  children?: NodeChildren,
): HTMLElement;
/**
 * 根据选择器获取匹配的第一个 DOM 元素。
 * @param selector - 选择器字符串或直接的 HTMLElement。
 * @param dom - 可选的父级 DOM 元素，默认为当前文档。
 * @returns 返回匹配的第一个 HTMLElement，如果没有找到则返回 null。
 */
export declare function $one(
  selector: string | HTMLElement,
  dom?: DocumentContext,
): HTMLElement | null;
/**
 * 为节点添加 class
 * @param {HTMLElement} elem 待添加 class 的节点
 * @param {string} clazz     需要添加的 class
 */
export declare function addClass(elem: HTMLElement, clazz: string): void;
/**
 * 节点移除 class
 * @param {HTMLElement} elem 待移除 class 的节点
 * @param {string} clazz     需要移除的 class
 */
export declare function removeClass(elem: HTMLElement, clazz: string): void;
/**
 * 判断节点是否包含某个 class
 * @param elem  待判断 class 的节点
 * @param clazz 待判断的 class
 * @returns
 */
export declare function hasClass(elem: HTMLElement, clazz: string): boolean;
/**
 * 切换指定元素的类名。
 * 如果元素已包含该类名，则移除它；否则添加它。
 * @param el - 要操作的 HTML 元素。
 * @param clazz - 要切换的类名。
 */
export declare function toggleClass(el: HTMLElement, clazz: string): void;
/**
 * 替换指定元素的 CSS 类
 *
 * 该函数用于根据给定的旧类名或类索引，将其替换为新类名。
 * 如果旧类不存在，则不会进行替换。
 *
 * @param el - 目标 HTML 元素，将对其类进行操作
 * @param oldClazz - 要替换的旧类名或类索引（基于数字时对应 classList 的索引位置）
 * @param newClazz - 新的类名，用于替换旧的类
 * @returns void
 */
export declare function replaceClass(
  el: HTMLElement,
  oldClazz: string | number,
  newClazz: string,
): void;
type EventHandler = EventListenerOrEventListenerObject | ((e: CustomEvent) => void);
/**
 * 为节点添加事件处理
 * @param {HTMLElement} element   添加事件的节点
 * @param {string}      listener  事件名称
 * @param {function}    fn     事件处理函数
 * @param {boolean}     option  是否是只运行一次的处理函数或者配置，其中 eventFlag 为 string，如果配置该项，则表明为委托事件
 */
export declare function on(
  element:
    | HTMLElement
    | ShadowRoot
    | Document
    | HTMLCollection
    | NodeListOf<HTMLElement>
    | HTMLElement[],
  listener: string,
  fn: EventHandler,
  option?:
    | boolean
    | (AddEventListenerOptions & {
        eventFlag?: string;
      }),
): void;
/**
 * 移除指定元素的事件监听器。
 * @param el - 要移除监听器的 HTML 元素。
 * @param listener - 事件名称。
 * @param fn - 要移除的事件监听器函数。
 */
export declare function off(
  el:
    | HTMLElement
    | ShadowRoot
    | Document
    | HTMLCollection
    | NodeListOf<HTMLElement>
    | HTMLElement[],
  listener: string,
  fn: EventHandler,
  option?: boolean | EventListenerOptions,
): void;
/**
 * 判断事件是否应该继续传递。
 * 从事件目标开始向上遍历DOM树，检查每个节点上是否存在指定的属性。
 * 如果找到该属性且其值不为'__stop__'，则返回true，表示事件可以继续传递。
 * 否则，返回false，表示事件应该停止传递。
 * 通常用于事件委托时判断是否继续传递事件。
 *
 * @param e - 触发的事件对象
 * @param eventFlag - 需要检查的属性名
 * @param endRoot - 可选，如果传递该参数，则表示停止遍历的节点，如果未传递，则表示遍历到文档根节点为止
 * @returns 包含三个元素的数组：[是否继续传递事件, 属性值, 当前检查的DOM节点]
 */
export declare function shouldEventNext(
  e: Event,
  eventFlag: string,
  endRoot?: HTMLElement | ShadowRoot,
): [boolean, string, HTMLElement];
/**
 * 设置或获取节点的 innerHTML 属性
 * @param element
 * @param htmlstr 可选，如果传递该参数，则表示设置；否则表示获取
 * @returns
 */
export declare function html(element: HTMLElement, htmlstr?: string): string | undefined;
/**
 * 设置或获取节点的 textContent 属性
 * @param element
 * @param textstr 可选，如果传递该参数，则表示设置；否则表示获取
 * @returns
 */
export declare function text(element: HTMLElement, textstr?: string): string | undefined | null;
export declare function iterate<T>(elems: T[], fn: (el: T, index: number) => any): void;
export declare function iterate(
  elems: NodeList | HTMLCollection | NodeListOf<HTMLElement>,
  fn: (el: HTMLElement, index: number) => any,
): void;
/**
 * 设置或获取节点 data-* 属性
 * @param elem
 * @param key data- 后面跟随的值
 * @param value 如果传递该值表示获取；否则表示设置
 * @returns
 */
export declare function attr(
  elem: HTMLElement,
  key: string,
  value?: string,
): string | null | undefined;
/**
 * 获取属性值
 * @param key 属性名称
 */
export declare function getAttr(el: HTMLElement, key: string): string;
/**
 * 获取属性值，同时将值转换为默认值的类型，如果未赋值，则返回默认值；
 * @param key 属性名称
 * @param defaultValue 默认值
 */
export declare function getAttr(el: HTMLElement, filepath: string, defaultValue: string): string;
export declare function getAttr(el: HTMLElement, filepath: string, defaultValue: number): number;
export declare function getAttr(el: HTMLElement, filepath: string, defaultValue: boolean): boolean;
export declare function getAttr<T extends Record<string, string | number | boolean>>(
  el: HTMLElement,
  filepath: string,
  defaultValue: T,
): T;
/**
 * 获取指定节点的父节点
 * @param el
 * @returns
 */
export declare function parent(el: HTMLElement): HTMLElement;
/**
 * 获取隐藏节点的尺寸, 如果 parent 传空, 且 hideNode 为节点，则会通过修改原始样式方式计算
 * @param {string | HTMLElement} hideNode - The node to hide.
 * @param parent - 添加临时节点的父节点, 如果传递 null, 则通过修改原始样式方式计算，默认为: body.
 * @returns The DOMRect of the element.
 */
export declare function queryHideNodeSize(
  hideNode: string | HTMLElement,
  parent?: null | HTMLElement,
): {
  width: number;
  height: number;
};
/**
 * 判断元素是否在父元素的可视区域内。
 *
 * @param el 要检查的元素
 * @param parent 元素的父元素，默认为document.body
 * @param direction 检查的方向，默认为"horizontal"
 * @returns 如果元素在父元素的可视区域内，则返回true；否则返回false。
 */
export declare function isVisible(
  el: HTMLElement,
  parent?: HTMLElement | null | undefined,
  direction?: string,
): boolean;
/**
 * 判断当前设备是否为移动设备。
 *
 * 本函数通过检查用户代理字符串和屏幕尺寸来判断设备是否为移动设备。
 * 这对于需要根据设备类型进行不同布局或功能调整的应用非常有用。
 *
 * @returns {boolean} 如果设备是移动设备，则返回true；否则返回false。
 */
export declare function isMobile(): boolean;
/**
 * 格式化类名，支持数组和对象两种形式。
 * - 数组形式：数组中的每个元素代表一个类名，非空元素将被添加到结果字符串中。
 * - 对象形式：对象的键代表类名，值为真（非空、非undefined、非null）时，键将被添加到结果字符串中。
 * @param classObj - 类名对象或数组
 * @returns 格式化后的类名字符串
 */
export declare function formatClass(
  classObj:
    | (boolean | string | undefined | null)[]
    | Record<string, boolean | string | undefined | null>
    | string,
): string;
/**
 * 将样式对象格式化为 CSS 样式字符串。
 * @param styleObj - 样式对象，可以是字符串数组或键值对对象。
 * @returns 格式化后的 CSS 样式字符串。
 */
export declare function formatStyle(styleObj: FormatStyleParam): string;
/**
 * 执行元素的过渡动画。
 *
 * 如果是名称类似于 Vue.js 的过渡动画，通过添加 `*-active`、`*-from|to` class 类名。
 *
 * @param el - 需要执行过渡动画的 HTML 元素。
 * @param nameOrProperties - 过渡动画的名称或属性数组。可以是字符串表示的动画名称，或者是包含属性名称、初始值或目标值、持续时间。eg. [['opacity', '0.5']] | 'nt-opacity'
 * @param dir - 过渡动画的方向，"leave" 表示离开，"enter" 表示进入。默认值为 "enter"。
 * @param finish - 过渡动画结束时的回调函数。
 *
 * @example <caption>执行 `nt-opacity` 名称动画</caption>
 * // css
 * .nt-opacity-enter-active,
 * .nt-opacity-leave-active {
 *  transition: opacity 0.3s ease;
 * }
 * .nt-opacity-enter-from,
 * .nt-opacity-leave-to {
 *   opacity: 0;
 * }
 * // js
 * transition($el, "nt-opacity", "enter");
 *
 * @example <caption>执行 `style` 属性动画</caption>
 * transition($el, [["opacity", "0", "0.3s"]], "enter");
 *
 * @example <caption>动画结束后移除节点</caption>
 * transition($el, [["opacity", "0", "0.3s"]], "leave", () => {  $el.remove(); });
 */
export declare function transition(
  el: HTMLElement,
  nameOrProperties: string | [string, string, string][],
  dir?: "leave" | "enter",
  finish?: () => void,
): void;
/**
 * 计算光标位置
 *
 * 根据输入值的变化计算新的光标位置，主要用于输入框内容变化时的光标位置调整
 *
 * @param start - 光标起始位置，通常为: input.selectionStart
 * @param end - 光标结束位置（通常与起始位置相同，用于选择范围），通常为: input.selectionEnd
 * @param oldValue - 变化前的值
 * @param newValue - 变化后的值
 * @returns 新的光标位置对象，包含新的起始和结束位置
 *
 * @example
 * // 删除字符时，光标向前移动
 * calcuteCursorPosition(2, 2, "abc", "ac"); // 返回 { start: 1, end: 1 }
 *
 * @example
 * // 添加字符时，光标向后移动
 * calcuteCursorPosition(2, 2, "ac", "abc"); // 返回 { start: 3, end: 3 }
 *
 * @example
 * // 替换字符时，保持位置
 * calcuteCursorPosition(2, 2, "abc", "axc"); // 返回 { start: 2, end: 2 }
 */
export declare function calcuteCursorPosition(
  start: number,
  end: number,
  oldValue: string,
  newValue: string,
): {
  start: number;
  end: number;
};
export {};