feat(android): add hideKeyboardStrategy option to AndroidDevice and implement hideKeyboard method (#1037)

* feat(android): add hideKeyboardStrategy option to AndroidDevice and implement hideKeyboard method

* feat(android): enhance keyboard handling with autoDismissKeyboard and hideKeyboardStrategy options in AndroidDevice tests

* fix(android): rename hideKeyboardStrategy to keyboardDismissStrategy for consistency in AndroidDevice implementation and documentation

Author: quanru

apps/site/docs/en/integrate-with-android.mdx

@@ -107,6 +107,7 @@ The AndroidDevice constructor supports the following parameters:
 - `deviceId: string` - The device id
 - `opts?: AndroidDeviceOpt` - Optional, the options for the AndroidDevice
   - `autoDismissKeyboard?: boolean` - Optional, whether to dismiss the keyboard after inputting. (Default: true)
+  - `keyboardDismissStrategy?: 'esc-first' | 'back-first'` - Optional, the strategy to dismiss the keyboard. 'esc-first' tries ESC key first, then back key if needed. 'back-first' tries back key first, then ESC key if needed. (Default: 'esc-first')
   - `androidAdbPath?: string` - Optional, the path to the adb executable.
   - `remoteAdbHost?: string` - Optional, the remote adb host.
   - `remoteAdbPort?: number` - Optional, the remote adb port.

apps/site/docs/zh/integrate-with-android.mdx

@@ -107,6 +107,7 @@ AndroidDevice 的构造函数支持以下参数：
 - `deviceId: string` - 设备 id
 - `opts?: AndroidDeviceOpt` - 可选参数，用于初始化 AndroidDevice 的配置
   - `autoDismissKeyboard?: boolean` - 可选参数，是否在输入文本后自动关闭键盘。默认值为 true。
+  - `keyboardDismissStrategy?: 'esc-first' | 'back-first'` - 可选参数，关闭键盘的策略。'esc-first' 优先尝试 ESC 键，如果键盘仍存在则尝试返回键。'back-first' 优先尝试返回键，如果键盘仍存在则尝试 ESC 键。默认值为 'esc-first'。
   - `androidAdbPath?: string` - 可选参数，用于指定 adb 可执行文件的路径。
   - `remoteAdbHost?: string` - 可选参数，用于指定远程 adb 主机。
   - `remoteAdbPort?: number` - 可选参数，用于指定远程 adb 端口。

packages/android/src/page/index.ts

@@ -685,7 +685,7 @@ ${Object.keys(size)
     }
 
     if (isAutoDismissKeyboard === true) {
-      await adb.hideKeyboard();
+      await this.hideKeyboard(options);
     }
   }
 
@@ -925,4 +925,66 @@ ${Object.keys(size)
   async getElementInfoByXpath(xpath: string): Promise<ElementInfo> {
     throw new Error('Not implemented');
   }
+
+  async hideKeyboard(
+    options?: AndroidDeviceInputOpt,
+    timeoutMs = 1000,
+  ): Promise<boolean> {
+    const adb = await this.getAdb();
+    const keyboardDismissStrategy =
+      options?.keyboardDismissStrategy ??
+      this.options?.keyboardDismissStrategy ??
+      'esc-first';
+
+    // Check if keyboard is shown
+    const keyboardStatus = await adb.isSoftKeyboardPresent();
+    const isKeyboardShown =
+      typeof keyboardStatus === 'boolean'
+        ? keyboardStatus
+        : keyboardStatus?.isKeyboardShown;
+
+    if (!isKeyboardShown) {
+      debugPage('Keyboard has no UI; no closing necessary');
+      return false;
+    }
+
+    // Determine key codes order based on strategy
+    const keyCodes =
+      keyboardDismissStrategy === 'back-first'
+        ? [4, 111] // KEYCODE_BACK, KEYCODE_ESCAPE
+        : [111, 4]; // KEYCODE_ESCAPE, KEYCODE_BACK
+
+    // Try each key code with waiting
+    for (const keyCode of keyCodes) {
+      await adb.keyevent(keyCode);
+
+      // Wait for keyboard to be hidden with timeout
+      const startTime = Date.now();
+      const intervalMs = 100;
+
+      while (Date.now() - startTime < timeoutMs) {
+        await sleep(intervalMs);
+
+        const currentStatus = await adb.isSoftKeyboardPresent();
+        const isStillShown =
+          typeof currentStatus === 'boolean'
+            ? currentStatus
+            : currentStatus?.isKeyboardShown;
+
+        if (!isStillShown) {
+          debugPage(`Keyboard hidden successfully with keycode ${keyCode}`);
+          return true;
+        }
+      }
+
+      debugPage(
+        `Keyboard still shown after keycode ${keyCode}, trying next key`,
+      );
+    }
+
+    console.warn(
+      'Warning: Failed to hide the software keyboard after trying both ESC and BACK keys',
+    );
+    return false;
+  }
 }