AndroidDevice

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

在特定的 selector 輸入框中填入 text。

用法

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 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'。
  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 (選用)#
  
  要啟動的可選套件名稱，而非預設的 Android 版 Chrome。
- proxy Object (選用)加入於：v1.29#
  - server string
    
    要用於所有請求的 Proxy。支援 HTTP 和 SOCKS Proxy，例如 http://myproxy.com:3128 或 socks5://myproxy.com:3128。簡短格式 myproxy.com:3128 會被視為 HTTP Proxy。
  - bypass string (選用)
    
    要略過 Proxy 的可選逗號分隔網域，例如 ".com, chromium.org, .domain.com"。
  - username string (選用)
    
    如果 HTTP Proxy 需要驗證，則使用的可選使用者名稱。
  - password string (選用)
    
    如果 HTTP Proxy 需要驗證，則使用的可選密碼。
  網路 Proxy 設定。
- 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 或 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 | "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 值會停用預設的預設值，使 viewport 取決於作業系統定義的主機視窗大小。這會使測試的執行變成非決定性的。

回傳

Promise<BrowserContext>#

longTap

加入於：v1.9

androidDevice.longTap

對由 selector 定義的小工具執行長按操作。

用法

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

參數

selector [AndroidSelector]#

要點擊的選擇器。
options Object (選用)
- timeout number (選填)#
  
  最大等待時間，單位為毫秒，預設為 30 秒，傳遞 0 以停用逾時。預設值可以使用 androidDevice.setDefaultTimeout() 方法變更。

回傳

Promise<void>#

model

加入於：v1.9

androidDevice.model

裝置型號。

用法

androidDevice.model();

回傳

string #

open

加入於：v1.9

androidDevice.open

在裝置上的 shell 中啟動程序，並傳回一個 socket 以與啟動的程序進行通訊。

用法

await androidDevice.open(command);

參數

command string #

要執行的 Shell 命令。

回傳

Promise<AndroidSocket>#

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

回傳

Promise<void>#

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

回傳

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 number (選填)#
  
  最大等待時間，單位為毫秒，預設為 30 秒，傳遞 0 以停用逾時。預設值可以使用 androidDevice.setDefaultTimeout() 方法變更。

回傳

Promise<void>#

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

回傳

Promise<void>#

screenshot

加入於：v1.9

androidDevice.screenshot

傳回包含裝置螢幕截圖的 buffer。

用法

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

參數

options Object (選用)
- path string (選填)#
  
  儲存影像的檔案路徑。如果 path 是相對路徑，則會相對於目前工作目錄解析。如果未提供路徑，則影像不會儲存到磁碟。

回傳

Promise<Buffer>#

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

回傳

Promise<void>#

serial

加入於：v1.9

androidDevice.serial

裝置序號。

用法

androidDevice.serial();

回傳

string #

setDefaultTimeout

加入於：v1.9

androidDevice.setDefaultTimeout

此設定將變更所有接受 timeout 選項的方法的預設最大時間。

用法

androidDevice.setDefaultTimeout(timeout);

參數

timeout number #

最大時間 (毫秒)

shell

加入於：v1.9

androidDevice.shell

在裝置上執行 shell 命令並傳回其輸出。

用法

await androidDevice.shell(command);

參數

command string #

要執行的 Shell 命令。

回傳

Promise<Buffer>#

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

回傳

Promise<void>#

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

回傳

Promise<void>#

wait

加入於：v1.9

androidDevice.wait

等待特定的 selector 出現或消失，取決於 state。

用法

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

參數

selector [AndroidSelector]#

要等待的選擇器。
options Object (選用)
- state "gone" (選填)#
  
  選填的狀態。可以是
  - 預設 - 等待元素出現。
  - 'gone' - 等待元素不存在。
- timeout number (選填)#
  
  最大等待時間，單位為毫秒，預設為 30 秒，傳遞 0 以停用逾時。預設值可以使用 androidDevice.setDefaultTimeout() 方法變更。

回傳

Promise<void>#

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() 變更。
接收事件的述詞或選項物件。選填。

回傳

Promise<Object>#

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 socket 名稱。
options Object (選用)
- timeout number (選填)#
  
  最大等待時間，單位為毫秒，預設為 30 秒，傳遞 0 以停用逾時。預設值可以使用 androidDevice.setDefaultTimeout() 方法變更。

回傳

Promise<AndroidWebView>#

webViews

加入於：v1.9

androidDevice.webViews

目前開啟的 WebViews。

用法

androidDevice.webViews();

回傳

Array<AndroidWebView>#

Properties

input

加入於：v1.9

androidDevice.input

用法

androidDevice.input

Type

AndroidInput

Events

on('close')

Added in: v1.28

androidDevice.on('close')

當裝置連線關閉時發出。

用法

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

Event data

AndroidDevice

on('webview')

加入於：v1.9

androidDevice.on('webview')

當偵測到新的 WebView 實例時發出。

用法

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

Event data

AndroidWebView

方法​

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​

Properties​

input​

Events​

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

Properties

input

Events

on('close')

on('webview')