ph-utils 0.20.1 → 1.1.0

package/lib/browser.d.ts

@@ -0,0 +1,439 @@
+//#region src/dom.d.ts
+/**
+ * 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;
+declare function elem(selector: string | HTMLElement, dom?: DocumentContext): HTMLElement[];
+/**
+ * 根据选择器获取 DOM 元素。
+ * @param selector - 选择器字符串或 HTMLElement 实例。
+ * @param dom - 可选参数，指定在哪个 DOM 节点下查找元素，默认为 document。
+ * @returns 返回匹配到的 HTMLElement 实例。
+ */
+declare function $(selector: string | HTMLElement, dom?: DocumentContext): HTMLElement[];
+/**
+ * 创建一个 HTML 元素，支持通过标签名或 HTML 字符串创建。
+ * @param tag - 元素标签名或 HTML 字符串。
+ * @param option - 元素的属性、样式、文本内容等配置。所有不是指定的属性，都会通过 setAttribute 设置
+ * @param children - 子节点
+ * @returns 创建的 HTML 元素。
+ */
+declare function create(tag: string, option?: {
+  class?: FormatClassParam;
+  style?: FormatStyleParam;
+  textContent?: string;
+  innerHTML?: string;
+  outerHTML?: string;
+  [index: string]: any;
+}, children?: NodeChildren): HTMLElement;
+/** 创建节点 */
+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。
+ */
+declare function $one(selector: string | HTMLElement, dom?: DocumentContext): HTMLElement | null;
+/**
+ * 为节点添加 class
+ * @param {HTMLElement} elem 待添加 class 的节点
+ * @param {string} clazz     需要添加的 class
+ */
+declare function addClass(elem: HTMLElement, clazz: string): void;
+/**
+ * 节点移除 class
+ * @param {HTMLElement} elem 待移除 class 的节点
+ * @param {string} clazz     需要移除的 class
+ */
+declare function removeClass(elem: HTMLElement, clazz: string): void;
+/**
+ * 判断节点是否包含某个 class
+ * @param elem  待判断 class 的节点
+ * @param clazz 待判断的 class
+ * @returns
+ */
+declare function hasClass(elem: HTMLElement, clazz: string): boolean;
+/**
+ * 切换指定元素的类名。
+ * 如果元素已包含该类名，则移除它；否则添加它。
+ * @param el - 要操作的 HTML 元素。
+ * @param clazz - 要切换的类名。
+ */
+declare function toggleClass(el: HTMLElement, clazz: string): void;
+/**
+ * 替换指定元素的 CSS 类
+ *
+ * 该函数用于根据给定的旧类名或类索引，将其替换为新类名。
+ * 如果旧类不存在，则不会进行替换。
+ *
+ * @param el - 目标 HTML 元素，将对其类进行操作
+ * @param oldClazz - 要替换的旧类名或类索引（基于数字时对应 classList 的索引位置）
+ * @param newClazz - 新的类名，用于替换旧的类
+ * @returns void
+ */
+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，如果配置该项，则表明为委托事件
+ */
+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 - 要移除的事件监听器函数。
+ */
+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节点]
+ */
+declare function shouldEventNext(e: Event, eventFlag: string, endRoot?: HTMLElement | ShadowRoot): [boolean, string, HTMLElement];
+/**
+ * 设置或获取节点的 innerHTML 属性
+ * @param element
+ * @param htmlstr 可选，如果传递该参数，则表示设置；否则表示获取
+ * @returns
+ */
+declare function html(element: HTMLElement, htmlstr?: string): string | undefined;
+/**
+ * 设置或获取节点的 textContent 属性
+ * @param element
+ * @param textstr 可选，如果传递该参数，则表示设置；否则表示获取
+ * @returns
+ */
+declare function text(element: HTMLElement, textstr?: string): string | undefined | null;
+declare function iterate<T>(elems: T[], fn: (el: T, index: number) => any): void;
+declare function iterate(elems: NodeList | HTMLCollection | NodeListOf<HTMLElement>, fn: (el: HTMLElement, index: number) => any): void;
+/**
+ * 设置或获取节点 data-* 属性
+ * @param elem
+ * @param key data- 后面跟随的值
+ * @param value 如果传递该值表示获取；否则表示设置
+ * @returns
+ */
+declare function attr(elem: HTMLElement, key: string, value?: string): string | null | undefined;
+/**
+ * 获取属性值
+ * @param key 属性名称
+ */
+declare function getAttr(el: HTMLElement, key: string): string;
+/**
+ * 获取属性值，同时将值转换为默认值的类型，如果未赋值，则返回默认值；
+ * @param key 属性名称
+ * @param defaultValue 默认值
+ */
+declare function getAttr(el: HTMLElement, filepath: string, defaultValue: string): string;
+declare function getAttr(el: HTMLElement, filepath: string, defaultValue: number): number;
+declare function getAttr(el: HTMLElement, filepath: string, defaultValue: boolean): boolean;
+declare function getAttr<T extends Record<string, string | number | boolean>>(el: HTMLElement, filepath: string, defaultValue: T): T;
+/**
+ * 获取指定节点的父节点
+ * @param el
+ * @returns
+ */
+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.
+ */
+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。
+ */
+declare function isVisible(el: HTMLElement, parent?: HTMLElement | null | undefined, direction?: string): boolean;
+/**
+ * 判断当前设备是否为移动设备。
+ *
+ * 本函数通过检查用户代理字符串和屏幕尺寸来判断设备是否为移动设备。
+ * 这对于需要根据设备类型进行不同布局或功能调整的应用非常有用。
+ *
+ * @returns {boolean} 如果设备是移动设备，则返回true；否则返回false。
+ */
+declare function isMobile(): boolean;
+type ClsxValue = string | number | boolean | undefined | null | ClsxValue[] | Record<string, boolean | string | number | undefined | null>;
+/**
+ * 条件化类名拼接工具，支持任意嵌套的字符串、数组、对象参数。
+ * - 字符串/数字：直接拼接
+ * - 数组：递归处理每个元素
+ * - 对象：值为真时拼接键名
+ * - falsy 值（false、null、undefined、0、""）：跳过
+ * @param args - 任意数量的类名参数
+ * @returns 拼接后的类名字符串
+ */
+declare function clsx(...args: ClsxValue[]): string;
+/**
+ * 格式化类名，支持数组和对象两种形式。
+ * - 数组形式：数组中的每个元素代表一个类名，非空元素将被添加到结果字符串中。
+ * - 对象形式：对象的键代表类名，值为真（非空、非undefined、非null）时，键将被添加到结果字符串中。
+ * @param classObj - 类名对象或数组
+ * @returns 格式化后的类名字符串
+ */
+declare function formatClass(classObj: (boolean | string | undefined | null)[] | Record<string, boolean | string | undefined | null> | string): string;
+type StyxBaseValue = string | boolean | undefined | null;
+type StyxValue = StyxBaseValue | StyxBaseValue[] | Record<string, StyxBaseValue | number>;
+/**
+ * 条件化样式拼接工具，支持任意嵌套的字符串、数组、对象参数。
+ * - 字符串：直接拼接（自动补 `;`）
+ * - 数组：递归处理每个元素
+ * - 对象：拼接为 `key:value;` 格式
+ * - falsy 值（false、null、undefined、0、""）：跳过
+ * @param args - 任意数量的样式参数
+ * @returns 拼接后的样式字符串
+ */
+declare function styx(...args: StyxValue[]): string;
+/**
+ * 将样式对象格式化为 CSS 样式字符串。
+ * @param styleObj - 样式对象，可以是字符串数组或键值对对象。
+ * @returns 格式化后的 CSS 样式字符串。
+ */
+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(); });
+ */
+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 }
+ */
+declare function calcuteCursorPosition(start: number, end: number, oldValue: string, newValue: string): {
+  start: number;
+  end: number;
+};
+//#endregion
+//#region src/copy.d.ts
+/**
+ * 复制数据, 可以从多种类型的数据
+ *    1. 直接复制文本: await copy("待复制的文本")
+ *    2. 复制节点上的 data-copy-text:
+ *      <button data-copy-text="这是待复制的文本">复制</button>
+ *      await copy(e.target) // or await copy("#a") or await copy(document.querySelector('#a'))
+ *    3. 直接复制节点本身数据: await copy('#a')
+ * @param {string | HTMLElement} source 复制源, 从中解析待复制的数据
+ * @returns {Promise<boolean>} 是否复制成功
+ */
+declare function copy(source: string | HTMLElement): Promise<boolean>;
+//#endregion
+//#region src/storage.d.ts
+/**
+ * 缓存相关
+ */
+type StorageType = "session" | "local";
+interface StorageSetOption {
+  storage?: StorageType;
+  /** 数据有效期, 单位秒, 默认: -1 - 永久存储 */
+  expire?: number;
+}
+/**
+ * 存储值到 Storage 中
+ * @param key 设置的 key
+ * @param value 设置的值
+ * @param [option.storage] session 或 local, 默认: session
+ * @param [option.expire] 数据有效期, 单位秒, 默认: -1 - 永久存储
+ *
+ * @example <caption>1. 存储到 SessionStorage</caption>
+ * set("key", "value");
+ *
+ * @example <caption>2. 存储到 LocalStorage</caption>
+ * set("key", "value", { storage: "local" });
+ */
+declare function set(key: string, value: any, option?: StorageSetOption): void;
+/**
+ * 清空所有的缓存内容
+ * @param storage 待清空的缓存对象
+ */
+declare function clear(storage?: StorageType): void;
+/**
+ * 删除存储到 Storage 中的数据
+ * @param key
+ * @param storage
+ */
+declare function remove(key: string, storage?: StorageType): void;
+/** 从 Storage 中获取数据时的配置 */
+interface StorageQueryOption {
+  /** 数据是否持久化, 默认为: false, 设置为 true 则会在每一次取出数据后删除 */
+  delete?: boolean;
+  /** 存储对象, session、local */
+  storage?: StorageType;
+}
+/**
+ * 从 Storage 中取出数据
+ * @param key 保存时的 key
+ * @param defaultValue 没有数据时的默认值
+ * @param [option.delete] 是否在取出后，删除数据，默认：false - 取出后删除数据
+ * @param [option.storage] 使用的 Storage ，可以是 localStorage、sessionStorage, 默认: localStorage、sessionStorage
+ * @returns Storage 中 key 对应的数据
+ */
+declare function get<T>(key: string, defaultValue?: T, option?: StorageQueryOption): T;
+//#endregion
+//#region src/theme.d.ts
+/** 获取当前系统的主题 */
+declare function getSystemTheme(): "light" | "dark" | "auto";
+/**
+ * 初始化主题, 让网页能够适应系统主题, 同时根据缓存的主题切换主题
+ * @returns 当前应用的主题
+ */
+declare function initTheme(): Promise<"light" | "dark" | "auto">;
+/**
+ * 切换主题, 通常用于预览
+ * @param theme 切换的主题
+ * @param transition 是否使用过渡动画, 注意浏览器必须支持 document.startViewTransition, 默认: true
+ * @returns 切换后的主题
+ */
+declare function toggleTheme(theme?: "light" | "dark" | "auto", transition?: boolean): Promise<"light" | "dark" | "auto">;
+/** 获取当前主题 */
+declare function getTheme(): string;
+/**
+ * 应用主题
+ * @param theme 待应用的主题
+ * @param cache 是否缓存应用的主题, 让应用下一次启动的时候, 可以应用主题, 默认: true
+ * @param transition 是否使用过渡动画, 注意浏览器必须支持 document.startViewTransition, 默认: true
+ * @returns 应用的主题
+ */
+declare function applyTheme(theme?: "light" | "dark" | "auto", cache?: boolean, transition?: boolean): Promise<"light" | "dark" | "auto">;
+/** 获取当前主题色 */
+declare function getColorTheme(defaultValue?: string): string | undefined;
+/**
+ * 初始化主题色, 让网页能够适应系统主题色, 同时根据缓存的主题色切换主题色
+ * @returns 当前应用的主题色
+ */
+declare function initColorTheme(): Promise<string> | null;
+/**
+ * 切换主题色, 通常用于预览
+ * @param color 待切换的主题色
+ * @returns 切换后的主题色
+ */
+declare function toggleColorTheme(color: string): Promise<string>;
+/**
+ * 应用主题色
+ * @param color 主题色
+ * @param cache 是否缓存主题色, 让应用下一次启动的时候, 可以应用主题色, 默认: true
+ * @returns 切换后的主题色
+ */
+declare function applyColorTheme(color: string, cache?: boolean): Promise<string>;
+//#endregion
+//#region src/web.d.ts
+/**
+ * web(浏览器) 端工具类
+ */
+type FormValue = string | number | boolean;
+/**
+ * 解析 Form 表单中的 input 元素的数据为 JSON 格式，key: input-name；value: input-value
+ * @param form {object} Form 节点对象
+ */
+declare const formJson: <T extends Record<string, FormValue>>(form: HTMLFormElement) => T;
+type QueryResult = string | string[];
+/**
+ * 获取 url query 参数 (get 请求的参数)
+ * @param search 如果是 React 应用就需要传递 useLocation().search
+ * @returns
+ */
+declare function query(search?: string): Record<string, QueryResult>;
+/**
+ * 函数节流 - 每隔单位时间，只执行一次
+ * @param cb    待节流的函数
+ * @param wait  间隔时间
+ * @returns
+ */
+declare function throttle<R extends unknown[], T>(fn: (...args: R) => T, wait?: number): {
+  (...args: R): void;
+  cancel: () => void;
+};
+/**
+ * 函数防抖 - 当重复触发某一个行为（事件时），只执行最后一次触发
+ * @param fn        防抖函数
+ * @param interval  间隔时间段
+ * @returns
+ */
+declare function debounce<R extends unknown[], T>(fn: (...args: R) => T, interval?: number): {
+  (...args: R): void;
+  cancel: () => void;
+};
+//#endregion
+export { $, $$, $one, addClass, applyColorTheme, applyTheme, attr, calcuteCursorPosition, clear, clsx, copy, create, debounce, elem, formJson, formatClass, formatStyle, get, getAttr, getColorTheme, getSystemTheme, getTheme, hasClass, html, initColorTheme, initTheme, isMobile, isVisible, iterate, off, on, parent, query, queryHideNodeSize, remove, removeClass, replaceClass, set, shouldEventNext, styx, text, throttle, toggleClass, toggleColorTheme, toggleTheme, transition };