跳到主要内容

AndroidDevice

AndroidDevice 表示一个已连接的设备，可以是真实硬件，也可以是模拟器。可以通过 android.devices() 获取设备实例。

方法​

close​

新增于: v1.9 androidDevice.close

断开与设备的连接。

用法

await androidDevice.close();

返回值

drag​

新增于: v1.9 androidDevice.drag

拖动由 selector 定义的小部件到 dest 点。

用法

await androidDevice.drag(selector, dest);
await androidDevice.drag(selector, dest, options);

参数

  • selector [AndroidSelector]#

    要拖动的选择器。

  • dest Object#

    拖动到的目标点。

  • options Object (可选)

    • speed number (可选)#

      拖动的可选速度，单位为像素/秒。

    • timeout number (可选)#

      最大超时时间（毫秒），默认为 30 秒，传递 0 表示禁用超时。默认值可通过 androidDevice.setDefaultTimeout() 方法更改。

返回值

fill​

新增于: v1.9 androidDevice.fill

将 text 填充到指定 selector 的输入框中。

用法

await androidDevice.fill(selector, text);
await androidDevice.fill(selector, text, options);

参数

  • selector [AndroidSelector]#

    要填充的选择器。

  • text string#

    要填入输入框的文本内容。

  • options Object (可选)

返回值

fling​

新增于: v1.9 androidDevice.fling

以指定 direction 方向快速滑动由 selector 定义的小部件。

用法

await androidDevice.fling(selector, direction);
await androidDevice.fling(selector, direction, options);

参数

  • selector [AndroidSelector]#

    要滑动的选择器。

  • direction "down" | "up" | "left" | "right"#

    滑动方向。

  • options Object (可选)

    • speed number (可选)#

      滑动的可选速度，单位为像素/秒。

    • timeout number (可选)#

      最大超时时间（毫秒），默认为 30 秒，传递 0 表示禁用超时。默认值可通过 androidDevice.setDefaultTimeout() 方法更改。

返回值

info​

新增于: v1.9 androidDevice.info

返回由 selector 定义的小部件的信息。

用法

await androidDevice.info(selector);

参数

  • selector [AndroidSelector]#

    要获取信息的选择器。

返回值

installApk​

新增于: v1.9 androidDevice.installApk

在设备上安装 apk 文件。

用法

await androidDevice.installApk(file);
await androidDevice.installApk(file, options);

参数

  • file string | Buffer#

    apk 文件的路径，或 apk 文件内容。

  • options Object (可选)

    • args Array<string> (可选)#

      传递给 shell:cmd package install 调用的可选参数。默认为 -r -t -S。

返回值

launchBrowser​

新增于: v1.9 androidDevice.launchBrowser

在设备上启动 Chrome 浏览器，并返回其持久化上下文。

用法

await androidDevice.launchBrowser();
await androidDevice.launchBrowser(options);

参数

  • options Object (可选)

    • acceptDownloads boolean (可选)#

      是否自动下载所有附件。默认为 true，即所有下载都会被接受。

    • args Array<string> (可选) 新增于: v1.29#

      注意

      自定义浏览器参数需谨慎使用，部分参数可能会影响 Playwright 的功能。

      传递给浏览器实例的额外参数。Chromium 参数列表可参考这里。

    • baseURL string (可选)#

      在使用 page.goto()、page.route()、page.waitForURL()、page.waitForRequest() 或 page.waitForResponse() 时，会通过 URL() 构造函数来拼接对应的 URL。默认未设置。示例：

      • baseURL: http://localhost:3000，跳转到 /bar.html，结果为 http://localhost:3000/bar.html
      • baseURL: http://localhost:3000/foo/，跳转到 ./bar.html，结果为 http://localhost:3000/foo/bar.html
      • baseURL: http://localhost:3000/foo（无斜杠），跳转到 ./bar.html，结果为 http://localhost:3000/bar.html

    • bypassCSP boolean (可选)#

      是否绕过页面的 Content-Security-Policy。默认为 false。

    • colorScheme null | "light" | "dark" | "no-preference" (可选)#

      模拟 prefers-colors-scheme 媒体特性，支持的值有 'light' 和 'dark'。更多详情见 page.emulateMedia()。传递 null 可重置为系统默认。默认为 'light'。

    • contrast null | "no-preference" | "more" (可选)#

      模拟 'prefers-contrast' 媒体特性，支持的值有 'no-preference'、'more'。更多详情见 page.emulateMedia()。传递 null 可重置为系统默认。默认为 'no-preference'。

    • deviceScaleFactor number (可选)#

      指定设备像素比（可理解为 dpr）。默认为 1。了解更多关于设备像素比模拟。

    • extraHTTPHeaders Object<string, string> (可选)#

      包含每个请求要发送的额外 HTTP 头的对象。默认为无。

    • forcedColors null | "active" | "none" (可选)#

      模拟 'forced-colors' 媒体特性，支持的值有 'active'、'none'。更多详情见 page.emulateMedia()。传递 null 可重置为系统默认。默认为 'none'。

    • geolocation Object (可选)#

      • latitude number

        纬度，范围为 -90 到 90。

      • longitude number

        经度，范围为 -180 到 180。

      • accuracy number (可选)

        非负精度值。默认为 0。

    • hasTouch boolean (可选)#

      指定视口是否支持触摸事件。默认为 false。了解更多关于移动端模拟。

    • httpCredentials Object (可选)#

      • username string

      • password string

      • origin string (可选)

        限定仅在特定 origin（scheme://host:port）发送 http 认证信息。

      • send "unauthorized" | "always" (可选)

        此选项仅适用于通过对应 APIRequestContext 发送的请求，不影响浏览器发出的请求。'always' - 每个 API 请求都会携带带有基本认证信息的 Authorization 头。'unauthorized' - 仅在收到带有 WWW-Authenticate 头的 401（未授权）响应时发送认证信息。默认为 'unauthorized'。

      HTTP 认证凭据。如果未指定 origin，则用户名和密码会在收到未授权响应时发送给任意服务器。

    • ignoreHTTPSErrors boolean (可选)#

      是否在发送网络请求时忽略 HTTPS 错误。默认为 false。

    • isMobile boolean (可选)#

      是否考虑 meta viewport 标签并启用触摸事件。isMobile 是设备的一部分，通常无需手动设置。默认为 false，且 Firefox 不支持。了解更多关于移动端模拟。

    • javaScriptEnabled boolean (可选)#

      是否在上下文中启用 JavaScript。默认为 true。了解更多关于禁用 JavaScript。

    • locale string (可选)#

      指定用户区域设置，例如 en-GB、de-DE 等。区域设置会影响 navigator.language、Accept-Language 请求头以及数字和日期格式规则。默认为系统默认区域设置。更多模拟相关内容见模拟指南。

    • logger Logger (可选)#

      Playwright 日志的日志记录器。

    • offline boolean (可选)#

      是否模拟网络离线。默认为 false。了解更多关于网络模拟。

    • permissions Array<string> (可选)#

      授予该上下文所有页面的权限列表。更多详情见 browserContext.grantPermissions()。默认为无。

    • pkg string (可选)#

      可选，指定启动的包名，替代默认的 Android Chrome。

    • proxy Object (可选) 新增于: v1.29#

      • server string

        所有请求使用的代理。支持 HTTP 和 SOCKS 代理，例如 http://myproxy.com:3128 或 socks5://myproxy.com:3128。简写 myproxy.com:3128 视为 HTTP 代理。

      • bypass string (可选)

        可选，逗号分隔的域名列表，指定不走代理，例如 ".com, chromium.org, .domain.com"。

      • username string (可选)

        可选，HTTP 代理需要认证时使用的用户名。

      • password string (可选)

        可选，HTTP 代理需要认证时使用的密码。

      网络代理设置。

    • recordHar Object (可选)#

      • omitContent boolean (可选)

        可选，控制是否在 HAR 文件中省略请求内容。默认为 false。已废弃，请使用 content 策略。

      • content "omit" | "embed" | "attach" (可选)

        可选，控制资源内容的管理方式。omit 表示不保存内容，attach 表示资源以单独文件或 ZIP 条目保存，embed 表示内容内嵌于 HAR 文件。.zip 输出文件默认为 attach，其他扩展名默认为 embed。

      • path string

        HAR 文件保存到文件系统的路径。如果文件名以 .zip 结尾，则默认使用 content: 'attach'。

      • mode "full" | "minimal" (可选)

        设为 minimal 时，仅记录 HAR 回放所需的最小信息，不包含大小、时序、页面、Cookie、安全等信息。默认为 full。

      • urlFilter string | RegExp (可选)

        用于过滤存储到 HAR 的请求的 glob 或正则表达式。当通过上下文选项提供了 baseURL 且传入的 URL 是路径时，会通过 new URL() 合并。默认为无。

      为所有页面启用 HAR 录制，保存到 recordHar.path 文件。如果未指定，则不会录制 HAR。请确保在 browserContext.close() 后等待 HAR 文件保存。

    • recordVideo Object (可选)#

      • dir string

        视频保存的目录路径。

      • size Object (可选)

        • width number

          视频帧宽度。

        • height number

          视频帧高度。

        可选，录制视频的尺寸。如果未指定，则等于 viewport 缩放到 800x800 内。如果未显式配置 viewport，则视频尺寸默认为 800x450。每个页面的实际画面会按需缩放以适配指定尺寸。

      为所有页面启用视频录制，保存到 recordVideo.dir 目录。如果未指定，则不录制视频。请确保在 browserContext.close() 后等待视频保存。

    • reducedMotion null | "reduce" | "no-preference" (可选)#

      模拟 'prefers-reduced-motion' 媒体特性，支持的值有 'reduce'、'no-preference'。更多详情见 page.emulateMedia()。传递 null 可重置为系统默认。默认为 'no-preference'。

    • screen Object (可选)#

      • width number

        页面宽度（像素）。

      • height number

        页面高度（像素）。

      通过 window.screen 在网页内模拟一致的窗口屏幕尺寸。仅在设置了 viewport 时生效。

    • serviceWorkers "allow" | "block" (可选)#

      是否允许站点注册 Service Worker。默认为 'allow'。

      • 'allow'：允许注册 Service Worker。
      • 'block'：Playwright 会阻止所有 Service Worker 的注册。

    • strictSelectors boolean (可选)#

      若设为 true，则为该上下文启用严格选择器模式。在严格模式下，所有只允许单个目标 DOM 元素的选择器操作，如果匹配到多个元素会抛出异常。此选项不影响 Locator API（Locator 始终为严格模式）。默认为 false。更多关于严格模式请参见 Locator。

    • timezoneId string (可选)#

      更改上下文的时区。支持的时区 ID 列表见 ICU 的 metaZones.txt。默认为系统时区。

    • userAgent string (可选)#

      指定该上下文使用的 User-Agent。

    • videoSize Object (可选)#

      已废弃

      请使用 recordVideo 代替。

      • width number

        视频帧宽度。

      • height number

        视频帧高度。

    • videosPath string (可选)#

      已废弃

      请使用 recordVideo 代替。

    • viewport null | Object (可选)#

      • width number

        页面宽度（像素）。

      • height number

        页面高度（像素）。

      为每个页面模拟一致的视口。默认为 1280x720 视口。使用 null 可禁用一致视口模拟。了解更多关于视口模拟。

      备注

      null 值会跳过默认预设，使视口依赖于操作系统定义的主机窗口大小。这样会导致测试执行结果不确定。

返回值

longTap​

新增于: v1.9 androidDevice.longTap

对由 selector 定义的小部件执行长按操作。

用法

await androidDevice.longTap(selector);
await androidDevice.longTap(selector, options);

参数

  • selector [AndroidSelector]#

    要长按的选择器。

  • options Object (可选)

返回值

model​

新增于: v1.9 androidDevice.model

设备型号。

用法

androidDevice.model();

返回值

open​

新增于: v1.9 androidDevice.open

在设备的 shell 中启动一个进程，并返回用于与该进程通信的 socket。

用法

await androidDevice.open(command);

参数

  • command string#

    要执行的 shell 命令。

返回值

pinchClose​

新增于: v1.9 androidDevice.pinchClose

对由 selector 定义的小部件执行收拢（Pinch Close）手势。

用法

await androidDevice.pinchClose(selector, percent);
await androidDevice.pinchClose(selector, percent, options);

参数

  • selector [AndroidSelector]#

    要执行收拢手势的选择器。

  • percent number#

    收拢手势的距离，按小部件尺寸的百分比。

  • options Object (可选)

    • speed number (可选)#

      可选，收拢手势的速度，单位为像素/秒。

    • timeout number (可选)#

      最大超时时间（毫秒），默认为 30 秒，传递 0 表示禁用超时。默认值可通过 androidDevice.setDefaultTimeout() 方法更改。

返回值

pinchOpen​

新增于: v1.9 androidDevice.pinchOpen

对由 selector 定义的小部件执行张开（Pinch Open）手势。

用法

await androidDevice.pinchOpen(selector, percent);
await androidDevice.pinchOpen(selector, percent, options);

参数

  • selector [AndroidSelector]#

    要执行张开手势的选择器。

  • percent number#

    张开手势的距离，按小部件尺寸的百分比。

  • options Object (可选)

    • speed number (可选)#

      可选，张开手势的速度，单位为像素/秒。

    • timeout number (可选)#

      最大超时时间（毫秒），默认为 30 秒，传递 0 表示禁用超时。默认值可通过 androidDevice.setDefaultTimeout() 方法更改。

返回值

press​

新增于: v1.9 androidDevice.press

在由 selector 定义的小部件中按下指定的 key。

用法

await androidDevice.press(selector, key);
await androidDevice.press(selector, key, options);

参数

  • selector [AndroidSelector]#

    要按键的选择器。

  • key [AndroidKey]#

    要按下的按键。

  • options Object (可选)

返回值

push​

新增于: v1.9 androidDevice.push

将文件复制到设备上。

用法

await androidDevice.push(file, path);
await androidDevice.push(file, path, options);

参数

  • file string | Buffer#

    文件路径或文件内容。

  • path string#

    设备上的目标文件路径。

  • options Object (可选)

    • mode number (可选)#

      可选，文件权限模式，默认为 644（rw-r--r--）。

返回值

screenshot​

新增于: v1.9 androidDevice.screenshot

返回设备截图的 Buffer。

用法

await androidDevice.screenshot();
await androidDevice.screenshot(options);

参数

  • options Object (可选)

    • path string (可选)#

      图片保存的文件路径。如果 path 是相对路径，则相对于当前工作目录解析。如果未指定路径，则图片不会保存到磁盘。

返回值

scroll​

新增于: v1.9 androidDevice.scroll

滚动由 selector 定义的小部件到指定的 direction 方向。

用法

await androidDevice.scroll(selector, direction, percent);
await androidDevice.scroll(selector, direction, percent, options);

参数

  • selector [AndroidSelector]#

    要滚动的选择器。

  • direction "down" | "up" | "left" | "right"#

    滚动方向。

  • percent number#

    滚动的距离，按小部件尺寸的百分比。

  • options Object (可选)

    • speed number (可选)#

      可选，滚动的速度，单位为像素/秒。

    • timeout number (可选)#

      最大超时时间（毫秒），默认为 30 秒，传递 0 表示禁用超时。默认值可通过 androidDevice.setDefaultTimeout() 方法更改。

返回值

serial​

新增于: v1.9 androidDevice.serial

设备序列号。

用法

androidDevice.serial();

返回值

setDefaultTimeout​

新增于: v1.9 androidDevice.setDefaultTimeout

此设置将更改所有支持 timeout 选项的方法的默认最大超时时间。

用法

androidDevice.setDefaultTimeout(timeout);

参数

  • timeout number#

    最大超时时间（毫秒）

shell​

新增于: v1.9 androidDevice.shell

在设备上执行 shell 命令并返回其输出。

用法

await androidDevice.shell(command);

参数

  • command string#

    要执行的 shell 命令。

返回值

swipe​

新增于: v1.9 androidDevice.swipe

滑动由 selector 定义的小部件到指定的 direction 方向。

用法

await androidDevice.swipe(selector, direction, percent);
await androidDevice.swipe(selector, direction, percent, options);

参数

  • selector [AndroidSelector]#

    要滑动的选择器。

  • direction "down" | "up" | "left" | "right"#

    滑动方向。

  • percent number#

    滑动的距离，按小部件尺寸的百分比。

  • options Object (可选)

    • speed number (可选)#

      可选，滑动的速度，单位为像素/秒。

    • timeout number (可选)#

      最大超时时间（毫秒），默认为 30 秒，传递 0 表示禁用超时。默认值可通过 androidDevice.setDefaultTimeout() 方法更改。

返回值

tap​

新增于: v1.9 androidDevice.tap

点击由 selector 定义的小部件。

用法

await androidDevice.tap(selector);
await androidDevice.tap(selector, options);

参数

  • selector [AndroidSelector]#

    要点击的选择器。

  • options Object (可选)

    • duration number (可选)#

      可选，点击的持续时间（毫秒）。

    • timeout number (可选)#

      最大超时时间（毫秒），默认为 30 秒，传递 0 表示禁用超时。默认值可通过 androidDevice.setDefaultTimeout() 方法更改。

返回值

wait​

新增于: v1.9 androidDevice.wait

等待指定的 selector 出现或消失，具体取决于 state 的设置。

用法

await androidDevice.wait(selector);
await androidDevice.wait(selector, options);

参数

  • selector [AndroidSelector]#

    要等待的选择器。

  • options Object (可选)

    • state "gone" (可选)#

      可选状态。可选值包括：

      • 默认 - 等待元素出现。
      • 'gone' - 等待元素消失。

    • timeout number (可选)#

      最大超时时间（毫秒），默认为 30 秒，传递 0 表示禁用超时。默认值可通过 androidDevice.setDefaultTimeout() 方法更改。

返回值

waitForEvent​

新增于: v1.9 androidDevice.waitForEvent

等待事件触发，并将其值传递给谓词函数。当谓词返回真值时结束等待。

用法

await androidDevice.waitForEvent(event);
await androidDevice.waitForEvent(event, optionsOrPredicate);

参数

  • event string#

    事件名称，通常与传递给 *.on(event) 的名称一致。

  • optionsOrPredicate function | Object (可选)#

    • predicate function

      接收事件数据，当返回真值时结束等待。

    • timeout number (可选)

      等待的最大时间（毫秒）。默认为 30000（30 秒）。传递 0 表示禁用超时。默认值可通过 androidDevice.setDefaultTimeout() 方法更改。

    可以是接收事件的谓词函数，也可以是参数对象。可选。

返回值

webView​

新增于: v1.9 androidDevice.webView

该方法会等待直到有匹配 selector 的 AndroidWebView 被打开并返回它。如果已经有匹配 selector 的 AndroidWebView 处于打开状态，则会立即返回。

用法

await androidDevice.webView(selector);
await androidDevice.webView(selector, options);

参数

  • selector Object#

    • pkg string (可选)

      可选，包名标识符。

    • socketName string (可选)

      可选，webview 的 socket 名称。

  • options Object (可选)

返回值

webViews​

新增于: v1.9 androidDevice.webViews

当前已打开的 WebView 列表。

用法

androidDevice.webViews();

返回值

属性​

input​

新增于: v1.9 androidDevice.input

用法

androidDevice.input

类型

事件​

on('close')​

新增于: v1.28 androidDevice.on('close')

当设备连接关闭时触发。

用法

androidDevice.on('close', data => {});

事件数据

on('webview')​

新增于: v1.9 androidDevice.on('webview')

当检测到新的 WebView 实例时触发。

用法

androidDevice.on('webview', data => {});

事件数据