Skip to main content

AndroidDevice

AndroidDevice represents a connected device, either real hardware or emulated. Devices can be obtained using android.devices().

方法​

🌐 Methods

close​

Added in: v1.9 androidDevice.close

与设备断开连接。

🌐 Disconnects from the device.

用法

await androidDevice.close();

返回

drag​

Added in: v1.9 androidDevice.drag

将由 selector 定义的小部件拖动到 dest 点。

🌐 Drags the widget defined by selector towards dest point.

用法

await androidDevice.drag(selector, dest);
await androidDevice.drag(selector, dest, options);

参数

  • selector [AndroidSelector]#

    要拖动的选择器。

  • dest Object#

    拖动到的点。

  • options Object (optional)

    • speed number (optional)#

      可选的拖动速度（以每秒像素为单位）。

    • timeout number (optional)#

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

返回

fill​

Added in: v1.9 androidDevice.fill

在特定的选择器输入框中填写文本。

🌐 Fills the specific selector input box with text.

用法

await androidDevice.fill(selector, text);
await androidDevice.fill(selector, text, options);

参数

  • selector [AndroidSelector]#

    要填充的选择器。

  • text string#

    输入框中要填写的文本。

  • options Object (optional)

返回

fling​

Added in: v1.9 androidDevice.fling

将由 selector 定义的小部件以指定的 direction 方向抛出。

🌐 Flings the widget defined by selector in the specified direction.

用法

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

参数

  • selector [AndroidSelector]#

    选择器来投掷。

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

    投掷方向。

  • options Object (optional)

    • speed number (optional)#

      可选的投射速度（以每秒像素为单位）。

    • timeout number (optional)#

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

返回

info​

Added in: v1.9 androidDevice.info

返回由 selector 定义的小部件的信息。

🌐 Returns information about a widget defined by selector.

用法

await androidDevice.info(selector);

参数

  • selector [AndroidSelector]#

    返回信息的选择器。

返回

installApk​

Added in: v1.9 androidDevice.installApk

在设备上安装 apk。

🌐 Installs an apk on the device.

用法

await androidDevice.installApk(file);
await androidDevice.installApk(file, options);

参数

  • file string | Buffer#

    apk 文件的路径或 apk 文件内容。

  • options Object (optional)

    • args Array<string> (optional)#

      传递给 shell:cmd package install 调用的可选参数。默认值为 -r -t -S。

返回

launchBrowser​

Added in: v1.9 androidDevice.launchBrowser

在设备上启动 Chrome 浏览器，并返回其持久上下文。

🌐 Launches Chrome browser on the device, and returns its persistent context.

用法

await androidDevice.launchBrowser();
await androidDevice.launchBrowser(options);

参数

  • options Object (optional)

    • acceptDownloads boolean (optional)#

      是否自动下载所有附件。默认值为 true，表示接受所有下载。

    • args Array<string> (optional) Added in: v1.29#

      warning

      使用自定义浏览器参数需自行承担风险，因为其中一些可能会破坏 Playwright 的功能。

      传递给浏览器实例的额外参数。Chromium 标志列表可以在 这里 查看。

    • baseURL string (optional)#

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

      切换是否绕过页面的内容安全策略。默认值为 false。

    • colorScheme null | "light" | "dark" | "no-preference" (optional)#

      模拟 prefers-colors-scheme 媒体特性，支持的值为 'light' 和 'dark'。更多详情请参见 page.emulateMedia()。传入 null 可将模拟重置为系统默认值。默认值为 'light'。

    • contrast null | "no-preference" | "more" (optional)#

      模拟 'prefers-contrast' 媒体特性，支持的值为 'no-preference'、'more'。更多详情请参见 page.emulateMedia()。传递 null 会将模拟重置为系统默认值。默认为 'no-preference'。

    • deviceScaleFactor number (optional)#

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

    • extraHTTPHeaders Object<string, string> (optional)#

      一个包含附加 HTTP 头的对象，这些头将随每个请求发送。默认为无。

    • forcedColors null | "active" | "none" (optional)#

      模拟 'forced-colors' 媒体特性，支持的值为 'active'、'none'。更多详情请参见 page.emulateMedia()。传递 null 会将模拟重置为系统默认值。默认为 'none'。

    • geolocation Object (optional)#

      • latitude number

        纬度在 -90 到 90 之间。

      • longitude number

        经度在 -180 到 180 之间。

      • accuracy number (optional)

        非负精度值。默认值为 0。

    • hasTouch boolean (optional)#

      指定视口是否支持触摸事件。默认值为 false。了解更多关于 移动模拟 的信息。

    • httpCredentials Object (optional)#

      • username string

      • password string

      • origin string (optional)

        限制在特定来源 (scheme://host:port) 上发送 http 凭据。

      • send "unauthorized" | "always" (optional)

        此选项仅适用于从对应的 APIRequestContext 发送的请求，并不影响从浏览器发送的请求。'always' - Authorization 头信息会随每个 API 请求发送基本认证凭据。'unauthorized - 凭据仅在收到带有 WWW-Authenticate 头的 401（未授权）响应时发送。默认为 'unauthorized'。

      HTTP 认证 的凭据。如果未指定来源，用户名和密码将在收到未授权响应时发送到任何服务器。

    • ignoreHTTPSErrors boolean (optional)#

      发送网络请求时是否忽略 HTTPS 错误。默认值为 false。

    • isMobile boolean (optional)#

      是否考虑 meta viewport 标签并启用触摸事件。isMobile 是 device 的一部分，因此你实际上不需要手动设置它。默认值为 false，并且在 Firefox 中不受支持。了解更多关于 移动端模拟 的信息。

    • javaScriptEnabled boolean (optional)#

      是否在此环境中启用 JavaScript。默认为 true。了解更多关于禁用 JavaScript的信息。

    • locale string (optional)#

      指定用户区域设置，例如 en-GB、de-DE 等。区域设置会影响 navigator.language 的值、Accept-Language 请求头的值以及数字和日期的格式规则。默认为系统默认区域设置。有关模拟的更多信息，请参阅我们的 模拟指南。

    • logger Logger (optional)#

      已弃用

      日志记录器接收到的日志不完整。请改用追踪。

      用于 Playwright 日志记录的日志器接收器。

    • offline boolean (optional)#

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

    • permissions Array<string> (optional)#

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

    • pkg string (optional)#

      用于启动而不是默认的 Android Chrome 的可选包名称。

    • proxy Object (optional) Added in: v1.29#

      • server string

        用于所有请求的代理。支持 HTTP 和 SOCKS 代理，例如 http://myproxy.com:3128 或 socks5://myproxy.com:3128。简写 myproxy.com:3128 被视为 HTTP 代理。

      • bypass string (optional)

        可选的以逗号分隔的域名，用于绕过代理，例如 ".com, chromium.org, .domain.com"。

      • username string (optional)

        如果 HTTP 代理需要身份验证，则使用可选的用户名。

      • password string (optional)

        如果 HTTP 代理需要身份验证，则使用可选密码。

      网络代理设置。

    • recordHar Object (optional)#

      • omitContent boolean (optional)

        可选设置，用于控制是否从 HAR 中省略请求内容。默认值为 false。已弃用，请改用 content 策略。

      • content "omit" | "embed" | "attach" (optional)

        可选设置，用于控制资源内容管理。如果指定 omit，内容不会被保存。如果指定 attach，资源将作为单独的文件或 ZIP 压缩包中的条目保存。如果指定 embed，内容将根据 HAR 规范内联存储在 HAR 文件中。默认情况下，对于 .zip 输出文件为 attach，对于所有其他文件扩展名为 embed。

      • path string

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

      • mode "full" | "minimal" (optional)

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

      • urlFilter string | RegExp (optional)

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

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

    • recordVideo Object (optional)#

      • dir string

        放置视频的目录路径。

      • size Object (optional)

        • width number

          视频帧宽度。

        • height number

          视频帧高度。

        录制视频的可选尺寸。如果未指定，大小将等于 viewport 并缩小以适应 800x800。如果未显式配置 viewport，视频大小默认为 800x450。每页的实际画面如有必要将缩小以适应指定尺寸。

      启用将所有页面的视频录制到 recordVideo.dir 目录。如果未指定，则不会录制视频。请确保等待 browserContext.close() 以便保存视频。

    • reducedMotion null | "reduce" | "no-preference" (optional)#

      模拟 'prefers-reduced-motion' 媒体特性，支持的值为 'reduce'、'no-preference'。更多详情请参见 page.emulateMedia()。传递 null 会将模拟重置为系统默认值。默认为 'no-preference'。

    • screen Object (optional)#

      • width number

        页面宽度（以像素为单位）。

      • height number

        页面高度（以像素为单位）。

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

    • serviceWorkers "allow" | "block" (optional)#

      是否允许网站注册服务工作进程。默认值为 'allow'。

      • 'allow'：服务工作者 可以被注册。
      • 'block'：Playwright 将阻止所有服务工作进程的注册。

    • strictSelectors boolean (optional)#

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

    • timezoneId string (optional)#

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

    • userAgent string (optional)#

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

    • videoSize Object (optional)#

      已弃用

      请改用 recordVideo。

      • width number

        视频帧宽度。

      • height number

        视频帧高度。

    • videosPath string (optional)#

      已弃用

      请改用 recordVideo。

    • viewport null | Object (optional)#

      • width number

        页面宽度（以像素为单位）。

      • height number

        页面高度（以像素为单位）。

      为每个页面模拟一致的视口。默认视口为 1280x720。使用 null 可禁用一致视口模拟。了解更多关于视口模拟的信息。

      note

      null 值选择不使用默认预设，使视口依赖于操作系统定义的主机窗口大小。这会导致测试执行结果不确定。

返回

longTap​

Added in: v1.9 androidDevice.longTap

在由 selector 定义的小部件上执行长按操作。

🌐 Performs a long tap on the widget defined by selector.

用法

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

参数

  • selector [AndroidSelector]#

    要点击的选择器。

  • options Object (optional)

返回

model​

Added in: v1.9 androidDevice.model

设备型号。

🌐 Device model.

用法

androidDevice.model();

返回

open​

Added in: v1.9 androidDevice.open

在设备上的 shell 中启动进程并返回套接字以与启动的进程进行通信。

🌐 Launches a process in the shell on the device and returns a socket to communicate with the launched process.

用法

await androidDevice.open(command);

参数

  • command string#

    要执行的 shell 命令。

返回

pinchClose​

Added in: v1.9 androidDevice.pinchClose

捏合由 selector 定义的小部件，方向为闭合方向。

🌐 Pinches the widget defined by selector in the closing direction.

用法

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

参数

  • selector [AndroidSelector]#

    选择器捏合。

  • percent number#

    捏合大小占小部件大小的百分比。

  • options Object (optional)

    • speed number (optional)#

      可选的捏合速度（以每秒像素为单位）。

    • timeout number (optional)#

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

返回

pinchOpen​

Added in: v1.9 androidDevice.pinchOpen

捏住由 selector 定义的小部件，以打开的方向操作。

🌐 Pinches the widget defined by selector in the open direction.

用法

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

参数

  • selector [AndroidSelector]#

    选择器捏开。

  • percent number#

    捏合大小占小部件大小的百分比。

  • options Object (optional)

    • speed number (optional)#

      可选的捏合速度（以每秒像素为单位）。

    • timeout number (optional)#

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

返回

press​

Added in: v1.9 androidDevice.press

在由 selector 定义的小部件中按下指定的 key。

🌐 Presses the specific key in the widget defined by selector.

用法

await androidDevice.press(selector, key);
await androidDevice.press(selector, key, options);

参数

  • selector [AndroidSelector]#

    选择器按下按键。

  • key [AndroidKey]#

    要按的键。

  • options Object (optional)

返回

push​

Added in: v1.9 androidDevice.push

将文件复制到设备。

🌐 Copies a file to the device.

用法

await androidDevice.push(file, path);
await androidDevice.push(file, path, options);

参数

  • file string | Buffer#

    文件的路径或文件内容。

  • path string#

    设备上文件的路径。

  • options Object (optional)

    • mode number (optional)#

      可选文件模式，默认为 644（rw-r--r--）。

返回

screenshot​

Added in: v1.9 androidDevice.screenshot

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

🌐 Returns the buffer with the captured screenshot of the device.

用法

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

参数

  • options Object (optional)

    • path string (optional)#

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

返回

scroll​

Added in: v1.9 androidDevice.scroll

在指定的方向滚动由选择器定义的小部件。

🌐 Scrolls the widget defined by selector in the specified 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 (optional)

    • speed number (optional)#

      可选的滚动速度（以每秒像素为单位）。

    • timeout number (optional)#

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

返回

serial​

Added in: v1.9 androidDevice.serial

设备序列号。

🌐 Device serial number.

用法

androidDevice.serial();

返回

setDefaultTimeout​

Added in: v1.9 androidDevice.setDefaultTimeout

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

🌐 This setting will change the default maximum time for all the methods accepting timeout option.

用法

androidDevice.setDefaultTimeout(timeout);

参数

  • timeout number#

    最长时间（以毫秒为单位）

shell​

Added in: v1.9 androidDevice.shell

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

🌐 Executes a shell command on the device and returns its output.

用法

await androidDevice.shell(command);

参数

  • command string#

    要执行的 shell 命令。

返回

swipe​

Added in: v1.9 androidDevice.swipe

在指定的方向上滑动由选择器定义的小部件。

🌐 Swipes the widget defined by selector in the specified 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 (optional)

    • speed number (optional)#

      可选的滑动速度（以每秒像素为单位）。

    • timeout number (optional)#

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

返回

tap​

Added in: v1.9 androidDevice.tap

点击由 selector 定义的小部件。

🌐 Taps on the widget defined by selector.

用法

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

参数

  • selector [AndroidSelector]#

    要点击的选择器。

  • options Object (optional)

    • duration number (optional)#

      点击的可选持续时间（以毫秒为单位）。

    • timeout number (optional)#

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

返回

wait​

Added in: v1.9 androidDevice.wait

等待特定的 选择器 根据 状态 出现或消失。

🌐 Waits for the specific selector to either appear or disappear, depending on the state.

用法

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

参数

  • selector [AndroidSelector]#

    选择器等待。

  • options Object (optional)

    • state "gone" (optional)#

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

      • 默认 - 等待元素出现。
      • 'gone' - 等待元素不存在。

    • timeout number (optional)#

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

返回

waitForEvent​

Added in: v1.9 androidDevice.waitForEvent

等待事件触发，并将其值传递给谓词函数。当谓词返回真值时返回。

🌐 Waits for event to fire and passes its value into the predicate function. Returns when the predicate returns truthy value.

用法

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

参数

  • event string#

    事件名称，通常传递到 *.on(event) 的那个相同名称。

  • optionsOrPredicate function | Object (optional)#

    • predicate function

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

    • timeout number (optional)

      等待的最长时间，以毫秒为单位。默认值为 30000（30 秒）。传入 0 可禁用超时。可以使用 androidDevice.setDefaultTimeout() 来更改默认值。

    可以是接收事件的谓词，也可以是一个选项对象。可选。

返回

webView​

Added in: v1.9 androidDevice.webView

此方法会等待直到打开与 selector 匹配的 AndroidWebView 并返回它。如果已经有与 selector 匹配的 AndroidWebView 打开，则会立即返回。

🌐 This method waits until AndroidWebView matching the selector is opened and returns it. If there is already an open AndroidWebView matching the selector, returns immediately.

用法

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

参数

  • selector Object#

    • pkg string (optional)

      可选的包标识符。

    • socketName string (optional)

      可选的 webview 套接字名称。

  • options Object (optional)

返回

webViews​

Added in: v1.9 androidDevice.webViews

当前打开的 WebView。

🌐 Currently open WebViews.

用法

androidDevice.webViews();

返回

属性​

🌐 Properties

input​

Added in: v1.9 androidDevice.input

用法

androidDevice.input

类型

事件​

🌐 Events

on('close')​

Added in: v1.28 androidDevice.on('close')

当设备连接关闭时触发。

🌐 Emitted when the device connection gets closed.

用法

androidDevice.on('close', data => {});

事件数据

on('webview')​

Added in: v1.9 androidDevice.on('webview')

当检测到新的 WebView 实例时触发。

🌐 Emitted when a new WebView instance is detected.

用法

androidDevice.on('webview', data => {});

事件数据