ph-utils 0.17.2 → 0.19.0

package/lib/src/date.js

@@ -0,0 +1,202 @@
+/**
+ * node 和 web 端日期处理工具类
+ */
+// 配置日期格式的正则表达式
+const REGEX_FORMAT = /yy(?:yy)?|([HMmds])\1?|(S)?/g;
+// 由于 Date.parse() 不能正确解析 yyyy-dd-mm 格式的日期, 所以匹配手动解析
+const REGEX_PARSE = /^(\d{4})-?(\d{1,2})-?(\d{0,2})[^0-9]*(\d{1,2})?:?(\d{1,2})?:?(\d{1,2})?.?(\d{1,3})?$/;
+const ofArgs = {
+    start: [0, 0, 1, 0, 0, 0, 0],
+    end: [0, 11, -2, 23, 59, 59, 999],
+};
+const units = {
+    Date: ["date", "Date", "day", "Day", "D", "d"],
+    Month: ["Month", "month", "m"],
+    FullYear: ["Year", "year", "y"],
+    Hours: ["Hours", "hours", "H"],
+    Minutes: ["Minutes", "Minute", "minute", "minutes", "M"],
+    Seconds: ["Seconds", "seconds", "Second", "second", "s"],
+    Milliseconds: ["Milliseconds", "Millisecond", "milliseconds", "illisecond", "S"],
+};
+/**
+ * 不足位数, 前位补 0
+ * @param s 日期数字
+ * @param l 截取位数
+ * @returns {string}  补0后的日期数字
+ */
+function p(s, l = 2) {
+    /*
+     * 由于年份最多为4为，所以前面先添3个0
+     * slice() 从后开始提前字符串
+     */
+    return `000${s}`.slice(l * -1);
+}
+/**
+ * 将单位转换为首字母大写, 例如：hours -> Hours
+ * @param unit hours
+ * @returns
+ */
+function getUnit(unit) {
+    let period = null;
+    for (const [key, value] of Object.entries(units)) {
+        if (value.includes(unit)) {
+            period = key;
+            break;
+        }
+    }
+    if (period == null) {
+        throw new Error(`Invalid unit: ${unit}`);
+    }
+    return period;
+}
+/**
+ * 获取指定日期某个月的最后一天
+ * @param date  日期
+ * @param month 月份, 如果不传, 则当前月的最后一天
+ * @returns
+ */
+function getLastDayOfMonth(date, month) {
+    // 获取下个月的第一天
+    const lastDate = new Date(date.getFullYear(), (month || date.getMonth()) + 1, 1);
+    // 将下个月的第一天的日期减去一天，得到当前月的最后一天
+    lastDate.setDate(lastDate.getDate() - 1);
+    // 返回最后一天的日期
+    return lastDate.getDate();
+}
+/**
+ * 将日期格式化为指定形式的字符串
+ * @param date      日期
+ * @param pattern   格式化字符串 yyyy - 年, mm - 月, dd - 日, HH - 小时(24时制), MM - 分钟, ss - 秒, S - 毫秒, 默认: yyyy-mm-dd HH:MM:ss
+ */
+export function format(date, pattern = "yyyy-mm-dd HH:MM:ss") {
+    // eslint-disable-next-line
+    date = parse(date);
+    const d = date.getDate();
+    const y = date.getFullYear();
+    const m = date.getMonth();
+    const H = date.getHours();
+    const M = date.getMinutes();
+    const s = date.getSeconds();
+    const flags = {
+        yy: p(y),
+        yyyy: y,
+        m: m + 1,
+        mm: p(m + 1),
+        d: d,
+        dd: p(d),
+        H: H,
+        HH: p(H),
+        M: M,
+        MM: p(M),
+        s: s,
+        ss: p(s),
+        S: p(date.getMilliseconds(), 3),
+    };
+    if (pattern != null) {
+        return pattern.replace(REGEX_FORMAT, (flag) => {
+            if (flag in flags) {
+                return flags[flag];
+            }
+            return flag;
+        });
+    }
+    return String(date.getTime());
+}
+/**
+ * 将指定的参数解析为日期对象(Date)
+ * 参考 dayjs 实现, 也可以参考 https://github.com/nomiddlename/date-format
+ * @param date 待解析的日期参数
+ */
+export function parse(date) {
+    if (date == null)
+        return new Date();
+    if (typeof date === "string" && !/Z$/i.test(date)) {
+        const d = date.match(REGEX_PARSE);
+        if (d) {
+            return new Date(d[1], d[2] - 1, d[3] || 1, d[4] || 0, d[5] || 0, d[6] || 0, d[7] || 0);
+        }
+    }
+    if (typeof date === "number") {
+        return new Date(date <= 9999999999 ? date * 1000 : date);
+    }
+    return new Date(date);
+}
+/**
+ * 设置日期的开始或者结束的点
+ * @param date 日期，能够被 parse 解析的日期
+ * @param unit 单位，Date[D]、Minute[M], 默认为 Date
+ * @param isEnd true则为 endOf
+ */
+export function dateOf(date, unit, isEnd = false) {
+    /* 如果是设置某一天的开始时刻, 就需要将时、分、秒、毫秒设置为0，依次类推设置 */
+    const periods = ["Year", "Month", "Date", "Hours", "Minutes", "Seconds", "Milliseconds"];
+    let index = periods.indexOf(getUnit(unit || "Date"));
+    const clone = parse(date);
+    index++;
+    const setValues = ofArgs[isEnd === true ? "end" : "start"];
+    for (const len = periods.length; index < len; index++) {
+        let value = setValues[index];
+        if (value === -2) {
+            // 设置为某个月的最后一天的日期
+            value = getLastDayOfMonth(clone);
+        }
+        Date.prototype["set" + periods[index]].apply(clone, [setValues[index]]);
+    }
+    return clone;
+}
+/**
+ * 设置日期的开始的点
+ * @param date 日期，能够被 parse 解析的日期
+ * @param unit 单位，Date[D]、Minute[M], 默认为 Date
+ * @returns
+ */
+export function startOf(date, unit) {
+    return dateOf(date, unit);
+}
+/**
+ * 设置日期的结束点
+ * @param date 日期，能够被 parse 解析的日期
+ * @param unit 单位，Date[D]、Minute[M], 默认为 Date
+ * @returns
+ */
+export function endOf(date, unit) {
+    return dateOf(date, unit, true);
+}
+/**
+ * 获取时间戳
+ * @param ctime 时间
+ * @param pre 精度, s - 精确到秒, ms - 精确到毫秒, 默认: s
+ * @returns
+ */
+export function timestamp(ctime, pre = "s") {
+    let tm = parse(ctime).getTime();
+    return pre === "s" ? Math.floor(tm / 1000) : tm;
+}
+/**
+ * 日期加上指定时间后的日期
+ * @param date  指定的日期
+ * @param num   需要添加的数字, 如果这个参数传递一个小于0的数字，则就是日期减去相应的数字
+ * @param unit  需要添加的单位，date - 加减天数
+ * @param fmt   可选参数，如果传递了格式化的单位，则返回格式化后的日期, 格式化字符串 yyyy - 年, mm - 月, dd - 日, HH - 小时, MM - 分钟, ss - 秒
+ * @returns {Date | string} 如果传递了 fmt 参数，则返回 string，否则返回 Date
+ */
+export function add(date, num, unit, fmt) {
+    let sdate = new Date();
+    if (date != null) {
+        sdate = parse(date);
+    }
+    // eslint-disable-next-line
+    unit = getUnit(unit);
+    let fn = "set" + unit;
+    let gn = "get" + unit;
+    // @ts-ignore
+    let oldValue = Date.prototype[gn].apply(sdate);
+    // @ts-ignore
+    Date.prototype[fn].apply(sdate, [oldValue + num]);
+    if (typeof fmt === "string") {
+        return format(sdate, fmt);
+    }
+    else {
+        return sdate;
+    }
+}

package/lib/src/dom.d.ts

@@ -0,0 +1,265 @@
+/**
+ * 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 ctx - 元素的父级文档上下文。
+ * @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 {};