跳到主要内容

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 "向下" | "向上" | "向左" | "向右"#

    滑动方向。

  • 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: 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 | "浅色" | "深色" | "无偏好" (可选)#

      模拟 prefers-colors-scheme 媒体特性，支持的值为 '浅色' 和 '深色'。详情请参阅 page.emulateMedia()。传入 null 会将模拟重置为系统默认值。默认为 '浅色'。

    • contrast null | "无偏好" | "更高" (可选)#

      模拟 'prefers-contrast' 媒体特性，支持的值为 '无偏好'、'更高'。详情请参阅 page.emulateMedia()。传入 null 会将模拟重置为系统默认值。默认为 '无偏好'。

    • deviceScaleFactor number (可选)#

      指定设备缩放因子（可理解为 dpr）。默认为 1。了解更多关于 使用设备缩放因子模拟设备 的信息。

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

      一个包含每次请求发送的额外 HTTP 头信息的对象。默认为空。

    • forcedColors null | "启用" | "禁用" (可选)#

      模拟 'forced-colors' 媒体特性，支持的值为 '启用'、'禁用'。详情请参阅 page.emulateMedia()。传入 null 会将模拟重置为系统默认值。默认为 '禁用'。

    • 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 "未授权" | "总是" (可选)

        此选项仅适用于从相应的 APIRequestContext 发送的请求，不影响从浏览器发送的请求。'总是' - 每次 API 请求都会发送带有基本身份验证凭据的 Authorization 标头。'未授权' - 凭据仅在收到包含 WWW-Authenticate 标头的 401 (未授权) 响应时发送。默认为 '未授权'。

      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 接收器。

    • 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，则不保留内容。如果指定 attach，资源将保留为单独的文件或 ZIP 存档中的条目。如果指定 embed，内容将根据 HAR 规范以内联方式存储在 HAR 文件中。对于 .zip 输出文件，默认为 attach；对于所有其他文件扩展名，默认为 embed。

      • path string

        文件系统上写入 HAR 文件的路径。如果文件扩展名为 .zip，则默认使用 content: 'attach'。

      • mode "完整" | "最小" (可选)

        设置为 minimal 时，仅记录从 HAR 路由所需的信息。这将省略大小、时序、页面、cookie、安全以及从 HAR 重放时未使用的其他类型的 HAR 信息。默认为 full。

      • urlFilter string | RegExp (可选)

        用于过滤存储在 HAR 中的请求的 glob 或 regex 模式。当提供了上下文选项中的 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 | "减少" | "无偏好" (可选)#

      模拟 'prefers-reduced-motion' 媒体特性，支持的值为 '减少'、'无偏好'。详情请参阅 page.emulateMedia()。传入 null 会将模拟重置为系统默认值。默认为 '无偏好'。

    • screen Object (可选)#

      • width number

        页面宽度（像素）。

      • height number

        页面高度（像素）。

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

    • serviceWorkers "允许" | "阻止" (可选)#

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

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

    • 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 中启动一个进程，并返回一个用于与启动的进程通信的 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 (optional)#

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

    • timeout number (optional)#

      最大等待时间（毫秒），默认为 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 (optional)#

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

    • timeout number (optional)#

      最大等待时间（毫秒），默认为 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 (optional)#

      可选的文件模式，默认为 644 (rw-r--r--)。

返回值

screenshot​

新增于: v1.9 androidDevice.screenshot

返回捕获的设备屏幕截图的 buffer。

用法

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

参数

  • options Object (可选)

    • path string (optional)#

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

返回值

scroll​

新增于: v1.9 androidDevice.scroll

沿指定的 方向 滚动由 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 (optional)#

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

    • timeout number (optional)#

      最大等待时间（毫秒），默认为 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 定义的控件。

用法

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 (optional)#

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

    • timeout number (optional)#

      最大等待时间（毫秒），默认为 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 (optional)#

      可选的点击持续时间，单位为毫秒。

    • timeout number (optional)#

      最大等待时间（毫秒），默认为 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" (optional)#

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

      • default - 等待元素存在。
      • 'gone' - 等待元素不存在。

    • timeout number (optional)#

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

返回值

waitForEvent​

新增于: v1.9 androidDevice.waitForEvent

等待事件触发，并将其值传入 predicate 函数。当 predicate 返回 truthy 值时返回。

用法

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

参数

  • event string#

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

  • optionsOrPredicate function | Object (optional)#

    • predicate function

      接收事件数据并在等待应该解决时解析为 truthy 值。

    • timeout number (optional)

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

    接收事件的 predicate 或一个 options 对象。可选。

返回值

webView​

新增于: v1.9 androidDevice.webView

此方法等待匹配 selector 的 AndroidWebView 打开并返回它。如果已存在匹配 selector 的 AndroidWebView，则立即返回。

用法

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

参数

  • selector Object#

    • pkg string (optional)

      可选的包标识符。

    • socketName string (optional)

      可选的 webview socket 名称。

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

事件数据