ectrol 0.0.3 → 0.1.0

package/dist/index.d.mts

@@ -41,7 +41,6 @@ interface ISize {
 declare class ElementHandle {
   readonly contents: WebContents;
   readonly selector: string;
-  isNotFound: boolean;
   constructor(contents: WebContents, selector: string);
   /**
    * 生成在 renderer 端执行的查找脚本。
@@ -53,7 +52,9 @@ declare class ElementHandle {
   /**
    * 触发元素 mouseover 事件（不移动真实鼠标）。
    */
-  hover(): Promise<any>;
+  hover(options?: {
+    timeout?: number;
+  }): Promise<any>;
   /**
    * 点击
    * - 通过 WebContents.sendInputEvent 发送 mouseDown/mouseUp 事件
@@ -83,14 +84,23 @@ declare class ElementHandle {
   /**
    * 将复选框或单选按钮设为选中，并派发 change 事件。
    */
-  check(): Promise<any>;
+  check(options?: {
+    timeout?: number;
+  }): Promise<any>;
   /**
    * 填充输入框内容。
    * - 适用于 `<input>`、`<textarea>` 或 `contenteditable` 元素。
    * - 会触发 `input` 事件（冒泡）。
+   * - 支持自定义输入间隔, 'auto' 表示模拟自然输入节奏
+   * @example
+   * ```
+   * await element.fill('Hello, World!', { interval: 100 });
+   * ```
    */
   fill(value: string, options?: {
     timeout?: number;
+    interval?: number | 'auto';
+    append?: boolean;
   }): Promise<void>;
   /**
    * 在元素上发送按键事件。
@@ -124,55 +134,77 @@ declare class ElementHandle {
    * @param value 选项的值
    * @returns
    */
-  selectOption(value: string): Promise<any>;
+  selectOption(value: string, options?: {
+    timeout?: number;
+  }): Promise<any>;
   /**
    * 获取元素的 HTML 内容。
    */
-  innerHTML(): Promise<any>;
+  innerHTML(options?: {
+    timeout?: number;
+  }): Promise<any>;
   /**
    * 获取元素的文本内容。
    */
-  innerText(): Promise<any>;
+  innerText(options?: {
+    timeout?: number;
+  }): Promise<any>;
   /**
    * 获取元素的文本内容。
    * @returns 元素的文本内容
    */
-  textContent(): Promise<any>;
+  textContent(options?: {
+    timeout?: number;
+  }): Promise<any>;
   /**
    * 获取元素的输入值。
    * @returns 元素的输入值
    */
-  inputValue(): Promise<any>;
+  inputValue(options?: {
+    timeout?: number;
+  }): Promise<any>;
   /**
    * 获取元素的选中状态。
    * @returns 元素的选中状态
    */
-  isChecked(): Promise<any>;
+  isChecked(options?: {
+    timeout?: number;
+  }): Promise<any>;
   /**
    * 获取元素的禁用状态。
    * @returns 元素的禁用状态
    */
-  isDisabled(): Promise<any>;
+  isDisabled(options?: {
+    timeout?: number;
+  }): Promise<any>;
   /**
    * 获取元素的可见状态。
    * @returns 元素的可见状态
    */
-  isVisible(): Promise<any>;
+  isVisible(options?: {
+    timeout?: number;
+  }): Promise<any>;
   /**
    * 获取元素的可用状态。
    * @returns 元素的可用状态
    */
-  isEnabled(): Promise<any>;
+  isEnabled(options?: {
+    timeout?: number;
+  }): Promise<any>;
   /**
    * 获取元素的可编辑状态。
    * @returns 元素的可编辑状态
    */
-  isEditable(): Promise<any>;
+  isEditable(options?: {
+    timeout?: number;
+  }): Promise<any>;
   /**
    * 获取元素的隐藏状态。
    * @returns 元素的隐藏状态
    */
-  isHidden(): Promise<any>;
+  isHidden(options?: {
+    timeout?: number;
+  }): Promise<any>;
   /**
    * 选中元素的文本内容。
    */
@@ -237,6 +269,11 @@ declare class SessionStorage {
   removeItem(key: string): Promise<void>;
 }
 //#endregion
+//#region src/utils.d.ts
+declare function randomInRange(min: number, max: number, integer?: boolean): number;
+declare function getHumanTypingDelay(index: number, text: string): number;
+declare function sleep(ms: number): Promise<unknown>;
+//#endregion
 //#region src/index.d.ts
 /**
  * Ectrol
@@ -261,4 +298,4 @@ declare class Ectrol {
   $(selector: string): ElementHandle;
 }
 //#endregion
-export { Ectrol, Ectrol as default, ElementHandle, IBoundingClientRect, ISize, IVector2D, LocalStorage, SessionStorage };
+export { Ectrol, Ectrol as default, ElementHandle, IBoundingClientRect, ISize, IVector2D, LocalStorage, SessionStorage, getHumanTypingDelay, randomInRange, sleep };

package/dist/index.mjs

@@ -1,3 +1,25 @@
+//#region src/utils.ts
+function randomInRange(min, max, integer = false) {
+	if (min > max) [min, max] = [max, min];
+	const value = Math.random() * (max - min) + min;
+	return integer ? Math.floor(value) : value;
+}
+function getHumanTypingDelay(index, text) {
+	const char = text[index];
+	let delay = randomInRange(16, 100);
+	const progress = index / text.length;
+	if (progress < .15) delay *= 1.3;
+	else if (progress > .85) delay *= 1.25;
+	if (char === " ") delay += 16;
+	if (/[,.!?;:]/.test(char)) delay += randomInRange(16, 50);
+	if (Math.random() < .03) delay += randomInRange(100, 200);
+	return Math.max(40, Math.round(delay));
+}
+async function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+//#endregion
 //#region src/element.ts
 /**
 * ElementHandle
@@ -7,7 +29,6 @@
 * - 大多数 API 接受 `timeout`，轮询查找元素直到超时
 */
 var ElementHandle = class {
-	isNotFound = false;
 	constructor(contents, selector) {
 		this.contents = contents;
 		this.selector = selector;
@@ -20,104 +41,116 @@ var ElementHandle = class {
 	*/
 	_getElement(timeout = 0) {
 		return `
-     (()=>{
-        function getElement() {
-          const selector = "${this.selector}";
-
-          if (!selector) return null;
+        new Promise((resolve) => {
+          function getElement() {
+            const selector = "${this.selector}";
+            if (!selector) return null;
+
+            window.__ELECTROL__ = window.__ELECTROL__ || {};
+            if (window.__ELECTROL__[selector]) {
+              return window.__ELECTROL__[selector];
+            }
 
-          window.__ELECTROL__ = window.__ELECTROL__ || {};
-          if (window.__ELECTROL__[selector]) {
-            return window.__ELECTROL__[selector];
-          }
+            // 分层选择器，支持 iframe 穿越
+            const parts = selector.split('|>').map(s => s.trim());
+            if (!parts.length) return null;
 
-          // 分层选择器，支持 iframe 穿越
-          const parts = selector.split('|>').map(s => s.trim());
-          if (!parts.length) return null;
+            let currentDocument = document;
+            let offsetLeft = 0;
+            let offsetTop = 0;
+            let element = null;
 
-          let currentDocument = document;
-          let offsetLeft = 0;
-          let offsetTop = 0;
-          let element = null;
+            for (let i = 0; i < parts.length; i++) {
+              if (!currentDocument) return null;
 
-          for (let i = 0; i < parts.length; i++) {
-            if (!currentDocument) return null;
+              const part = parts[i];
+              // 在当前文档查找该层选择器
+              const el = currentDocument.querySelector(part);
 
-            const part = parts[i];
-            // 在当前文档查找该层选择器
-            const el = currentDocument.querySelector(part);
+              if (!el) {
+                console.warn('未找到元素:', part);
+                return null;
+              }
 
-            if (!el) {
-              console.warn('未找到元素:', part);
-              return null;
-            }
+              const rect = el.getBoundingClientRect();
 
-            const rect = el.getBoundingClientRect();
+              // 累加当前层级偏移
+              offsetLeft += rect.left;
+              offsetTop += rect.top;
 
-            // 累加当前层级偏移
-            offsetLeft += rect.left;
-            offsetTop += rect.top;
+              element = el;
 
-            element = el;
+              const isLast = i === parts.length - 1;
+              if (!isLast) {
+                if (el.tagName !== 'IFRAME') {
+                  console.warn('非 iframe 元素却尝试进入下一层:', part);
+                  return null;
+                }
 
-            const isLast = i === parts.length - 1;
-            if (!isLast) {
-              if (el.tagName !== 'IFRAME') {
-                console.warn('非 iframe 元素却尝试进入下一层:', part);
-                return null;
-              }
+                const nextDoc = el.contentDocument || el.contentWindow?.document;
+                if (!nextDoc) {
+                  console.warn('无法访问 iframe.contentDocument（可能跨域）');
+                  return null;
+                }
 
-              const nextDoc = el.contentDocument || el.contentWindow?.document;
-              if (!nextDoc) {
-                console.warn('无法访问 iframe.contentDocument（可能跨域）');
-                return null;
+                currentDocument = nextDoc;
               }
-
-              currentDocument = nextDoc;
             }
-          }
 
-          if (!element) return null;
+            if (!element) return null;
 
-          const finalRect = element.getBoundingClientRect();
+            const finalRect = element.getBoundingClientRect();
 
-          // 缓存元素
-          // 缓存以避免重复查找
-          window.__ELECTROL__[selector] = {
-            element,
-            rect: new DOMRect(
-              offsetLeft,
-              offsetTop,
-              finalRect.width,
-              finalRect.height
-            )
-          };
+            // 缓存元素
+            // 缓存以避免重复查找
+            window.__ELECTROL__[selector] = {
+              element,
+              rect: new DOMRect(
+                offsetLeft,
+                offsetTop,
+                finalRect.width,
+                finalRect.height
+              )
+            };
 
-          return window.__ELECTROL__[selector]
-        }
+            return window.__ELECTROL__[selector]
+          }
 
-        const timeout = ${timeout}
+          const timeout = ${timeout}
 
-        if(timeout <= 0) {
-          return getElement();
-        }
+          // 轮询查找元素
+          const interval = setInterval(() => {
+            const element = getElement();
+            if (element) {
+              clearInterval(interval);
+              clearTimeout(timeoutId);
+              resolve(element);
+            }
+          }, 100);
+
+          // 超时处理
+          const timeoutId = setTimeout(() => {
+            clearInterval(interval);
+            resolve(null);
+          }, timeout);
 
-        const startTime = Date.now()
-        while (Date.now() - startTime < timeout) {
           const element = getElement();
-          if (element) return element;
-        }
-        return null;
-      })()
+
+          if (element) {
+            clearInterval(interval);
+            clearTimeout(timeoutId);
+            resolve(element);
+          }
+        })
     `;
 	}
 	/**
 	* 触发元素 mouseover 事件（不移动真实鼠标）。
 	*/
-	hover() {
+	hover(options) {
 		return this.contents.executeJavaScript(`
-      (function() {
-        const target = ${this._getElement()};
+      (async () => {
+        const target = await ${this._getElement(options?.timeout)};
         if (!target) return null;
 
         const event = new MouseEvent('mouseover', {
@@ -147,7 +180,7 @@ var ElementHandle = class {
 				button: options?.button || "left",
 				clickCount: 1
 			});
-			await new Promise((resolve) => setTimeout(resolve, options?.delay || 10));
+			await sleep(options?.delay || 10);
 			this.contents.sendInputEvent({
 				type: "mouseUp",
 				x: rect.centerX,
@@ -180,10 +213,10 @@ var ElementHandle = class {
 	/**
 	* 将复选框或单选按钮设为选中，并派发 change 事件。
 	*/
-	check() {
+	check(options) {
 		return this.contents.executeJavaScript(`
-      (function() {
-        const target = ${this._getElement()};
+      (async () => {
+        const target = await ${this._getElement(options?.timeout)};
         if (!target) return null;
 
         // 验证输入框是否是复选框或单选按钮
@@ -198,22 +231,32 @@ var ElementHandle = class {
 	* 填充输入框内容。
 	* - 适用于 `<input>`、`<textarea>` 或 `contenteditable` 元素。
 	* - 会触发 `input` 事件（冒泡）。
+	* - 支持自定义输入间隔, 'auto' 表示模拟自然输入节奏
+	* @example
+	* ```
+	* await element.fill('Hello, World!', { interval: 100 });
+	* ```
 	*/
 	async fill(value, options) {
-		await this.contents.executeJavaScript(`
-      (function() {
-        const target = ${this._getElement(options?.timeout)};
-        if (!target) return null;
-
-        // 验证输入框是否是文本类型
-        if (target.element.tagName !== 'INPUT' && target.element.tagName !== 'TEXTAREA' && !target.element.isContentEditable) return null;
-
-        target.element.focus();
-
-        target.element.value = ${JSON.stringify(value)};
-        target.element.dispatchEvent(new Event('input', { bubbles: true }));
+		await this.focus({ timeout: options?.timeout });
+		let interval;
+		if (typeof options?.interval === "number") interval = options?.interval;
+		if (!options?.append) await this.contents.executeJavaScript(`
+      (async () => {
+        const target = await ${this._getElement(options?.timeout)};
+        if (target && target.element) {
+          if (target.element.tagName !== 'INPUT' && target.element.tagName !== 'TEXTAREA' && !target.element.isContentEditable) return null;
+          target.element.value = "";
+        }
       })()
     `);
+		for (let index = 0; index < value.length; index++) {
+			await sleep(interval || getHumanTypingDelay(index, value));
+			this.contents.sendInputEvent({
+				type: "char",
+				keyCode: value[index]
+			});
+		}
 	}
 	/**
 	* 在元素上发送按键事件。
@@ -230,7 +273,7 @@ var ElementHandle = class {
 			type: "keyDown",
 			keyCode: key$1
 		});
-		await new Promise((resolve) => setTimeout(resolve, options?.delay || 10));
+		await sleep(options?.delay || 10);
 		for (const key$1 of keys) this.contents.sendInputEvent({
 			type: "keyUp",
 			keyCode: key$1
@@ -241,8 +284,8 @@ var ElementHandle = class {
 	*/
 	async focus(options) {
 		return this.contents.executeJavaScript(`
-      (function() {
-        const target = ${this._getElement(options?.timeout)};
+      (async () => {
+        const target = await ${this._getElement(options?.timeout)};
         if (!target) return null;
 
         // 验证输入框是否是文本类型
@@ -263,11 +306,9 @@ var ElementHandle = class {
 	* - 返回扩展的 DOMRect 信息并包含元素中心点坐标。
 	*/
 	getBoundingClientRect(timeout = 0) {
-		if (this.isNotFound) return Promise.resolve(null);
 		return this.contents.executeJavaScript(`
-      (function() {
-        const target = ${this._getElement(timeout)};
-
+      (async () => {
+        const target = await ${this._getElement(timeout)};
         if (!target) return null;
 
         const rect = target.rect;
@@ -291,10 +332,10 @@ var ElementHandle = class {
 	* @param value 选项的值
 	* @returns
 	*/
-	async selectOption(value) {
+	async selectOption(value, options) {
 		return this.contents.executeJavaScript(`
-      (function() {
-        const target = ${this._getElement()};
+      (async () => {
+        const target = await ${this._getElement(options?.timeout)};
         if (!target) return null;
 
         // 验证元素是否为选择框
@@ -308,10 +349,10 @@ var ElementHandle = class {
 	/**
 	* 获取元素的 HTML 内容。
 	*/
-	async innerHTML() {
+	async innerHTML(options) {
 		return this.contents.executeJavaScript(`
-      (function() {
-        const target = ${this._getElement()};
+      (async () => {
+        const target = await ${this._getElement(options?.timeout)};
         if (!target) return null;
 
         return target.element.innerHTML;
@@ -321,10 +362,10 @@ var ElementHandle = class {
 	/**
 	* 获取元素的文本内容。
 	*/
-	async innerText() {
+	async innerText(options) {
 		return this.contents.executeJavaScript(`
-      (function() {
-        const target = ${this._getElement()};
+      (async () => {
+        const target = await ${this._getElement(options?.timeout)};
         if (!target) return null;
 
         return target.element.innerText;
@@ -335,10 +376,10 @@ var ElementHandle = class {
 	* 获取元素的文本内容。
 	* @returns 元素的文本内容
 	*/
-	async textContent() {
+	async textContent(options) {
 		return this.contents.executeJavaScript(`
-      (function() {
-        const target = ${this._getElement()};
+      (async () => {
+        const target = await ${this._getElement(options?.timeout)};
         if (!target) return null;
 
         return target.element.textContent;
@@ -349,10 +390,10 @@ var ElementHandle = class {
 	* 获取元素的输入值。
 	* @returns 元素的输入值
 	*/
-	async inputValue() {
+	async inputValue(options) {
 		return this.contents.executeJavaScript(`
-      (function() {
-        const target = ${this._getElement()};
+      (async () => {
+        const target = await ${this._getElement(options?.timeout)};
         if (!target) return null;
 
         // 验证输入框是否是文本类型
@@ -366,10 +407,10 @@ var ElementHandle = class {
 	* 获取元素的选中状态。
 	* @returns 元素的选中状态
 	*/
-	async isChecked() {
+	async isChecked(options) {
 		return this.contents.executeJavaScript(`
-      (function() {
-        const target = ${this._getElement()};
+      (async () => {
+        const target = await ${this._getElement(options?.timeout)};
         if (!target) return null;
 
         // 验证输入框是否是复选框或单选框
@@ -383,10 +424,10 @@ var ElementHandle = class {
 	* 获取元素的禁用状态。
 	* @returns 元素的禁用状态
 	*/
-	async isDisabled() {
+	async isDisabled(options) {
 		return this.contents.executeJavaScript(`
-      (function() {
-        const target = ${this._getElement()};
+      (async () => {
+        const target = await ${this._getElement(options?.timeout)};
         if (!target) return null;
 
         return target.element.disabled;
@@ -397,10 +438,10 @@ var ElementHandle = class {
 	* 获取元素的可见状态。
 	* @returns 元素的可见状态
 	*/
-	async isVisible() {
+	async isVisible(options) {
 		return this.contents.executeJavaScript(`
-      (function() {
-        const target = ${this._getElement()};
+      (async () => {
+        const target = await ${this._getElement(options?.timeout)};
         if (!target) return null;
 
         return target.element.offsetParent !== null;
@@ -411,10 +452,10 @@ var ElementHandle = class {
 	* 获取元素的可用状态。
 	* @returns 元素的可用状态
 	*/
-	async isEnabled() {
+	async isEnabled(options) {
 		return this.contents.executeJavaScript(`
-      (function() {
-        const target = ${this._getElement()};
+      (async () => {
+        const target = await ${this._getElement(options?.timeout)};
         if (!target) return null;
 
         return !target.element.disabled;
@@ -425,10 +466,10 @@ var ElementHandle = class {
 	* 获取元素的可编辑状态。
 	* @returns 元素的可编辑状态
 	*/
-	async isEditable() {
+	async isEditable(options) {
 		return this.contents.executeJavaScript(`
-      (function() {
-        const target = ${this._getElement()};
+      (async () => {
+        const target = await ${this._getElement(options?.timeout)};
         if (!target) return null;
 
         return target.element.isContentEditable;
@@ -439,10 +480,10 @@ var ElementHandle = class {
 	* 获取元素的隐藏状态。
 	* @returns 元素的隐藏状态
 	*/
-	async isHidden() {
+	async isHidden(options) {
 		return this.contents.executeJavaScript(`
-      (function() {
-        const target = ${this._getElement()};
+      (async () => {
+        const target = await ${this._getElement(options?.timeout)};
         if (!target) return null;
 
         return target.element.offsetParent === null;
@@ -454,8 +495,8 @@ var ElementHandle = class {
 	*/
 	async selectText(options) {
 		return this.contents.executeJavaScript(`
-      (function() {
-        const target = ${this._getElement(options.timeout)};
+      (async () => {
+        const target = await ${this._getElement(options.timeout)};
         if (!target) return null;
 
         // 选中元素的文本内容
@@ -474,8 +515,8 @@ var ElementHandle = class {
 	*/
 	async uncheck(options) {
 		return this.contents.executeJavaScript(`
-      (function() {
-        const target = ${this._getElement(options?.timeout)};
+      (async () => {
+        const target = await ${this._getElement(options?.timeout)};
         if (!target) return null;
 
         // 验证输入框是否是复选框或单选框
@@ -587,4 +628,4 @@ var Ectrol = class {
 var src_default = Ectrol;
 
 //#endregion
-export { Ectrol, ElementHandle, LocalStorage, SessionStorage, src_default as default };
+export { Ectrol, ElementHandle, LocalStorage, SessionStorage, src_default as default, getHumanTypingDelay, randomInRange, sleep };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ectrol",
   "type": "module",
-  "version": "0.0.3",
+  "version": "0.1.0",
   "description": "一个基于 Electron WebContents 的轻量级自动化助手，用于在你的应用内对网页内容进行交互（点击、输入、聚焦、键盘事件等）。",
   "author": "Cee Vee X <ceeveex@hotmail.com>",
   "license": "MIT",