@whitesev/domutils 1.8.4 → 1.8.6

package/dist/types/src/ElementWait.d.ts

@@ -12,7 +12,7 @@ declare class ElementWait extends ElementSelector {
      * @param timeout 超时时间，默认0
      * @param parent （可选）父元素，默认document
      * @example
-     * Utils.wait(()=> {
+     * DOMUtils.wait(()=> {
      *   let $test = document.querySelector("#test");
      *   return {
      *     success: $test !== null,
@@ -40,26 +40,48 @@ declare class ElementWait extends ElementSelector {
          */
         data: T;
     }, timeout?: number, parent?: Node | Element | Document | HTMLElement): Promise<T | null>;
+    /**
+     * 等待元素出现
+     * @param selectorFn 获取元素的函数
+     * @example
+     * DOMUtils.waitNode(()=>document.querySelector("div")).then( $div =>{
+     *  console.log($div); // $div => HTMLDivELement
+     * })
+     */
+    waitNode<K>(selectorFn: () => K | null | undefined): Promise<K>;
     /**
      * 等待元素出现
      * @param selectorFn 获取元素的函数
      * @param timeout 超时时间，默认0
      * @example
-     * Utils.waitNode(()=>document.querySelector("div"), 1000).then( $div =>{
+     * DOMUtils.waitNode(()=>document.querySelector("div"), 1000).then( $div =>{
      *  console.log($div); // $div => HTMLDivELement | null
      * })
      */
-    waitNode<K>(selectorFn: () => K | null | undefined): Promise<K>;
     waitNode<K>(selectorFn: () => K | null | undefined, timeout: number): Promise<K | null | undefined>;
+    /**
+     * 等待元素出现
+     * @param selectorFn 获取元素的函数
+     * @param parent 父元素
+     * @param timeout 超时时间，默认0
+     * @example
+     * DOMUtils.waitNode(()=>document.querySelector("div"), document).then( $div =>{
+     *  console.log($div); // $div => HTMLDivELement
+     * })
+     * DOMUtils.waitNode(()=>document.querySelector("div"), document, 1000).then( $div =>{
+     *  console.log($div); // $div => HTMLDivELement | null
+     * })
+     */
+    waitNode<K>(selectorFn: () => K | null | undefined, parent: Node | Element | Document | HTMLElement, timeout?: number): Promise<K | null | undefined>;
     /**
      * 等待元素出现
      * @param selector CSS选择器
      * @param parent （可选）父元素，默认document
      * @example
-     * Utils.waitNode("div").then( $div =>{
+     * DOMUtils.waitNode("div").then( $div =>{
      *  console.log($div); // div => HTMLDivELement
      * })
-     * Utils.waitNode("div", document).then( $div =>{
+     * DOMUtils.waitNode("div", document).then( $div =>{
      *  console.log($div); // div => HTMLDivELement
      * })
      */
@@ -70,10 +92,10 @@ declare class ElementWait extends ElementSelector {
      * @param selectorList CSS选择器数组
      * @param parent （可选）父元素，默认document
      * @example
-     * Utils.waitNode(["div"]).then( ([$div]) =>{
+     * DOMUtils.waitNode(["div"]).then( ([$div]) =>{
      *  console.log($div); // div => HTMLDivELement[]
      * })
-     * Utils.waitNode(["div"], document).then( ([$div]) =>{
+     * DOMUtils.waitNode(["div"], document).then( ([$div]) =>{
      *  console.log($div); // div => HTMLDivELement[]
      * })
      */
@@ -85,7 +107,7 @@ declare class ElementWait extends ElementSelector {
      * @param parent 父元素，默认document
      * @param timeout 超时时间，默认0
      * @example
-     * Utils.waitNode("div", document, 1000).then( $div =>{
+     * DOMUtils.waitNode("div", document, 1000).then( $div =>{
      *  console.log($div); // $div => HTMLDivELement | null
      * })
      */
@@ -97,7 +119,7 @@ declare class ElementWait extends ElementSelector {
      * @param parent 父元素，默认document
      * @param timeout 超时时间，默认0
      * @example
-     * Utils.waitNode(["div"], document, 1000).then( ([$div]) =>{
+     * DOMUtils.waitNode(["div"], document, 1000).then( ([$div]) =>{
      *  console.log($div); // $div => HTMLDivELement[] | null
      * })
      */
@@ -108,7 +130,7 @@ declare class ElementWait extends ElementSelector {
      * @param selector CSS选择器
      * @param timeout 超时时间，默认0
      * @example
-     * Utils.waitNode("div", 1000).then( $div =>{
+     * DOMUtils.waitNode("div", 1000).then( $div =>{
      *  console.log($div); // $div => HTMLDivELement | null
      * })
      */
@@ -119,7 +141,7 @@ declare class ElementWait extends ElementSelector {
      * @param selectorList CSS选择器数组
      * @param timeout 超时时间，默认0
      * @example
-     * Utils.waitNode(["div"], 1000).then( [$div] =>{
+     * DOMUtils.waitNode(["div"], 1000).then( [$div] =>{
      *  console.log($div); // $div => HTMLDivELement[] | null
      * })
      */
@@ -130,10 +152,10 @@ declare class ElementWait extends ElementSelector {
      * @param selectorList CSS选择器数组
      * @param parent （可选）监听的父元素
      * @example
-     * Utils.waitAnyNode(["div","div"]).then( $div =>{
+     * DOMUtils.waitAnyNode(["div","div"]).then( $div =>{
      *  console.log($div); // $div => HTMLDivELement 这里是第一个
      * })
-     * Utils.waitAnyNode(["a","div"], document).then( $a =>{
+     * DOMUtils.waitAnyNode(["a","div"], document).then( $a =>{
      *  console.log($a); // $a => HTMLAnchorElement 这里是第一个
      * })
      */
@@ -145,7 +167,7 @@ declare class ElementWait extends ElementSelector {
      * @param parent 父元素，默认document
      * @param timeout 超时时间，默认0
      * @example
-     * Utils.waitAnyNode(["div","div"], document, 10000).then( $div =>{
+     * DOMUtils.waitAnyNode(["div","div"], document, 10000).then( $div =>{
      *  console.log($div); // $div => HTMLDivELement | null
      * })
      */
@@ -156,7 +178,7 @@ declare class ElementWait extends ElementSelector {
      * @param selectorList CSS选择器数组
      * @param timeout 超时时间，默认0
      * @example
-     * Utils.waitAnyNode(["div","div"], 10000).then( $div =>{
+     * DOMUtils.waitAnyNode(["div","div"], 10000).then( $div =>{
      *  console.log($div); // $div => HTMLDivELement | null
      * })
      */
@@ -167,10 +189,10 @@ declare class ElementWait extends ElementSelector {
      * @param selector CSS选择器
      * @param parent （可选）监听的父元素
      * @example
-     * Utils.waitNodeList("div").then( $result =>{
+     * DOMUtils.waitNodeList("div").then( $result =>{
      *  console.log($result); // $result => NodeListOf<HTMLDivElement>
      * })
-     * Utils.waitNodeList("div", document).then( $result =>{
+     * DOMUtils.waitNodeList("div", document).then( $result =>{
      *  console.log($result); // $result => NodeListOf<HTMLDivElement>
      * })
      */
@@ -181,10 +203,10 @@ declare class ElementWait extends ElementSelector {
      * @param selectorList CSS选择器数组
      * @param parent （可选）监听的父元素
      * @example
-     * Utils.waitNodeList(["div"]).then( $result =>{
+     * DOMUtils.waitNodeList(["div"]).then( $result =>{
      *  console.log($result); // $result => NodeListOf<HTMLDivElement>[]
      * })
-     * Utils.waitNodeList(["div"], document).then( $result =>{
+     * DOMUtils.waitNodeList(["div"], document).then( $result =>{
      *  console.log($result); // $result => NodeListOf<HTMLDivElement>[]
      * })
      */
@@ -196,7 +218,7 @@ declare class ElementWait extends ElementSelector {
      * @param parent 监听的父元素
      * @param timeout 超时时间，默认0
      * @example
-     * Utils.waitNodeList("div", document, 10000).then( $result =>{
+     * DOMUtils.waitNodeList("div", document, 10000).then( $result =>{
      *  console.log($result); // $result => NodeListOf<HTMLDivElement> | null
      * })
      */
@@ -208,7 +230,7 @@ declare class ElementWait extends ElementSelector {
      * @param parent 监听的父元素
      * @param timeout 超时时间，默认0
      * @example
-     * Utils.waitNodeList(["div"], document, 10000).then( $result =>{
+     * DOMUtils.waitNodeList(["div"], document, 10000).then( $result =>{
      *  console.log($result); // $result => NodeListOf<HTMLDivElement>[] | null
      * })
      */
@@ -219,7 +241,7 @@ declare class ElementWait extends ElementSelector {
      * @param selector CSS选择器数组
      * @param timeout 超时时间，默认0
      * @example
-     * Utils.waitNodeList("div", 10000).then( $result =>{
+     * DOMUtils.waitNodeList("div", 10000).then( $result =>{
      *  console.log($result); // $result => NodeListOf<HTMLDivElement> | null
      * })
      */
@@ -230,7 +252,7 @@ declare class ElementWait extends ElementSelector {
      * @param selectorList CSS选择器数组
      * @param timeout 超时时间，默认0
      * @example
-     * Utils.waitNodeList(["div"], 10000).then( $result =>{
+     * DOMUtils.waitNodeList(["div"], 10000).then( $result =>{
      *  console.log($result); // $result => NodeListOf<HTMLDivElement>[] | null
      * })
      */
@@ -241,10 +263,10 @@ declare class ElementWait extends ElementSelector {
      * @param selectorList CSS选择器数组
      * @param parent （可选）监听的父元素
      * @example
-     * Utils.waitAnyNodeList(["div","a"]).then( $result =>{
+     * DOMUtils.waitAnyNodeList(["div","a"]).then( $result =>{
      *  console.log($result); // $result => NodeListOf<HTMLDivElement>
      * })
-     * Utils.waitAnyNodeList(["div","a"], document).then( $result =>{
+     * DOMUtils.waitAnyNodeList(["div","a"], document).then( $result =>{
      *  console.log($result); // $result => NodeListOf<HTMLDivElement>
      * })
      */
@@ -256,7 +278,7 @@ declare class ElementWait extends ElementSelector {
      * @param parent 父元素，默认document
      * @param timeout 超时时间，默认0
      * @example
-     * Utils.waitAnyNodeList(["div","a"], document, 10000).then( $result =>{
+     * DOMUtils.waitAnyNodeList(["div","a"], document, 10000).then( $result =>{
      *  console.log($result); // $result => NodeListOf<HTMLDivElement> | null
      * })
      */
@@ -267,7 +289,7 @@ declare class ElementWait extends ElementSelector {
      * @param selectorList CSS选择器数组
      * @param timeout 超时时间，默认0
      * @example
-     * Utils.waitAnyNodeList(["div","div"], 10000).then( $result =>{
+     * DOMUtils.waitAnyNodeList(["div","div"], 10000).then( $result =>{
      *  console.log($result); // $result => NodeListOf<HTMLDivElement> | null
      * })
      */

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@whitesev/domutils",
-  "version": "1.8.4",
+  "version": "1.8.6",
   "type": "module",
   "description": "适合在浏览器中操作DOM的常用工具类",
   "main": "dist/index.cjs.js",
@@ -52,7 +52,7 @@
     "rollup-plugin-clear": "^2.0.7",
     "tslib": "^2.8.1",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.50.0"
+    "typescript-eslint": "^8.50.1"
   },
   "scripts": {
     "lint": "eslint .",

package/src/ElementSelector.ts

@@ -9,11 +9,17 @@ class ElementSelector {
   /**
    * 选择器，可使用以下的额外语法
    *
-   * + :contains([text]) 作用: 找到包含指定文本内容的指定元素
-   * + :empty 作用:找到既没有文本内容也没有子元素的指定元素
-   * + :regexp([text]) 作用: 找到符合正则表达式的内容的指定元素
+   *
+   * **前置语法**
+   *
+   * + `xpath:` 作用：执行xpath语法，会对当前js环境下的`Document`进行节点获取
+   *
+   * **末尾语法**
+   * + `:contains([text])` 作用: 找到包含指定文本内容的指定元素
+   * + `:empty` 作用:找到既没有文本内容也没有子元素的指定元素
+   * + `:regexp([text])` 作用: 找到符合正则表达式的内容的指定元素
    * @param selector 选择器
-   * @param parent 指定父元素
+   * @param parent 指定父元素，默认为`document`
    * @example
    * DOMUtils.selector("div:contains('测试')")
    * > div.xxx
@@ -41,11 +47,16 @@ class ElementSelector {
   /**
    * 选择器，可使用以下的额外语法
    *
-   * + :contains([text]) 作用: 找到包含指定文本内容的指定元素
-   * + :empty 作用:找到既没有文本内容也没有子元素的指定元素
-   * + :regexp([text]) 作用: 找到符合正则表达式的内容的指定元素
+   * **前置语法**
+   *
+   * + `xpath:` 作用：执行xpath语法，会对当前js环境下的`Document`进行节点获取
+   *
+   * **末尾语法**
+   * + `:contains([text])` 作用: 找到包含指定文本内容的指定元素
+   * + `:empty` 作用:找到既没有文本内容也没有子元素的指定元素
+   * + `:regexp([text])` 作用: 找到符合正则表达式的内容的指定元素
    * @param selector 选择器
-   * @param parent 指定父元素
+   * @param parent 指定父元素，默认为`document`
    * @example
    * DOMUtils.selectorAll("div:contains('测试')")
    * > [div.xxx]
@@ -74,7 +85,23 @@ class ElementSelector {
     const context = this;
     parent = parent || context.windowApi.document;
     selector = selector.trim();
-    if (selector.match(/[^\s]{1}:empty$/gi)) {
+    if (selector.startsWith("xpath:")) {
+      selector = selector.replace(/^xpath:/i, "");
+      const xpathResult = context.windowApi.document.evaluate(
+        selector,
+        parent,
+        null,
+        XPathResult.ORDERED_NODE_ITERATOR_TYPE,
+        null
+      );
+      const result: E[] = [];
+      let iterateNext = xpathResult.iterateNext();
+      while (iterateNext) {
+        result.push(iterateNext as E);
+        iterateNext = xpathResult.iterateNext();
+      }
+      return result;
+    } else if (selector.match(/[^\s]{1}:empty$/gi)) {
       // empty 语法
       selector = selector.replace(/:empty$/gi, "");
       return Array.from(parent.querySelectorAll<E>(selector)).filter(($ele) => {