ph-utils 0.11.5 → 0.12.1

package/lib/dom.d.ts

@@ -7,21 +7,39 @@
  * 根据选择器获取节点
  * @param {string} selector 选择器
  */
-export declare function elem(selector: string | HTMLElement, dom?: HTMLElement | ShadowRoot | Document): NodeListOf<HTMLElement> | HTMLElement[];
+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;
+export declare function elem(selector: string | HTMLElement, dom?: DocumentContext): NodeListOf<HTMLElement> | HTMLElement[];
 /**
  * 根据选择器获取 DOM 元素。
  * @param selector - 选择器字符串或 HTMLElement 实例。
  * @param dom - 可选参数，指定在哪个 DOM 节点下查找元素，默认为 document。
  * @returns 返回匹配到的 HTMLElement 实例。
  */
-export declare function $(selector: string | HTMLElement, dom?: HTMLElement | ShadowRoot | Document): NodeListOf<HTMLElement> | HTMLElement[];
+export declare function $(selector: string | HTMLElement, dom?: DocumentContext): NodeListOf<HTMLElement> | HTMLElement[];
+/**
+ * 创建一个 HTML 元素，支持通过标签名或 HTML 字符串创建。
+ * @param tag - 元素标签名或 HTML 字符串。
+ * @param option - 元素的属性、样式、文本内容等配置。
+ * @param ctx - 元素的父级文档上下文。
+ * @returns 创建的 HTML 元素。
+ */
+export declare function create(tag: string, option?: {
+    class?: FormatClassParam;
+    style?: FormatStyleParam;
+    textContent?: string;
+    innerHTML?: string;
+    outerHTML?: string;
+    [index: string]: any;
+}, ctx?: DocumentContext): HTMLElement;
 /**
  * 根据选择器获取匹配的第一个 DOM 元素。
  * @param selector - 选择器字符串或直接的 HTMLElement。
  * @param dom - 可选的父级 DOM 元素，默认为当前文档。
  * @returns 返回匹配的第一个 HTMLElement，如果没有找到则返回 undefined。
  */
-export declare function $one(selector: string | HTMLElement, dom?: HTMLElement | ShadowRoot | Document): HTMLElement;
+export declare function $one(selector: string | HTMLElement, dom?: DocumentContext): HTMLElement | undefined;
 /**
  * 为节点添加 class
  * @param {HTMLElement} elem 待添加 class 的节点
@@ -151,13 +169,13 @@ export declare function isMobile(): boolean;
  * @param classObj - 类名对象或数组
  * @returns 格式化后的类名字符串
  */
-export declare function formatClass(classObj: (boolean | string | undefined | null)[] | Record<string, boolean | string | undefined | null>): string;
+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: (string | undefined | null | "")[] | Record<string, string | undefined | null>): string;
+export declare function formatStyle(styleObj: FormatStyleParam): string;
 /**
  * 对指定的 HTML 元素应用显示过渡效果。
  * @param target - 要应用过渡效果的 HTML 元素。
@@ -181,3 +199,4 @@ export declare function startTransition(target: HTMLElement, properties: [string
  * @param finish - 过渡结束后可选的回调函数。
  */
 export declare function endTransition(target: HTMLElement, properties: [string, string][], finish?: () => void): void;
+export {};

package/lib/dom.js

@@ -1,12 +1,3 @@
-/**
- * web(浏览器端) DOM 文件操作
- * 现今不推荐在使用这种方式，现在开发前端的时候，推荐使用一些成熟的框架例如：React、Preact、Vue、Angular、Svelte、Ember、Knockout等
- * 在使用这些框架的时候额外的一些不可避免的 dom 操作时才使用这个工具；如果确实需要使用原生开发推荐使用 jquery 或者想要更精简的话可以使用 https://github.com/finom/bala 封装
- */
-/**
- * 根据选择器获取节点
- * @param {string} selector 选择器
- */
 export function elem(selector, dom) {
     if (typeof selector === "string") {
         return (dom || document).querySelectorAll(selector);
@@ -24,6 +15,58 @@ export function elem(selector, dom) {
 export function $(selector, dom) {
     return elem(selector, dom);
 }
+/**
+ * 创建一个 HTML 元素，支持通过标签名或 HTML 字符串创建。
+ * @param tag - 元素标签名或 HTML 字符串。
+ * @param option - 元素的属性、样式、文本内容等配置。
+ * @param ctx - 元素的父级文档上下文。
+ * @returns 创建的 HTML 元素。
+ */
+export function create(tag, option = {}, ctx) {
+    let $el;
+    if (tag.startsWith("<") && tag.endsWith(">")) {
+        const parser = new DOMParser();
+        const doc = parser.parseFromString(tag, "text/html");
+        $el = doc.body.firstElementChild;
+    }
+    else {
+        $el = document.createElement(tag);
+    }
+    if ($el) {
+        if (option) {
+            for (const key in option) {
+                const value = option[key];
+                if (key === "class") {
+                    $el.className = formatClass(value);
+                }
+                else if (key === "style") {
+                    $el.style.cssText = formatStyle(value);
+                }
+                else if (key === "textContent" && value) {
+                    $el.textContent = value;
+                }
+                else if (key === "innerHTML" && value) {
+                    $el.innerHTML = value;
+                }
+                else if (key === "outerHTML" && value) {
+                    $el.outerHTML = value;
+                }
+                else {
+                    if (value === true) {
+                        $el.setAttribute(key, "");
+                    }
+                    else if (typeof value === "string") {
+                        $el.setAttribute(key, value);
+                    }
+                }
+            }
+        }
+        if (ctx) {
+            ctx.appendChild($el);
+        }
+    }
+    return $el;
+}
 /**
  * 根据选择器获取匹配的第一个 DOM 元素。
  * @param selector - 选择器字符串或直接的 HTMLElement。
@@ -31,7 +74,8 @@ export function $(selector, dom) {
  * @returns 返回匹配的第一个 HTMLElement，如果没有找到则返回 undefined。
  */
 export function $one(selector, dom) {
-    return elem(selector, dom)[0];
+    const els = elem(selector, dom);
+    return els.length > 0 ? els[0] : undefined;
 }
 /**
  * 为节点添加 class
@@ -298,6 +342,9 @@ export function formatClass(classObj) {
             }
         }
     }
+    else if (typeof classObj === "string") {
+        classes = classObj;
+    }
     else {
         for (const key in classObj) {
             if (classObj[key]) {
@@ -322,6 +369,9 @@ export function formatStyle(styleObj) {
             }
         }
     }
+    else if (typeof styleObj === "string") {
+        styleStr = styleObj;
+    }
     else {
         for (const key in styleObj) {
             const value = styleObj[key];

package/package.json

@@ -68,7 +68,7 @@
     },
     "./*": "./lib/*"
   },
-  "version": "0.11.5",
+  "version": "0.12.1",
   "type": "module",
   "repository": {
     "type": "git",