本頁面由 Cloud Translation API 翻譯而成。

MonkeyDevice

MonkeyRunner 類別代表執行 monkeyrunner 的工作站可存取的裝置或模擬器。

這個類別可用來控制 Android 裝置或模擬器。方法會傳送 UI 事件、擷取資訊、安裝及移除應用程式，以及執行應用程式。

你通常不需要建立 MonkeyDevice 的執行個體。而是使用 MonkeyRunner.waitForConnection()，進而從連線的裝置或模擬器建立新物件。下列個體一般不會用到：

newdevice = MonkeyDevice()

而是改用：

newdevice = MonkeyRunner.waitForConnection()

摘要

常數
string	DOWN	使用這個字串搭配 `press()` 或 `touch()` 的 `type` 引數，以傳送 DOWN 事件。
string	UP	使用這個字串搭配 `press()` 或 `touch()` 的 `type` 引數，以傳送 UP 事件。
string	DOWN_AND_UP	使用這個字串搭配 `press()` 或 `touch()` 的 `type` 引數，在 UP 事件後立即傳送 DOWN 事件。

方法
void	broadcastIntent(string uri, string action, string data, string mimetype, iterable categories dictionary extras, component component, iterable flags) 本語法將以應用程式的角色，向這部裝置廣播「意圖」。
void	drag(tuple start, tuple end, float duration, integer steps) 本語法將在裝置的螢幕上，模擬輕觸、按住及滑動的手勢。
object	getProperty(string key) 根據系統環境變數名稱回傳該裝置的值。在本方法的詳細說明中，已列出可用的變數名稱。
object	getSystemProperty(string key) . 相當於 `adb shell getprop <key>. This is provided for use by platform developers.` 的 API
void	installPackage(string path) 本語法將在這部裝置上安裝 packageFile 中的 Android 應用程式或測試套件。先前安裝的應用程式或測試套件將被取代。
dictionary	instrument(string className、dictionary args) 利用 Android 檢測工具執行特定元件，其回傳的結果與執行元件會是相同的字典資料結構。執行裝置必須先安裝好該元件。
void	press(string name,dictionary type) 本語法會將把類型指定的 key event 傳送至按鍵碼指定的 key。
void	(string into) 本語法將用 bootload 類型指定的系統啟動載入程式，重新啟動此裝置。
void	removePackage(string package) 將這部裝置中指定的套件與其資料和快取一併刪除。
object	shell(string cmd) 本裝置將執行 `adb` 殼層指令，並回傳結果 (如果有的話)。
void	startActivity(string uri, string action, string data, string mimetype, iterable categories dictionary extras, component component, flags) 本語法會將透過既有引數建構的「意圖」，在這部裝置上啟用活動。
`MonkeyImage`	takeSnapshot() 本語法將擷取裝置整個螢幕緩衝區，並得到包含當前螢幕畫面的 `MonkeyImage` 物件。
void	touch(integer x, integer y, integer type) 本語法會將類型指定的觸控事件傳送至 x 和 y 在螢幕上的位置。
void	type(string message) 使用本語法會將把訊息中的字元以鍵盤輸入的方式傳送至這部裝置。相當於使用 key event 類型的 `DOWN_AND_UP` 呼叫 `message` 每個按鍵碼的 `press()`。
void	wake() 本語法將喚醒這部裝置的螢幕。

常數

string DOWN

press() 或 touch() 的值。本語法在傳送 DOWN 事件類型至裝置時，可指明按下按鍵或輕觸螢幕。

string UP

press() 或 touch() 的值。本語法在傳送 UP 事件類型至裝置時，指明要發布的 key，或將畫面往上滑。

string DOWN_AND_UP

press()、touch() 或 type() 值。在傳送 DOWN 事件類型之後，緊接著傳送 UP 事件類型至裝置。本語法將指明要按下的按鍵，或是按一下螢幕。

公用方法

void broadcastIntent(string uri, string action, string data, string mimetype, iterable categories, dictionary extras, component component, iterable flags)

本語法將以應用程式的角色，向這部裝置廣播「意圖」。如要瞭解更多引數，請參閱 Intent。

引數

uri	「意圖」的 URI。請參閱 `Intent.setData()`。
action	請參閱 `Intent.setAction()` 以瞭解本「意圖」的動作。
data	請參閱 `Intent.setData()` 以瞭解本「意圖」的 URI 資料。
MIME 類型	如需瞭解「意圖」的 MIME 類型，請參閱 `Intent.setType()`。
categories	可疊代資料結構包含了定義本「意圖」類別的字串 (請參閱 `Intent.addCategory()`)。
extras	本「意圖」額外的字典結構資料 (如需範例，請參閱 `Intent.putExtra()`)。每個字典項目的鍵值應為字串。項目的鍵值可以是任何簡易資料或任何一種結構化資料。
component	請參閱 `ComponentName` 瞭解本「意圖」的元件。如果使用這個引數，系統會將「意圖」導向特定 Android 套件中的特定類別。
flag	迭代資料架構，包含「意圖」處理方式的控制標記 (請參閱 `Intent.setFlags()`)。

void drag(tuple start, tuple end, float duration, integer steps)

本語法將在裝置的螢幕上模擬輕觸、按住及滑動的手勢。

引數

start	拖曳手勢的起點，設定語法為 tuple (x,y)，其中 x 和 y 需為整數。
end	拖曳手勢的結束點，設定語法為 tuple (x,y)，其中 x 和 y 需為整數。
duration	設定拖曳手勢的持續時間 (單位為秒)。預設是 1.0 秒。
steps	從起點到終點需要的步數。預設值為 10 步。

object getProperty(string key)

根據系統環境變數名稱回傳該裝置的值。

引數

key	系統環境變數的名稱。可用變數名稱皆列於表 1 屬性變數名稱可見於本主題結尾處。

回傳

變數的值。資料格式會因要求的變數而有所變化。

object getSystemProperty(string key)

與 getProperty() 語法相同。

引數

key	系統環境變數的名稱。可用變數名稱皆列於表 1 屬性變數名稱。

回傳

變數的值。資料格式會因要求的變數而有所變化。

void installPackage(string path)

本語法將在這部裝置上，安裝 packageFile 中的 Android 應用程式或測試套件。先前安裝的應用程式或測試套件將被取代。

引數

path	即將安裝的 `.apk` 檔案完整路徑和檔案名稱。

dictionary instrument(string className, dictionary args)

利用 Android 檢測工具執行特定元件，其回傳的結果與執行元件會是相同的字典資料結構。執行裝置必須先安裝好該元件。

您可以使用這個方法執行測試案例，其類別屬於 Android 測試案例類別之一。如要瞭解如何透過 Android 測試架構進行單元測試，請參閱「測試基礎知識」一文。

引數

className	已安裝在本裝置的 Android 元件名稱 (如標準格式套件/類別) 套件名稱與本裝置 `.apk` 檔案的 Android 套件名相同，且類別名稱為該檔案中　Android 元件的類別名稱 (Activity、ContentProvider、Service 或 BroadcastReceiver)。套件和類別的名稱都必須完全符合相關規定。如需詳情，請參閱 `ComponentName`。
args	字典，內容包含標記和值。開始測試時，字典的值會傳送至元件。如果標記未設定任何值，請將其字典值設為空白字串。

回傳

字典，內容包含元件輸出的內容。而字典內容由元件本身決定。

在元件名稱引數中，如使用 InstrumentationTestRunner 作為類別名稱，那麼字典會包含單一鍵「stream」。而「stream」的值，會包含測試輸出內容的 string，形同從指令列執行 InstrumentationTestRunner 一樣。如需此輸出內容的格式說明，請參閱「使用其他 IDE 中的測試」一節。

void press(string name, integer type)

type 指定的 key event 將傳送至 keycode 指定的 key。

引數

name	即將傳送的按鍵碼名稱。如需按鍵碼名單，請參閱 `KeyEvent`。使用按鍵碼名稱，而非其代表的整數值。
type	即將傳送的 key event 類型。可以使用的值為 `DOWN`、`UP` 和 `DOWN_AND_UP`。

void reboot(string bootloadType)

使用 bootloadType 指定的系統啟動載入程式，重新啟動這部裝置。

引數

into	用於重新啟動的系統啟動載入程式類型。可以使用的值有「bootboot」、「recovery」或「None」。

void removePackage(string package)

將這部裝置中指定的套件與其資料和快取一併刪除。

引數

package	這部裝置上 `.apk` 檔案的 Android 套件名稱。

object shell(string) cmd)

本裝置將執行 adb 殼層指令，並回傳結果 (如果有的話)。

引數

cmd	將在 `adb` 殼層中執行的指令。Android Debug Bridge 主題會說明這些指令的形式。

回傳

指令執行的結果 (如果有的話)。回傳結果的格式會由指令決定。

void startActivity(string uri, string action, string data, string mimetype, iterable categories dictionary extras, component component, iterable flags)

如需在這部裝置上啟用活動，請傳送以既有引數建構的「意圖」。

引數

uri	如需瞭解「意圖」的 URI。請參閱 `Intent.setData()`。
action	如需瞭解「意圖」的動作，請參閱 `Intent.setAction()`。
data	如需瞭解「意圖」的資料 URI，請參閱 `Intent.setData()`。
MIME 類型	如需瞭解「意圖」的 MIME 類型，請參閱 `Intent.setType()`。
categories	一種可疊代資料結構，其中包含定義「意圖」類別的字串 (請參閱 `Intent.addCategory()`)。
extras	「意圖」的額外資料字典，如需範例，請參閱 `Intent.putExtra()`。每個字典項目的鍵值應為字串。項目的鍵值可以是任何簡易資料或任何一種結構化資料。
component	「意圖」的元件 (請參閱 `ComponentName`)。這個引數會將「意圖」導向特定 Android 套件中的特定類別。
flag	迭代資料架構，包含「意圖」處理方式的控制標記 (請參閱 `Intent.setFlags()`)。

`MonkeyImage`takeSnapshot()

本語法會將擷取裝置整個螢幕緩衝區，並得到包含當前螢幕畫面的物件。

回傳

包含當前畫面的 MonkeyImage 物件。

void touch(integer x, integer y, string type)

本語法會將類型指定的觸控事件傳送至 x 和 y 在螢幕上的位置。

引數

x	觸控在實際裝置像素的水平位置，以裝置螢幕當前方向為準，從螢幕左側開始計算定位。
y	觸控在實際裝置像素的垂直位置，以裝置螢幕當前方向為準，從螢幕頂端開始計算定位。
type	即將傳送的 key event 類型。可以使用的值為 `DOWN`、`UP` 和 `DOWN_AND_UP`。

void type(string message)

使用本語法會將把訊息中的字元以鍵盤輸入的方式傳送至這部裝置。相當於使用 key event 類型 DOWN_AND_UP 呼叫 message 每個按鍵碼的 press()。

引數

message	字串，包含即將傳送的字元。

void wake()

本語法將喚醒這部裝置的螢幕畫面。

附錄

表 1 使用 getProperty()和 getSystemProperty() 的屬性變數名稱。

屬性群組	屬性	說明	附註
`build`	`board`	裝置主機系統的代碼名稱	查看 `Build`
	`brand`	自訂作業系統的電信業者或供應商。
	`device`	裝置設計名稱。
	`fingerprint`	當前執行版本的 ID。
	`host`
	`ID`	變更清單的編號或標籤。
	`model`	使用者看得到的裝置名稱。
	`product`	產品完整名稱。
	`tags`	用於說明版本的標記，以逗號作為分隔，例如「未簽署」和「偵錯」。
	`type`	用於說明版本類型，例如「user」或「eng」。
	`user`
	`CPU_ABI`	原生程式碼指示集的名稱，格式兼用 CPU 類型以及 ABI 慣例。
	`manufacturer`	產品/硬體製造商。
	`version.incremental`	版本控制系統所使用的內部程式碼，用來指明軟體的版本。
	`version.release`	使用者看到的軟體版本名稱。
	`version.sdk`	使用者看到的 SDK 版本，與該作業系統版本相關。
	`version.codename`	目前的開發代碼名稱，如已推出此版本的軟體，則為「REL」。
`display`	`width`	裝置的螢幕寬度 (單位為像素)。	詳情請參閱 `DisplayMetrics`。
	`height`	裝置的螢幕高度 (單位為像素)。
	`density`	螢幕的邏輯密度。這項因素將影響如何調整 DIP (密度獨立像素)，以符合裝置螢幕的解析度。調整後，1 DIP 等同於 160 像素/英寸螢幕中的 1 個像素。例如，在 160 dpi 的螢幕上，密度 = 1.0，而 120 dpi 的螢幕，其密度 = 0.75。此數值不會完全符合實際螢幕大小，但會隨著螢幕 DPI 的大幅變動進行調整。詳情請參閱 `density`。
`am.current`	`package`	當前執行套件的 Android 套件名稱。	`am.current` 鍵會傳回目前執行「活動」的資訊。
	`action`	當前活動的動作。與套件資訊清單中 `action` 元素的 `name` 屬性有相同格式。
	`comp.class`	目前啟用「活動」的元件類別名稱。詳情請參閱 `comp.package`。
	`comp.package`	目前啟用「活動」的元件套件名稱。元件將由套件名稱與其包含的類別名稱來指定。
	`data`	啟用當前「活動」之「意圖」所含的資料 (如果有的話)。
	`categories`	啟用當前「活動」之「意圖」所指定的類別。
`clock`	`realtime`	重新啟動裝置後經過的毫秒數，包括休眠時間。	詳情請參閱 `SystemClock`。
	`uptime`	重新啟動裝置後經過的毫秒數，不包括休眠時間
	`millis`	當前時間，以 UNIX Epoch 紀元時間為始 (單位為毫秒)。