跳到主要内容

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，从而将基本 URL 考虑在内。默认未设置。示例

      • baseURL: https://127.0.0.1:3000 并且导航到 /bar.html 会得到 https://127.0.0.1:3000/bar.html
      • baseURL: https://127.0.0.1:3000/foo/ 并且导航到 ./bar.html 会得到 https://127.0.0.1:3000/foo/bar.html
      • baseURL: https://127.0.0.1:3000/foo (没有尾部斜杠) 并且导航到 ./bar.html 会得到 https://127.0.0.1:3000/bar.html

    • bypassCSP boolean (可选)#

      切换是否绕过页面的内容安全策略 (CSP)。默认为 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).

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

        此选项仅适用于从相应的 APIRequestContext 发送的请求，并且不影响从浏览器发送的请求。'always' - 带有基本身份验证凭据的 Authorization 标头将随每个 API 请求一起发送。 'unauthorized - 仅当收到带有 WWW-Authenticate 标头的 401 (Unauthorized) 响应时才发送凭据。默认为 '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 日志记录的 Logger sink。

    • offline boolean (可选)#

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

    • permissions Array<string> (可选)#

      要授予此上下文中所有页面的权限列表。有关更多详细信息，请参阅 browserContext.grantPermissions()。默认为无。

    • pkg string (可选)#

      要启动的可选包名称，而不是默认的 Chrome for Android。

    • 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 信息。默认为 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

          视频帧高度。

        录制视频的可选尺寸。如果未指定，则尺寸将等于缩小到适合 800x800 的 viewport。如果未显式配置 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 (可选)#

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

    • 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();

返回值

打开​

添加于: v1.9 androidDevice.open

在设备上的 shell 中启动一个进程，并返回一个 socket 以与启动的进程进行通信。

用法

await androidDevice.open(command);

参数

返回值

pinchClose（捏合关闭）​

添加于: v1.9 androidDevice.pinchClose

朝关闭方向捏合由 selector（选择器） 定义的 widget（小部件）。

用法

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

参数

返回值

pinchOpen（捏合打开）​

添加于: v1.9 androidDevice.pinchOpen

朝打开方向捏合由 selector（选择器） 定义的 widget（小部件）。

用法

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

参数

返回值

press（按下）​

添加于: v1.9 androidDevice.press

按下由 selector（选择器） 定义的 widget（小部件）中的特定 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);

参数

返回值

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（选择器） 定义的 widget（小部件）。

用法

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

参数

  • selector [AndroidSelector]#

    要滚动的选择器。

  • direction "down" | "up" | "left" | "right"（"下" | "上" | "左" | "右"）#

    滚动方向。

  • percent number（数字）#

    滚动距离，以小部件大小的百分比表示。

  • options Object (可选)

返回值

serial（序列号）​

添加于: v1.9 androidDevice.serial

设备序列号。

用法

androidDevice.serial();

返回值

setDefaultTimeout（设置默认超时）​

添加于: v1.9 androidDevice.setDefaultTimeout

此设置将更改所有接受 timeout（超时） 选项的方法的默认最大时间。

用法

androidDevice.setDefaultTimeout(timeout);

参数

shell​

添加于: v1.9 androidDevice.shell

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

用法

await androidDevice.shell(command);

参数

返回值

swipe（滑动）​

添加于: v1.9 androidDevice.swipe

在指定的 direction（方向） 上滑动由 selector（选择器） 定义的 widget（小部件）。

用法

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

参数

  • selector [AndroidSelector]#

    要滑动的选择器。

  • direction "down" | "up" | "left" | "right"（"下" | "上" | "左" | "右"）#

    滑动方向。

  • percent number（数字）#

    滑动距离，以小部件大小的百分比表示。

  • options Object (可选)

返回值

tap（点击）​

添加于: v1.9 androidDevice.tap

点击由 selector（选择器） 定义的 widget（小部件）。

用法

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

参数

返回值

wait（等待）​

添加于: v1.9 androidDevice.wait

等待特定的 selector（选择器） 出现或消失，具体取决于 state（状态）。

用法

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

参数

  • selector [AndroidSelector]#

    要等待的选择器。

  • options Object (可选)

    • state "gone"（"消失"） (可选)#

      可选状态。可以是

      • default（默认）- 等待元素出现。
      • 'gone' - 等待元素不出现。

    • timeout number（数字） (可选)#

      最大等待时间，单位为毫秒，默认为 30 秒，传递 0 以禁用超时。默认值可以通过 androidDevice.setDefaultTimeout() 方法更改。

返回值

waitForEvent（等待事件）​

添加于: v1.9 androidDevice.waitForEvent

等待事件触发并将其值传递到 predicate（谓词）函数中。当谓词返回真值时返回。

用法

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

参数

返回值

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

事件数据