跳转到主要内容

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 定义的控件进行滑动手势 (fling)。

用法

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

参数

  • selector [AndroidSelector]#

    要进行 fling 操作的选择器。

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

    Fling 方向。

  • options Object (可选)

    • speed number (可选)#

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

    • 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 浏览器，并返回其持久化上下文 (persistent context)。

用法

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，以构建相应的 URL。默认未设置。示例

      • baseURL: https://:3000，导航到 /bar.html 会得到 https://:3000/bar.html
      • baseURL: https://:3000/foo/，导航到 ./bar.html 会得到 https://:3000/foo/bar.html
      • baseURL: https://:3000/foo (不带尾部斜杠)，导航到 ./bar.html，结果为 https://: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 (可选)

        限制在特定源（scheme://host:port）上发送 http 凭据).

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

        此选项仅适用于来自相应 APIRequestContext 的请求，不会影响来自浏览器的请求。'always' - Authorization 头和基本身份验证凭据将与每个 API 请求一起发送。'unauthorized' - 仅在收到具有 WWW-Authenticate 头的 401（未经授权）响应时发送凭据。默认为 'unauthorized'。

      用于 HTTP 身份验证的凭据。如果未指定源，则在未经授权的响应时将用户名和密码发送到任何服务器。

    • 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 文件中，符合 HAR 规范。对于 .zip 输出文件，默认为 attach；对于所有其他文件扩展名，默认为 embed。

      • path string

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

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

        设置为 minimal 时，仅记录从 HAR 路由所需的信息。这会省略 HAR 的大小、时间、页面、Cookie、安全性和其他类型的 HAR 信息，这些信息在从 HAR 重放时不使用。默认为 full。

      • urlFilter string | RegExp (可选)

        用于过滤存储在 HAR 中的请求的 glob 或正则表达式模式。当通过上下文选项提供了 baseURL 并且传入的 URL 是一个路径时，它将通过 new URL() 构造函数进行合并。默认为无。

      启用对所有页面到 recordHar.path 文件的 HAR 记录。如果未指定，则不记录 HAR。请确保在保存 HAR 之前 await browserContext.close()。

    • recordVideo Object (可选)#

      • dir string (可选)

        存放视频的目录路径。如果未指定，视频将存储在 artifactsDir 中（参见 browserType.launch() 选项）。

      • size Object (可选)

        • width number

          视频帧宽度。

        • height number

          视频帧高度。

        已录制视频的可选尺寸。如果未指定，则尺寸将等于viewport，并缩小以适应 800x800。如果未明确配置viewport，则视频尺寸默认为 800x450。每页的实际图像在必要时将缩小以适应指定的尺寸。

      • showActions Object (可选)

        • duration number (可选)

          每个注释显示的持续时间（以毫秒为单位）。默认为 500。

        • position "top-left" | "top" | "top-right" | "bottom-left" | "bottom" | "bottom-right" (可选)

          操作标题覆盖层的位置。默认为 "top-right"。

        • fontSize number (可选)

          操作标题的字体大小（以像素为单位）。默认为 24。

        如果指定，则在录制视频期间启用对交互元素的视觉标注。

      启用将所有页面视频录制到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 Workers。默认为 'allow'。

      • 'allow': Service Workers 可以注册。
      • 'block': Playwright 将阻止所有 Service Workers 的注册。

    • strictSelectors boolean (可选)#

      如果设置为 true，则为此上下文启用严格选择器模式。在严格选择器模式下，所有对隐式单个目标 DOM 元素的选择器的操作，当有多个元素匹配选择器时，都将抛出错误。此选项不影响任何 Locator API（Locator 始终是严格的）。默认为 false。有关严格模式的详细信息，请参阅Locator。

    • timezoneId string (可选)#

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

    • userAgent string (可选)#

      此上下文中使用的特定用户代理。

    • 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 定义的控件上进行向内捏合操作。

用法

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 定义的控件上进行向外捏合操作。

用法

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

在指定 direction 上对 selector 定义的控件进行滚动操作。

用法

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

在指定 direction 上对 selector 定义的控件进行滑动 (swipe) 操作。

用法

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

根据 state 等待特定的 selector 出现或消失。

用法

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 数字 (可选)

      最大等待时间（毫秒）。默认为 30000（30 秒）。传 0 禁用超时。可以使用 androidDevice.setDefaultTimeout() 更改默认值。

    一个接收事件的谓词或一个选项对象。可选。

返回

webView​

添加于：v1.9 androidDevice.webView

该方法等待直到打开了与 selector 匹配的 AndroidWebView 并将其返回。如果已经存在匹配 selector 的打开状态的 AndroidWebView，则立即返回。

用法

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

参数

返回

webViews​

添加于：v1.9 androidDevice.webViews

当前打开的 WebViews。

用法

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 => {});

事件数据