Android 设备

AndroidDevice 表示一个连接的设备，可以是真实硬件或模拟的。可以使用 android.devices() 获取设备。

方法

close

添加于：v1.9

androidDevice.close

断开与设备的连接。

用法

await androidDevice.close();

Promise<void>#

drag

添加于：v1.9

androidDevice.drag

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

用法

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

参数

selector [AndroidSelector]#

要拖动的选择器。
dest Object #
- x number
- y number
要拖动的点。
options Object (可选)
- speed number (可选)#
  
  拖动的可选速度，单位为像素每秒。
- timeout number (可选)#
  
  最大时间，单位为毫秒，默认为 30 秒，传递 0 可禁用超时。默认值可以使用 androidDevice.setDefaultTimeout() 方法更改。

Promise<void>#

fill

添加于：v1.9

androidDevice.fill

用 text 填充特定 selector 输入框。

用法

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

参数

selector [AndroidSelector]#

要填充的选择器。
text string #

要填充到输入框中的文本。
options Object (可选)
- timeout number (可选)#
  
  最大时间，单位为毫秒，默认为 30 秒，传递 0 可禁用超时。默认值可以使用 androidDevice.setDefaultTimeout() 方法更改。

Promise<void>#

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() 方法更改。

Promise<void>#

info

添加于：v1.9

androidDevice.info

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

用法

await androidDevice.info(selector);

参数

selector [AndroidSelector]#

要返回信息的有关选择器。

Promise<[AndroidElementInfo]>#

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。

Promise<void>#

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 布尔值 (可选)#
  
  切换是否绕过页面的内容安全策略。默认为 false。
- colorScheme null | "light" | "dark" | "no-preference" (可选)#
  
  模拟 'prefers-colors-scheme' 媒体功能，支持的值为 'light'、'dark'、'no-preference'。有关详细信息，请参阅 page.emulateMedia()。传递 null 将模拟重置为系统默认值。默认为 'light'。
- command 字符串 (可选)#
  
  可选的包名称，用于启动默认的 Android Chrome 以外的应用程序。
- deviceScaleFactor 数字 (可选)#
  
  指定设备缩放比例（可以理解为 dpr）。默认为 1。详细了解使用设备缩放比例模拟设备。
- extraHTTPHeaders 对象<字符串, 字符串> (可选)#
  
  包含与每个请求一起发送的附加 HTTP 头部的对象。默认为无。
- forcedColors null | "active" | "none" (可选)#
  
  模拟 'forced-colors' 媒体功能，支持的值为 'active'、'none'。有关详细信息，请参阅 page.emulateMedia()。传递 null 将模拟重置为系统默认值。默认为 'none'。
- geolocation 对象 (可选)#
  - latitude 数字
    
    纬度介于 -90 和 90 之间。
  - longitude 数字
    
    经度介于 -180 和 180 之间。
  - accuracy 数字 (可选)
    
    非负精度值。默认为 0。
- hasTouch 布尔值 (可选)#
  
  指定视窗是否支持触摸事件。默认为 false。详细了解移动模拟。
- httpCredentials 对象 (可选)#
  - username 字符串
  - password 字符串
  - origin 字符串 (可选)
    
    限制在特定来源（方案://主机:端口).
  - send "unauthorized" | "always" (可选)
    
    此选项仅适用于从相应的 APIRequestContext 发送的请求，不影响从浏览器发送的请求。'always' - Authorization 头部将带有基本身份验证凭据，并随每个 API 请求一起发送。'unauthorized - 凭据仅在收到带有 WWW-Authenticate 头部的 401（未授权）响应时发送。默认为 'unauthorized'。
  HTTP 身份验证的凭据。如果未指定来源，则用户名和密码将在未经授权的响应时发送到任何服务器。
- ignoreHTTPSErrors 布尔值 (可选)#
  
  是否忽略发送网络请求时的 HTTPS 错误。默认为 false。
- isMobile 布尔值 (可选)#
  
  是否考虑 meta viewport 标签并启用触摸事件。isMobile 是设备的一部分，因此您实际上不需要手动设置它。默认为 false，并且在 Firefox 中不受支持。详细了解移动模拟。
- javaScriptEnabled 布尔值 (可选)#
  
  在上下文中是否启用 JavaScript。默认为 true。详细了解禁用 JavaScript。
- locale 字符串 (可选)#
  
  指定用户区域设置，例如 en-GB、de-DE 等。区域设置将影响 navigator.language 值、Accept-Language 请求头部值以及数字和日期格式规则。默认为系统默认区域设置。详细了解我们模拟指南中的模拟。
- logger Logger (可选)#
  
  Playwright 日志记录的日志接收器。
- offline 布尔值 (可选)#
  
  是否模拟网络脱机。默认为 false。详细了解网络模拟。
- permissions 数组<字符串> (可选)#
  
  授予此上下文中的所有页面的权限列表。有关详细信息，请参阅 browserContext.grantPermissions()。默认为无。
- proxy 对象 (可选)添加于：v1.29#
  - server 字符串
    
    将用于所有请求的代理。支持 HTTP 和 SOCKS 代理，例如 http://myproxy.com:3128 或 socks5://myproxy.com:3128。简写形式 myproxy.com:3128 被认为是 HTTP 代理。
  - bypass 字符串 (可选)
    
    可选的逗号分隔的域名，用于绕过代理，例如 ".com, chromium.org, .domain.com"。
  - username 字符串 (可选)
    
    如果 HTTP 代理需要身份验证，则可选的用户名。
  - password 字符串 (可选)
    
    如果 HTTP 代理需要身份验证，则可选的密码。
  网络代理设置。
- recordHar 对象 (可选)#
  - omitContent 布尔值 (可选)
    
    可选设置，用于控制是否从 HAR 中省略请求内容。默认为 false。已弃用，请使用 content 策略代替。
  - content "omit" | "embed" | "attach" (可选)
    
    可选设置，用于控制资源内容管理。如果指定 omit，则不持久化内容。如果指定 attach，则资源将作为单独的文件或 ZIP 存档中的条目持久化。如果指定 embed，则内容将根据 HAR 规范内联存储在 HAR 文件中。对于 .zip 输出文件，默认为 attach；对于所有其他文件扩展名，默认为 embed。
  - path 字符串
    
    文件系统上用于写入 HAR 文件的路径。如果文件名以 .zip 结尾，则默认使用 content: 'attach'。
  - mode "full" | "minimal" (可选)
    
    当设置为 minimal 时，仅记录从 HAR 路由所需的信息。这省略了大小、时间、页面、Cookie、安全性和其他类型的 HAR 信息，这些信息在从 HAR 回放时不会使用。默认为 full。
  - urlFilter 字符串 | 正则表达式 (可选)
    
    用于过滤存储在 HAR 中的请求的全局或正则表达式模式。如果通过上下文选项提供了 baseURL 并且传递的 URL 是一个路径，则它将通过 new URL() 构造函数合并。默认为无。
  为所有页面启用 HAR 记录，写入 recordHar.path 文件。如果未指定，则不会记录 HAR。确保等待 browserContext.close() 以保存 HAR。
- recordVideo 对象 (可选)#
  - dir 字符串
    
    要将视频放入的目录路径。
  - size 对象 (可选)
    - width 数字
      
      视频帧宽度。
    - height 数字
      
      视频帧高度。
    录制视频的可选尺寸。如果未指定，则大小将等于缩放到适合 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 对象 (可选)#
  - width 数字
    
    页面宽度（以像素为单位）。
  - height 数字
    
    页面高度（以像素为单位）。
  模拟一致的窗口屏幕大小，该大小可通过 window.screen 在网页内使用。仅在 viewport 设置时使用。
- serviceWorkers "allow" | "block" (可选)#
  
  是否允许网站注册服务工作者。默认为 'allow'。
  - 'allow': 可以注册服务工作者。
  - 'block': Playwright 将阻止所有服务工作者的注册。
- strictSelectors 布尔值 (可选)#
  
  如果设置为 true，则为该上下文启用严格选择器模式。在严格选择器模式下，对暗示单个目标 DOM 元素的选择器的所有操作将在多个元素匹配选择器时抛出。此选项不会影响任何 Locator API（Locator 始终是严格的）。默认为 false。有关严格模式的更多信息，请参见 Locator。
- timezoneId 字符串 (可选)#
  
  更改上下文的时区。有关支持的时区 ID 列表，请参见 ICU 的 metaZones.txt。默认为系统时区。
- userAgent 字符串 (可选)#
  
  要在该上下文中使用的特定用户代理。
- videoSize 对象 (可选)#
  
  已弃用
  改用 recordVideo。
  - width 数字
    
    视频帧宽度。
  - height 数字
    
    视频帧高度。
- videosPath 字符串 (可选)#
  
  已弃用
  改用 recordVideo。
- viewport null | 对象 (可选)#
  - width 数字
    
    页面宽度（以像素为单位）。
  - height 数字
    
    页面高度（以像素为单位）。
  为每个页面模拟一致的视口。默认为 1280x720 视口。使用 null 禁用一致的视口模拟。了解有关视口模拟的更多信息。
  
  注意
  null 值会退出默认预设，使视口取决于操作系统定义的主机窗口大小。这使得测试执行变得不确定。

Promise<BrowserContext>#

longTap

添加于：v1.9

androidDevice.longTap

对由 selector 定义的小部件执行长按。

用法

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

参数

selector [AndroidSelector]#

要长按的选择器。
options Object (可选)
- timeout 数字 (可选)#
  
  最大时间，单位为毫秒，默认为 30 秒，传递 0 可禁用超时。默认值可以使用 androidDevice.setDefaultTimeout() 方法更改。

Promise<void>#

model

添加于：v1.9

androidDevice.model

设备型号。

用法

androidDevice.model();

字符串 #

open

添加于：v1.9

androidDevice.open

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

用法

await androidDevice.open(command);

参数

command 字符串 #

要执行的 shell 命令。

Promise<AndroidSocket>#

pinchClose

添加于：v1.9

androidDevice.pinchClose

以关闭方向捏合由 selector 定义的小部件。

用法

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

参数

selector [AndroidSelector]#

要捏合关闭的选择器。
percent 数字 #

捏合的大小，以小部件大小的百分比表示。
options Object (可选)
- speed 数字 (可选)#
  
  捏合的可选速度（以像素/秒为单位）。
- timeout 数字 (可选)#
  
  最大时间，单位为毫秒，默认为 30 秒，传递 0 可禁用超时。默认值可以使用 androidDevice.setDefaultTimeout() 方法更改。

Promise<void>#

pinchOpen

添加于：v1.9

androidDevice.pinchOpen

以打开方向捏合由 selector 定义的小部件。

用法

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

参数

selector [AndroidSelector]#

要捏合打开的选择器。
percent 数字 #

捏合的大小，以小部件大小的百分比表示。
options Object (可选)
- speed 数字 (可选)#
  
  捏合的可选速度（以像素/秒为单位）。
- timeout 数字 (可选)#
  
  最大时间，单位为毫秒，默认为 30 秒，传递 0 可禁用超时。默认值可以使用 androidDevice.setDefaultTimeout() 方法更改。

Promise<void>#

press

添加于：v1.9

androidDevice.press

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

用法

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

参数

selector [AndroidSelector]#

要在其中按下键的选择器。
key [AndroidKey]#

要按下的键。
options Object (可选)
- timeout 数字 (可选)#
  
  最大时间，单位为毫秒，默认为 30 秒，传递 0 可禁用超时。默认值可以使用 androidDevice.setDefaultTimeout() 方法更改。

Promise<空>#

push

添加于：v1.9

androidDevice.push

将文件复制到设备。

用法

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

参数

file 字符串 | Buffer #

文件路径或文件内容。
path 字符串 #

设备上的文件路径。
options Object (可选)
- mode 数字 (可选)#
  
  可选文件模式，默认值为 644 (rw-r--r--)。

Promise<空>#

screenshot

添加于：v1.9

androidDevice.screenshot

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

用法

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

参数

options Object (可选)
- path 字符串 (可选)#
  
  要保存图像的文件路径。如果 path 是相对路径，则它将相对于当前工作目录解析。如果没有提供路径，则图像将不会保存到磁盘。

Promise<Buffer>#

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 数字 #

滚动距离，以小部件大小的百分比表示。
options Object (可选)
- speed 数字 (可选)#
  
  可选的滚动速度，以像素/秒为单位。
- timeout 数字 (可选)#
  
  最大时间，单位为毫秒，默认为 30 秒，传递 0 可禁用超时。默认值可以使用 androidDevice.setDefaultTimeout() 方法更改。

Promise<空>#

serial

添加于：v1.9

androidDevice.serial

设备序列号。

用法

androidDevice.serial();

字符串 #

setDefaultTimeout

添加于：v1.9

androidDevice.setDefaultTimeout

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

用法

androidDevice.setDefaultTimeout(timeout);

参数

timeout 数字 #

最大时间（毫秒）。

shell

添加于：v1.9

androidDevice.shell

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

用法

await androidDevice.shell(command);

参数

command 字符串 #

要执行的 shell 命令。

Promise<Buffer>#

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 数字 #

滑动距离，以小部件大小的百分比表示。
options Object (可选)
- speed 数字 (可选)#
  
  可选的滑动速度，以像素/秒为单位。
- timeout 数字 (可选)#
  
  最大时间，单位为毫秒，默认为 30 秒，传递 0 可禁用超时。默认值可以使用 androidDevice.setDefaultTimeout() 方法更改。

Promise<空>#

tap

添加于：v1.9

androidDevice.tap

点击由 selector 定义的小部件。

用法

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

参数

selector [AndroidSelector]#

要长按的选择器。
options Object (可选)
- duration 数字 (可选)#
  
  可选的点击持续时间（毫秒）。
- timeout 数字 (可选)#
  
  最大时间，单位为毫秒，默认为 30 秒，传递 0 可禁用超时。默认值可以使用 androidDevice.setDefaultTimeout() 方法更改。

Promise<空>#

wait

添加于：v1.9

androidDevice.wait

等待特定 selector 出现在或消失，具体取决于 state。

用法

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

参数

selector [AndroidSelector]#

要等待的选择器。
options Object (可选)
- state "gone" (可选)#
  
  可选状态。可以是以下之一：
  - 默认 - 等待元素出现。
  - 'gone' - 等待元素消失。
- timeout 数字 (可选)#
  
  最大时间，单位为毫秒，默认为 30 秒，传递 0 可禁用超时。默认值可以使用 androidDevice.setDefaultTimeout() 方法更改。

Promise<空>#

waitForEvent

添加于：v1.9

androidDevice.waitForEvent

等待事件触发并将它的值传递到谓词函数中。当谓词返回真值时，返回。

用法

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

参数

event 字符串 #

事件名称，通常与 *.on(event) 中传递的名称相同。
optionsOrPredicate 函数 | 对象 (可选)#
- predicate 函数
  
  接收事件数据，并在等待应该解析时解析为真值。
- timeout 数字 (可选)
  
  最大等待时间，以毫秒为单位。默认值为 30000（30 秒）。传递 0 禁用超时。默认值可以使用 androidDevice.setDefaultTimeout() 更改。
接收事件的谓词或选项对象。可选。

Promise<对象>#

webView

添加于：v1.9

androidDevice.webView

此方法等待直到匹配 AndroidWebView 的选择器打开并返回它。如果已经存在与选择器匹配的打开 AndroidWebView，则立即返回。

用法

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

参数

selector 对象#
- pkg 字符串 (可选)
  
  可选的包标识符。
- socketName 字符串 (可选)
  
  可选的 webview 套接字名称。
options Object (可选)
- timeout 数字 (可选)#
  
  最大时间，单位为毫秒，默认为 30 秒，传递 0 可禁用超时。默认值可以使用 androidDevice.setDefaultTimeout() 方法更改。

Promise<AndroidWebView>#

webViews

添加于：v1.9

androidDevice.webViews

当前打开的 WebViews。

用法

androidDevice.webViews();

数组<AndroidWebView>#

属性

input

添加于：v1.9

androidDevice.input

用法

androidDevice.input

类型

Android 输入

事件

on('close')

添加于: v1.28

androidDevice.on('close')

设备连接关闭时发出。

用法

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

事件数据

Android 设备

on('webview')

添加于：v1.9

androidDevice.on('webview')

检测到新的 WebView 实例时发出。

用法

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

事件数据

Android WebView

方法​

close​

drag​

fill​

fling​

info​

installApk​

launchBrowser​

longTap​

model​

open​

pinchClose​

pinchOpen​

press​

push​

screenshot​

scroll​

serial​

setDefaultTimeout​

shell​

swipe​

tap​

wait​

waitForEvent​

webView​

webViews​

属性​

input​

事件​

on('close')​

on('webview')​

方法

close

drag

fill

fling

info

installApk

launchBrowser

longTap

model

open

pinchClose

pinchOpen

press

push

screenshot

scroll

serial

setDefaultTimeout

shell

swipe

tap

wait

waitForEvent

webView

webViews

属性

input

事件

on('close')

on('webview')