跳转到主要内容

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

将由 selector 定义的部件以指定 direction 滑动。

用法

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://: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' - 每次 API 请求都会发送带有基本身份验证凭据的 Authorization 头部。'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 （可选）#

      要启动的可选包名，而不是默认的 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 信息，这些信息在从 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

          视频帧高度。

        录制视频的可选尺寸。如果未指定，尺寸将等于 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 Workers。默认为 'allow'。

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

    • strictSelectors boolean （可选）#

      如果设置为 true，则为此上下文启用严格选择器模式。在严格选择器模式下，当有多个元素匹配选择器时，对暗示单个目标 DOM 元素的所有选择器操作都将抛出错误。此选项不影响任何 Locator API（Locators 始终是严格的）。默认为 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 中启动一个进程，并返回一个套接字以与启动的进程通信。

用法

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

返回捕获的设备屏幕截图的缓冲区。

用法

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

根据 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);

参数

  • selector Object#

    • pkg string （可选）

      可选的包标识符。

    • socketName string （可选）

      可选的 webview 套接字名称。

  • options Object (可选)

返回

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

事件数据