跳到主要内容

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'。

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

        限制在特定来源上发送 http 凭据 (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 路由所需的信息。 这省略了大小、时间、页面、cookie、安全性和其他类型的 HAR 信息，这些信息在从 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 (可选)#

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

    • 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 中启动进程，并返回一个套接字以与启动的进程通信。

用法

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 定义的控件。

用法

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" (可选)#

      可选状态。可以是以下之一

      • default - 等待元素出现。
      • '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 套接字名称。

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

事件数据