傳送模擬器主控台指令

每部執行中的虛擬裝置都提供主控台,可讓您查詢及控管模擬裝置環境。舉例來說,您可以在應用程式透過模擬器執行時,使用主控台管理通訊埠重新導向、網路特性和電話通訊事件。

如要執行下列指令,您必須有執行中的模擬器。如要進一步瞭解如何執行模擬器,請參閱「在 Android Emulator 上執行應用程式」及「透過指令列啟動模擬器」。

啟動及停止主控台工作階段

如要存取控制台並輸入指令,請在終端機視窗中使用 telnet 連線至控制台通訊埠,並提供驗證權杖。只要主控台顯示「OK」,就表示可以接受指令。主控台並不會提供一般的提示。

如何連線至執行中虛擬裝置的主控台:

  1. 開啟終端機視窗,然後輸入以下指令:

    telnet localhost console-port
    

    在獨立視窗中執行時,模擬器視窗標題會列出主控台通訊埠號碼,但在工具視窗中執行時不會。舉例來說,如果是使用主控台通訊埠 5554 的模擬器,則視窗標題可能是 Pixel8_API_34:5554。此外,adb devices 指令會輸出執行中的虛擬裝置及其主控台通訊埠號碼清單。詳情請參閱「查詢裝置」相關說明。

    注意:模擬器會監聽通訊埠 5554 至 5585 的連線,且僅接受來自 localhost 的連線。

  2. 主控台顯示 OK 後,輸入 auth auth_token 指令。

    模擬器主控台會要求進行驗證,通過驗證後,您才能輸入主控台指令。auth_token 必須與主目錄中的 .emulator_console_auth_token 檔案內容相符。

    如果該檔案不存在,telnet localhost console-port 指令會建立該檔案,其中包含隨機產生的驗證權杖。如要停用驗證功能,請將權杖從 .emulator_console_auth_token 檔案中刪除,或是建立空白檔案 (如果檔案不存在)。

  3. 連線至主控台後,輸入主控台指令。

    輸入 help、help command 或 help-verbose 可查看主控台指令清單,並瞭解特定指令。

  4. 如要結束主控台工作階段,請輸入 quit 或 exit。

工作階段範例如下:

$ telnet localhost 5554
Trying ::1...
telnet: connect to address ::1: Connection refused
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
Android Console: Authentication required
Android Console: type 'auth <auth_token>' to authenticate
Android Console: you can find your <auth_token> in
'/Users/me/.emulator_console_auth_token'
OK
auth 123456789ABCdefZ
Android Console: type 'help' for a list of commands
OK
help-verbose
Android console command help:
    help|h|?         Prints a list of commands
    help-verbose     Prints a list of commands with descriptions
    ping             Checks if the emulator is alive
    automation       Manages emulator automation
    event            Simulates hardware events
    geo              Geo-location commands
    gsm              GSM related commands
    cdma             CDMA related commands
    crash            Crashes the emulator instance
    crash-on-exit    Simulates crash on exit for the emulator instance
    kill             Terminates the emulator instance
    restart          Restarts the emulator instance
    network          Manages network settings  (ethernet and cellular only)
    power            Power related commands
    quit|exit        Quits control session
    redir            Manages port redirections
    sms              SMS related commands
    avd              Controls virtual device execution
    qemu             QEMU-specific commands
    sensor           Manages emulator sensors
    physics          Manages physical model
    finger           Manages emulator finger print
    debug            Controls the emulator debug output tags
    rotate           Rotates the screen clockwise by 90 degrees
    screenrecord     Records the emulator's display
    fold             Folds the device
    unfold           Unfolds the device
    multidisplay     Configures the multi-display
    nodraw           turn on/off NoDraw mode. (experimental)
    resize-display   resize the display resolution to the preset size
    virtualscene-image  customize virtualscene image for virtulscene camera
    proxy            manage network proxy server settings
    phonenumber      set phone number for the device

try 'help <command>' for command-specific help
OK
exit
Connection closed by foreign host.

啟動後便不須控制的指令

如果不需要開啟工作階段,請使用 adb emu 快速指令,這會執行指令並立即將控制權交回叫用殼層:

adb emu command commandParameter

使用 adb emu 叫用會連線至可用的模擬器。如果同時執行多個模擬器,則必須傳入指定模擬器的序號:

adb -s emulator-serial emu command commandParameter

模擬器指令參考資料

以下清單說明模擬器主控台指令,以及指令的參數和值:

一般指令

  • avd {stop| start| status| name} 查詢、控制及管理虛擬裝置,相關參數如下:

    • stop:停止執行裝置。
    • start:開始執行裝置。
    • status:查詢虛擬裝置狀態 (可能是執行中或已停止)。
    • name:查詢虛擬裝置名稱。
  • avd snapshot {list| save name| load name| delete name}:利用快照儲存或還原裝置狀態,相關參數如下:

    • list:列出所有已儲存的快照。
    • save name:將快照儲存為 name。
    • load name:載入指定快照。
    • delete name:刪除指定快照。

    以下範例會使用 firstactivitysnapshot 名稱儲存快照:

    avd snapshot save firstactivitysnapshot
    
  • fold:摺疊裝置以顯示較小的螢幕設定 (如果是摺疊式裝置且目前未處於摺疊狀態)。

  • unfold:展開裝置以顯示較大的螢幕設定 (如果是摺疊式裝置且目前處於摺疊狀態)。

  • kill:終止虛擬裝置。

  • ping:檢查虛擬裝置是否正在執行。

  • rotate:將 AVD 逆時針旋轉 45 度。

讓模擬器停止運作

  • crash:在應用程式執行期間讓模擬器停止運作。

  • crash-on-exit:在應用程式結束時讓模擬器停止運作。

偵錯標記

  • debug tags ...:啟用或停用模擬器特定部分的偵錯訊息。tags 參數必須是執行 emulator -help-debug-tags 時顯示的偵錯標記清單所含的值。如要進一步瞭解 -help-debug-tags 選項,請參閱常用選項表格。以下範例會啟用 radio 標記:

    debug radio
    

通訊埠重新導向

  • redir list:列出目前的通訊埠重新導向。

  • redir add protocol:host-port:guest-port 新增通訊埠重新導向,相關參數如下:

    • protocol:必須是 tcp 或 udp。
    • host-port:要在主機上開啟的通訊埠號碼。
    • guest-port:要在模擬器上將資料轉送過去的通訊埠號碼。
  • redir del protocol:host-port 刪除通訊埠重新導向。

    • protocol:必須是 tcp 或 udp。
    • host-port:要在主機上開啟的通訊埠號碼。

地理位置

將 GPS 定位傳送至模擬器,設定向模擬器中執行的應用程式回報的地理位置。

虛擬裝置開始執行後,您隨即可發出下列任一地理位置指令。模擬器會建立模擬位置提供者,藉此設定您輸入的位置。這個提供者會回應由應用程式設定的位置事件監聽器,同時也會向 LocationManager 提供位置資訊。所有應用程式都可呼叫 LocationManager.getLastKnownLocation("gps") 查詢位置管理員,取得模擬裝置目前的 GPS 定位。

  • geo fix longitude latitude [altitude] [satellites] [velocity]:將 GPS 定位傳送至模擬器。請以十進制度數指定經緯度。請使用介於 1 到 12 之間的數字,指定要用於判斷位置的衛星數量,並指定高度 (以公尺為單位) 和速度 (以節為單位)。

  • geo nmea sentence:將 NMEA 0183 句子傳送至模擬裝置,就像從模擬 GPS 數據機傳送一樣。句子開頭必須是「$GP」。目前僅支援「$GPGGA」和「$GPRCM」語句。以下範例是 GPGGA (全球定位系統定位資料) 句子,可取得 GPS 接收器的時間、位置和定位資料:

    geo nmea $GPGGA,hhmmss.ss,llll.ll,a,yyyyy.yy,a,x,xx,x.x,x.x,M,x.x,M,x.x,xxxx
    

假硬體事件

模擬器控制台的硬體事件子系統可讓您模擬與裝置的任何實體互動。包括實體按鈕、螢幕觸控/手勢、旋轉撥號、搖桿輸入和硬體切換。

  • event types:列出所有假事件類型。如果事件包含代碼,右側的括號中會列出代碼數量。輸出內容範例:

    event types
    event <type> can be an integer or one of the following aliases:
        EV_SYN
        EV_KEY    (405 code aliases)
        EV_REL    (2 code aliases)
        EV_ABS    (27 code aliases)
        EV_MSC
        EV_SW     (4 code aliases)
        EV_LED
        EV_SND
        EV_REP
        EV_FF
        EV_PWR
        EV_FF_STATUS
        EV_MAX
    OK
    
  • event send types [types ...]:傳送一或多個假事件類型。

  • event codes type:列出指定假事件類型的事件代碼。

  • event send type[:code]:[value] [...]:傳送一或多個包含選用代碼和代碼值的假事件。

EV_KEY — 按鍵代碼參考資料

EV_KEY 事件類型用於模擬按鈕按下和放開。下表將龐大的支援按鍵代碼清單分成邏輯類別。對於每個按鍵代碼,調度 1 值會模擬按下動作,而 0 值則會模擬放開動作。2 值代表按鍵重複。

子表 A:Android 系統金鑰
程式碼 說明
KEY_HOME 主畫面按鈕觸發條件
KEY_BACK 返回按鈕觸發條件
KEY_MENU 選單 (溢位) 按鈕
KEY_POWER 電源鍵 (按/長按)
KEY_VOLUMEUP 調高音量按鈕觸發條件
KEY_VOLUMEDOWN 調低音量按鈕觸發條件
KEY_CAMERA 實體相機快門按鈕
KEY_FOCUS 相機自動對焦快門
KEY_SEARCH 搜尋按鈕觸發條件
KEY_SLEEP 睡眠指令觸發條件
KEY_WAKEUP 喚醒指令觸發條件
KEY_NOTIFICATION 開啟通知導覽匣
KEY_MUTE 將系統音訊輸出設為靜音
KEY_MICMUTE 將麥克風輸入設為靜音
KEY_BRIGHTNESSDOWN 調低螢幕亮度
KEY_BRIGHTNESSUP 調高螢幕亮度
KEY_PHONE 開啟預設撥號應用程式
KEY_SEND 傳送或發起通話
KEY_HEADSETHOOK 耳機掛鉤 (接聽/掛斷)
KEY_SCREEN 螢幕保護程式啟用指令
KEY_CONFIG 設定系統選單
KEY_SWITCHVIDEOMODE 切換系統影片模式
KEY_KBDILLUMTOGGLE 切換鍵盤背光
子表 B:媒體和播放控制項
程式碼 說明
KEY_PLAYPAUSE 切換播放和暫停狀態
KEY_PLAY 開始播放媒體
KEY_PAUSECD 暫停播放 CD
KEY_STOPCD 停止播放 CD
KEY_NEXTSONG 跳到下一首曲目
KEY_PREVIOUSSONG 跳到上一首曲目
KEY_REWIND 倒轉目前曲目
KEY_FASTFORWARD 快轉目前播放的曲目
KEY_RECORD 記錄觸發條件指令
KEY_SHUFFLE 切換隨機播放
KEY_REPEAT 切換重複播放
KEY_MEDIA 媒體鍵觸發條件
子表 C:導覽和一般鍵盤
程式碼 說明
KEY_UP D-Pad 向上鍵
KEY_DOWN D-Pad 向下鍵
KEY_LEFT D-Pad 向左鍵
KEY_RIGHT D-Pad 向右鍵
KEY_PAGEUP 向上捲動頁面
KEY_PAGEDOWN 向下捲動頁面
KEY_INSERT 插入鍵觸發條件
KEY_DELETE 刪除按鍵觸發條件
KEY_ENTER Enter 鍵觸發
KEY_ESC Escape 鍵觸發條件
KEY_TAB Tab 鍵觸發條件
KEY_SPACE 空格鍵觸發條件
KEY_BACKSPACE Backspace 鍵觸發條件
KEY_CLEAR 清除輸入緩衝區
KEY_CANCEL 取消進行中的動作
KEY_OK 確認/確定所選項目
KEY_SELECT 選取項目觸發條件
KEY_GOTO 前往指定地點
KEY_HELP 存取說明內容
子表 D:英數字元和撥號鍵盤符號
  • 標準字母:KEY_A 到 KEY_Z (26 個代碼)。
  • 數字鍵盤按鍵:KEY_1 到 KEY_0 (10 個代碼)。
程式碼 字元符號
KEY_COMMA ,
KEY_DOT .
KEY_SLASH /
KEY_SEMICOLON ;
KEY_APOSTROPHE '
KEY_GRAVE \`
KEY_MINUS -
KEY_EQUAL =
KEY_LEFTBRACE [
KEY_RIGHTBRACE ]
KEY_BACKSLASH \
KEY_KPASTERISK * (數字鍵盤)
KEY_KPPLUS + (數字鍵盤)
KEY_KPMINUS - (數字鍵盤)
KEY_KPDOT . (數字鍵盤)
KEY_KPSLASH / (數字鍵盤)
KEY_KPENTER Enter 鍵 (數字鍵盤)
KEY_KPEQUAL = (數字鍵盤)
KEY_KPCOMMA , (數字鍵盤)
KEY_KPJPCOMMA , (日文鍵盤配置)
KEY_KPLEFTPAREN ( (數字鍵盤)
KEY_KPRIGHTPAREN ) (數字鍵盤)
KEY_KPPLUSMINUS ± (數字鍵盤)
子表 E:輔助鍵和功能鍵
  • 標準功能鍵:KEY_F1 到 KEY_F24 (24 個代碼)。
程式碼 說明
KEY_LEFTSHIFT 左 Shift 鍵盤輔助鍵
KEY_RIGHTSHIFT 右 Shift 鍵盤輔助鍵
KEY_LEFTCTRL 左 Control 鍵盤輔助鍵
KEY_RIGHTCTRL 右側 Control 鍵盤輔助鍵
KEY_LEFTALT 左 Alt 鍵盤輔助鍵
KEY_RIGHTALT 右側 Alt 鍵盤輔助鍵
KEY_LEFTMETA 左側 Meta/Command 鍵
KEY_RIGHTMETA 右 Meta/Command 鍵
KEY_CAPSLOCK Caps Lock 鍵盤切換
KEY_NUMLOCK Num Lock 鍵盤切換
KEY_SCROLLLOCK Scroll Lock 鍵盤切換鍵
KEY_COMPOSE 撰寫角色小幫手
KEY_FN 實體鍵盤 FN 鍵
KEY_FN_ESC 功能鍵組合
KEY_FN_1 特殊功能快速鍵 1
KEY_FN_2 特殊功能快速鍵 2
KEY_FN_D 特殊功能快速鍵 D
KEY_FN_E 特殊功能快速鍵 E
KEY_FN_F 特殊功能快速鍵 F
KEY_FN_S 特殊功能快速鍵 S
KEY_FN_B 特殊功能快速鍵 B
子表 F:遊戲手把和搖桿
程式碼 說明
BTN_A/BTN_B/BTN_C 控制器正面按鈕 A/B/C
BTN_X/BTN_Y/BTN_Z 控制器正面按鈕 X/Y/Z
BTN_START 遊戲手把「開始」選單按鈕
BTN_SELECT 遊戲手把「選取」按鈕
BTN_MODE 控制器模式切換
BTN_TL/BTN_TR 左/右肩部緩衝器
BTN_TL2/BTN_TR2 左/右類比扳機
BTN_THUMBL/BTN_THUMBR 按一下左/右側搖桿
BTN_DPAD_UP 遊戲手把 D-pad 向上鍵觸發
BTN_DPAD_DOWN 遊戲手把 D-pad 向下鍵觸發
BTN_DPAD_LEFT 遊戲手把 D-pad 左側扳機鍵
BTN_DPAD_RIGHT 遊戲手把 D-pad 右側扳機鍵
BTN_THUMB 搖桿主要拇指扳機
BTN_TOP/BTN_TOP2 搖桿上方頂端按鈕
BTN_PINKIE 搖桿小指按鈕觸發
BTN_BASE 至 _BASE6 搖桿平台底座按鈕
BTN_DEAD 閒置遊戲手把死區標記
BTN_TRIGGER 實體搖桿手動觸發
BTN_JOYSTICK 一般搖桿輸入代碼
子表 G:滑鼠、觸控和觸控筆輸入
程式碼 說明
BTN_MOUSE 一般滑鼠游標事件
BTN_LEFT 按一下滑鼠左鍵
BTN_RIGHT 按一下滑鼠右鍵
BTN_MIDDLE 按一下滑鼠中鍵
BTN_SIDE 導覽側邊按鍵觸發條件
BTN_EXTRA 額外滑鼠按鈕觸發條件
BTN_FORWARD 點按瀏覽器前進鍵
BTN_BACK 點按瀏覽器返回按鈕
BTN_TASK 系統工作切換工具按鍵
BTN_TOUCH 偵測到螢幕實體接觸
BTN_STYLUS 主動式觸控筆接近
BTN_STYLUS2 觸控筆上的次要筆桿按鈕
BTN_TOOL_PEN 觸控筆工具 ID
BTN_TOOL_RUBBER 觸控筆橡皮擦工具 ID
BTN_TOOL_BRUSH 畫家筆刷工具 ID
BTN_TOOL_PENCIL 製圖鉛筆工具 ID
BTN_TOOL_AIRBRUSH 噴槍彩繪工具 ID
BTN_TOOL_FINGER 觸控螢幕手指接觸
BTN_TOOL_MOUSE 外接滑鼠工具 ID
BTN_TOOL_LENS 光學放大鏡鏡頭工具
BTN_TOOL_DOUBLETAP 手勢輕觸兩下速度旗標
BTN_TOOL_TRIPLETAP 手勢輕觸三下速度旗標
子表 H:應用程式捷徑
程式碼 目標動作
KEY_WWW 啟動預設網路瀏覽器
KEY_MAIL 開啟預設電子郵件用戶端
KEY_BOOKMARKS 開啟瀏覽器書籤清單
KEY_CALC 開啟計算機公用程式
KEY_FILE 開啟本機檔案總管
KEY_EDIT 文件編輯觸發條件
KEY_NEW 文件建立新觸發條件
KEY_OPEN 文件開啟觸發條件
KEY_SAVE 檔案儲存工作觸發條件
KEY_CLOSE 檔案關閉工作觸發條件
KEY_PRINT 檔案列印工作觸發條件
KEY_COPY 剪貼簿緩衝區複製動作
KEY_PASTE 剪貼簿緩衝區插入動作
KEY_CUT 剪貼簿緩衝區剪下動作
KEY_UNDO 剪貼簿緩衝區復原動作
KEY_REDO 剪貼簿緩衝區重做動作
KEY_CANCEL 緩衝區取消程序觸發條件
KEY_FIND 文件搜尋公用程式
KEY_REFRESH 文件重新整理公用程式
KEY_EXIT 文件關閉公用程式
KEY_DOCUMENTS 啟動系統文件入口網站
KEY_HOMEPAGE 啟動首頁瀏覽器
KEY_FAVORITES 開啟瀏覽器我的最愛入口網站
KEY_CHAT 啟動即時通訊程式
KEY_EMAIL 備用電子郵件地址啟動觸發條件
KEY_FINANCE 開啟股票/財經公用程式
KEY_SPORT 開啟運動追蹤公用程式
KEY_SHOP 開啟數位購物入口網站
KEY_PLAYER 開啟主要媒體播放器
KEY_MP3 開啟主要 MP3 播放器
KEY_TEXT 開啟預設文字編輯器
KEY_LIST 開啟檢查清單公用程式
KEY_MEMO 開啟記事本/備忘錄公用程式
KEY_CALENDAR 開啟日曆/議程入口網站
KEY_DIRECTORY 開啟系統地址目錄
KEY_COMPUTER 開啟規格探索工具
KEY_TV/KEY_TV2 啟動電視入口網站
KEY_RADIO 啟動無線電公用程式
KEY_CD/KEY_DVD 啟用光碟機
KEY_AUDIO/KEY_VIDEO 存取媒體規格
KEY_TUNER 設定接收器/調諧器
KEY_SAT/KEY_SAT2 設定衛星動態饋給
KEY_TAPE 播放錄音帶媒體卡牌
KEY_VCR 播放錄影機播放器動態
KEY_VCR2 播放 VCR 2 播放器畫面
KEY_AUX 輔助媒體通訊埠輸入
KEY_SETUP 設定選單
KEY_PROG1 至 _PROG4 使用者定義的程式金鑰
KEY_ZOOM 縮放可視區域切換鈕
KEY_MODE 選取可視區域模式
KEY_KEYBOARD 顯示/隱藏虛擬鍵盤
KEY_LANGUAGE 切換音軌語言
KEY_TITLE 開啟媒體標題選項
KEY_SUBTITLE 切換字幕介面
KEY_ANGLE 變更攝影機角度
KEY_EPG 開啟電子節目表
KEY_PVR 開啟個人錄影機
KEY_MHP 開放式多媒體家用平台
KEY_CHANNEL 開啟電視選台器頻道
KEY_CHANNELUP 調高電視頻道
KEY_CHANNELDOWN 調低電視頻道
KEY_RED 紅色互動式按鈕
KEY_GREEN 綠色互動按鈕
KEY_YELLOW 黃色互動按鈕
KEY_BLUE 藍色互動式按鈕
KEY_FIRST 選取第一個項目選項
KEY_LAST 選取「最後一個項目」選項
KEY_NEXT 選取下一個音軌選項
KEY_PREVIOUS 選取上一個音軌選項
KEY_RESTART 重新啟動媒體音軌循環
KEY_SLOW 慢動作播放選項
KEY_AB A-B 重複序列循環
KEY_PLAYCD CD 播放器播放指令
KEY_PAUSECD CD 播放器暫停指令
KEY_STOPCD CD 播放器停止指令
KEY_DIGITS 數位面板輸入指令
KEY_TEEN 青少年專用撥號鍵盤值選項
KEY_TWEN 鍵盤 twen 值選項
KEY_DEL_EOL 刪除至行緩衝區結尾
KEY_DEL_EOS 刪除至畫面緩衝區結尾
KEY_INS_LINE 插入新行緩衝區
KEY_BRL_DOT1 至 _DOT8 點字顯示器按鈕輸入
KEY_VOICECOMMAND 啟動語音小幫手應用程式
KEY_SELECTIVE_SCREEN 觸發區域螢幕剪輯
KEY_BATTERY 查詢電池通知
KEY_STAR/KEY_SHARP 電話撥號鍵盤符號
KEY_PLUS 電話撥號鍵盤加號符號
KEY_INFO 顯示資訊面板疊加層
KEY_TIME 顯示目前時間
KEY_VENDOR 查詢供應商規格
KEY_ARCHIVE 開啟本機封存公用程式
KEY_PROGRAM 設定程式參數
KEY_POWER2 觸發備用電源

EV_ABS — 絕對動作事件

EV_ABS 事件類型對於模擬精確觸控、拖曳手勢、多點觸控縮放動作和搖桿調整至關重要。下方的絕對座標會直接對應至基礎實體螢幕解析度。

程式碼 座標範圍 說明
ABS_MT_TRACKING_ID -1 或 ≥0 追蹤 ID;-1結束觸控
ABS_MT_POSITION_X 0 至 1767 X 座標 (Pixel Fold)
ABS_MT_POSITION_Y 0 至 2207 Y 座標 (Pixel Fold)
ABS_MT_TOUCH_MAJOR 像素 觸控區域長軸寬度
ABS_MT_TOUCH_MINOR 像素 觸控區域短軸寬度
ABS_MT_WIDTH_MAJOR 像素 工具長軸寬度
ABS_MT_WIDTH_MINOR 像素 工具短軸寬度
ABS_MT_ORIENTATION 0 至 255 接觸方向角度
ABS_MT_PRESSURE 0 至 255 接觸力大小
ABS_MT_DISTANCE mm 與螢幕的懸停距離
ABS_MT_TOOL_TYPE 0 至 2 0=手指,1=筆,2=鉛筆
ABS_MT_BLOB_ID 整數 聯絡人 Blob ID
ABS_MT_TOOL_X 像素 工具 X 軸位置座標
ABS_MT_TOOL_Y 像素 工具 Y 軸位置座標
ABS_MT_SLOT 0 至 N 有效版位 (通訊協定 B)
ABS_X/_Y/_Z 類比 搖桿座標軸
ABS_RX/_RY/_RZ 類比 搖桿旋轉軸
ABS_THROTTLE/_BRAKE 類比 踏板和轉向控制
ABS_HAT0X/_HAT0Y -1/0/1 D-pad 苦力帽和 POV 切換鈕
ABS_PRESSURE 0 至 255 觸控筆/指標壓力等級
ABS_DISTANCE mm 懸停距離 (觸控筆)
ABS_TILT_X/_TILT_Y 度 觸控筆傾斜角度
ABS_VOLUME analogue 控制器音量

Android 觸控互動是由多點觸控 (MT) 通訊協定驅動。現代模擬器會同時實作通訊協定 A (無狀態,傳送以同步標記分隔的接觸封包) 和通訊協定 B (有狀態,將接觸指派給專屬追蹤槽)。通訊協定 B 可有效追蹤多個並行觸控,適用於雙指撥動縮放等手勢。

EV_REL 和 EV_SW:動態和硬體切換鈕

EV_REL 事件類別會管理相對指標或座標變更,主要用於模擬外部滑鼠移動或捲動滾輪。EV_SW 事件類別會管理實體裝置切換,例如摺疊式手機或平板電腦是否摺疊,或是否插入外部音訊硬體。

程式碼 值 說明
REL_X 差異 水平移動游標
REL_Y 差異 垂直移動游標
SW_LID 0/1 筆電上蓋狀態 (0=開啟,1=關閉)
SW_TABLET_MODE 0/1 平板模式狀態 (0=關閉,1=啟用)
SW_HEADPHONE_INSERT 0/1 耳機插孔狀態 (0=拔出,1=插入)
SW_MICROPHONE_INSERT 0/1 麥克風插孔狀態 (0=拔出,1=插入)
指令調度語法

如要調度這些代碼,請設定控制台指令的格式,並以冒號分隔類型、代碼和值。您可以在單一字串中排入多個座標變更。最重要的是,請務必在最後附加同步處理標記 (EV_SYN:0:0),表示模擬器架構應將這些輸入內容一併彙整及處理。

事件指令碼和手勢範例

由於 Telnet 允許傳送多部分參數,因此您可以模擬實際的實體手勢序列。以下是原始事件指令碼結構,用於從主機控制台自動執行手勢。

模擬輕觸螢幕

如要在目標座標上執行乾淨的螢幕輕觸動作,請指派追蹤 ID、指定螢幕上的 X 和 Y 座標、模擬接觸觸控、同步處理,然後放開。

# Press down at coordinate (400, 800) and sync
event send EV_ABS:ABS_MT_TRACKING_ID:1
OK
event send EV_ABS:ABS_MT_POSITION_X:400
OK
event send EV_ABS:ABS_MT_POSITION_Y:800
OK
event send EV_KEY:BTN_TOUCH:1
OK
event send EV_SYN:0:0
OK
# Lift finger up and sync
event send EV_ABS:ABS_MT_TRACKING_ID:-1
OK
event send EV_KEY:BTN_TOUCH:0
OK
event send EV_SYN:0:0
OK
模擬垂直捲動 (滑動)

如要執行捲動滑動手勢,請按住起始座標的接觸點,傳送中間移動座標框架,然後在結束時放開。

# Finger touch down at start coordinate (500, 1600)
event send EV_ABS:ABS_MT_TRACKING_ID:2
OK
event send EV_ABS:ABS_MT_POSITION_X:500
OK
event send EV_ABS:ABS_MT_POSITION_Y:1600
OK
event send EV_KEY:BTN_TOUCH:1
OK
event send EV_SYN:0:0
OK
# Move coordinates upward dynamically
event send EV_ABS:ABS_MT_POSITION_Y:1200
OK
event send EV_SYN:0:0
OK
event send EV_ABS:ABS_MT_POSITION_Y:800
OK
event send EV_SYN:0:0
OK
event send EV_ABS:ABS_MT_POSITION_Y:400
OK
event send EV_SYN:0:0
OK
# Finger release at coordinate (500, 400)
event send EV_ABS:ABS_MT_TRACKING_ID:-1
OK
event send EV_KEY:BTN_TOUCH:0
OK
event send EV_SYN:0:0
OK
模擬雙指撥動縮放手勢

如要觸發雙指縮放,請使用有效的 MT 插槽 (0 和 1) 追蹤並協調兩個同時觸控座標,並將其移開。

# Finger 1 down at (500, 1000) using slot 0
event send EV_ABS:ABS_MT_SLOT:0
OK
event send EV_ABS:ABS_MT_TRACKING_ID:10
OK
event send EV_ABS:ABS_MT_POSITION_X:500
OK
event send EV_ABS:ABS_MT_POSITION_Y:1000
OK
event send EV_KEY:BTN_TOUCH:1
OK
event send EV_SYN:0:0
OK
# Finger 2 down at (600, 1000) using slot 1
event send EV_ABS:ABS_MT_SLOT:1
OK
event send EV_ABS:ABS_MT_TRACKING_ID:11
OK
event send EV_ABS:ABS_MT_POSITION_X:600
OK
event send EV_ABS:ABS_MT_POSITION_Y:1000
OK
event send EV_SYN:0:0
OK
# Fingers slide apart from each other
event send EV_ABS:ABS_MT_SLOT:0
OK
event send EV_ABS:ABS_MT_POSITION_X:300
OK
event send EV_SYN:0:0
OK
event send EV_ABS:ABS_MT_SLOT:1
OK
event send EV_ABS:ABS_MT_POSITION_X:800
OK
event send EV_SYN:0:0
OK
# Lift Finger 1 using slot 0
event send EV_ABS:ABS_MT_SLOT:0
OK
event send EV_ABS:ABS_MT_TRACKING_ID:-1
OK
event send EV_SYN:0:0
OK
# Lift Finger 2 using slot 1
event send EV_ABS:ABS_MT_SLOT:1
OK
event send EV_ABS:ABS_MT_TRACKING_ID:-1
OK
event send EV_KEY:BTN_TOUCH:0
OK
event send EV_SYN:0:0
OK
模擬耳機連線切換

模擬耳機插孔插入或拔除,測試音訊轉送切換。1 值代表插入耳機,0 則代表拔除耳機。

# Simulate headphones plugged in
event send EV_SW:SW_HEADPHONE_INSERT:1 EV_SYN:0:0
OK
# Simulate headphones unplugged
event send EV_SW:SW_HEADPHONE_INSERT:0 EV_SYN:0:0
OK
從實體裝置探索控制台事件代碼

如要找出任何自訂動作或按鈕手勢的確切事件語法序列,請使用 adb shell 連線,並執行 getevent 診斷公用程式。與模擬器 GUI 互動時,主控台會輸出確切的事件代碼、類型和位置。

# Run getevent to monitor input events dynamically
adb shell getevent -lt
/dev/input/event12: EV_KEY       KEY_POWER            DOWN
/dev/input/event12: EV_SYN       SYN_REPORT           00000000
/dev/input/event12: EV_KEY       KEY_POWER            UP
/dev/input/event12: EV_SYN       SYN_REPORT           00000000
  • event text message:傳送用於模擬按鍵操作的字元字串。訊息必須是 UTF-8 字串。系統會根據目前的裝置鍵盤將萬國碼 (Unicode) 訊息進行反向對應,並自動捨棄不支援的字元。

電源狀態控制項

  • power display:顯示電池和充電器狀態。

  • power ac {on| off}:將 AC 充電狀態設為開啟或關閉。

  • power status {unknown| charging| discharging| not-charging| full}:將電池狀態變更為指定狀態。

  • power present {true| false}:設定電池有無狀態。

  • power health {unknown| good| overheat| dead| overvoltage| failure}:設定電池健康狀態。

  • power capacity percent:將剩餘電池容量狀態設為 0 到 100 之間的百分比。

網路連線狀態 (僅限乙太網路和行動網路)

  • network status:檢查網路狀態、目前的延遲時間和速度特性。

  • network delay latency 變更模擬的網路延遲時間。

    模擬器可讓您模擬各種網路延遲程度,在較貼近實際運作狀況的環境中測試應用程式。您可以在模擬器啟動時設定延遲程度或範圍,也可以在應用程式透過模擬器執行時,使用主控台變更延遲時間。

    網路延遲時間必須採用下列其中一種格式 (數字的單位為毫秒):

    網路延遲時間格式:

  • gprs:GPRS,使用介於 150 至 550 之間的延遲時間範圍。

  • edge:EDGE/EGPRS,使用介於 80 至 400 之間的延遲時間範圍。

  • umts:UMTS/3G,使用介於 35 至 200 之間的延遲時間範圍。

  • none:沒有延遲。

  • num:模擬指定的延遲時間 (以毫秒為單位)。

  • min:max:模擬指定的延遲時間範圍。

    如要在模擬器啟動時設定延遲時間,請使用 -netdelay 模擬器選項,並提供支援的延遲時間值。範例:

    emulator -netdelay gprs
    emulator -netdelay 40,100
    

    如要在模擬器執行期間變更網路延遲時間,請連線至控制台,然後使用 network delay 指令:

    network delay gprs
    network delay 40 100
    
  • network speed speed 模擬器可讓您模擬各種網路傳輸速率。您可以在模擬器啟動時設定傳輸速率或範圍,也可以在應用程式透過模擬器執行時,使用控制台變更速率。

    網路速度必須採用下列其中一種格式 (數字的單位為千位元/秒):

    網路速度格式:

  • gsm:GSM/CSD,上傳速度為 14.4,下載速度為 14.4。

  • hscsd:HSCSD,所用的上傳速度為 14.4,下載速度為 43.2。

  • gprs:GPRS,上傳速度為 40.0,下載速度為 80.0。

  • edge:EDGE/EGPRS,上傳速度為 118.4,下載速度為 236.8。

  • umts:UMTS/3G,所用的上傳速度為 128.0,下載速度為 1920。

  • hsdpa:HSDPA,所用的上傳速度為 348.0,下載速度為 14,400.0。

  • lte:LTE,所用的上傳速度為 58,000,下載速度為 173,000。

  • evdo:EVDO,所用的上傳速度為 75,000,下載速度為 280,000。

  • full:無速度限制,但實際速度會因電腦連線速度而異。

  • num:以千位元/秒為單位,統一設定確切的上傳和下載速率。

  • up:down:以千位元/秒為單位,分別設定確切的上傳和下載速率。

    如要在模擬器啟動時設定網路速度,請使用 -netspeed 模擬器選項。範例:

    emulator -netspeed gsm @Pixel_API_26
    emulator -netspeed 14.4,80 @Pixel_API_26
    

    如要在模擬器執行期間變更網路速度,請連線至控制台,然後使用 network speed 指令:

    network speed 14.4 80
    
  • network capture {start| stop} file 將封包傳送至檔案。以下清單說明相關參數和參數值:

    注意:自 Android Emulator 36.5 起,Wi-Fi 連線流量預設由 netsim 處理。網路擷取控制台指令只會擷取透過 QEMU slirp 堆疊轉送的舊版行動網路/WAN 流量。如要在新版模擬器中擷取 Wi-Fi、藍牙或進階網路封包,請參閱進階模擬器網路指南中的「擷取網路流量」。

  • start file:開始擷取網路封包。基於安全考量,檔案必須是裸檔案名稱 (不含 / 等路徑分隔符,也不含 ..)。封包擷取檔案會儲存在 AVD 內容目錄的 console_out/ 資料夾下 (例如 ~/.android/avd/avd_name.avd/console_out/file)。

  • stop file:停止將封包傳送至指定檔案。

電話通訊模擬

Android Emulator 提供專屬的 GSM 和 CDMA 模擬數據機,可讓您在模擬器中模擬電話通訊功能。舉例來說,您可以使用 GSM 模擬來電,以及建立和終止數據連線。CDMA 則可用來提供訂閱來源和偏好的漫遊清單。Android 系統會完全以處理實際通話的方式處理模擬通話。模擬器不支援通話音訊。

  • gsm {call| accept| cancel| busy} phonenumber gsm 參數如下:

    • call:模擬來自 <phonenumber> 的來電。
    • accept:接聽來自 phonenumber 的來電,並將通話狀態變更為 active。只有在通話目前處於等待或保留狀態時,才能將通話狀態變更為進行中。
    • cancel:終止來自或撥往 <phonenumber> 的通話。
    • busy:結束打給電話號碼的外撥通話,並將通話狀態變更為忙線。只有在通話目前處於等候狀態時,您才能將通話狀態變更為忙線。
  • gsm {data| voice} state 資料狀態指令會變更 GPRS 數據連線的狀態,語音狀態指令則會變更 GPRS 語音連線的狀態,如下所示:

    • unregistered:無法連上網路。
    • home:使用區域網路,非漫遊。
    • roaming:使用漫遊網路。
    • searching:正在搜尋網路。
    • denied:僅可撥打緊急電話。
    • off:與未註冊相同。
    • on:與 home 相同。
  • gsm hold:將通話狀態變更為保留。只有在通話目前處於「進行中」或「等候中」狀態時,才能將通話狀態變更為「保留」。

  • gsm list:列出所有來電和外撥通話及其狀態。

  • gsm status:回報目前的 GSM 語音和數據狀態,會是語音和資料指令說明中所列的值。

  • gsm signal {rssi| ber} 變更下一個 15 秒更新期回報的訊號強度 (rssi) 和位元錯誤率 (ber)。以下清單說明相關參數和參數值:

    • rssi:範圍介於 0 到 31 之間,99 表示不明。
    • ber:範圍介於 0 到 7 之間,99 表示不明。
  • gsm signal-profile num:設定訊號強度設定檔。num 是介於 0 到 4 之間的數字。

  • cdma ssource source 設定目前的 CDMA 訂閱來源,其中來源是包含 CDMA 電信業者訂閱者及其值的網路許可清單,相關說明如下:

    • nv:從非揮發性 RAM 讀取訂閱項目。
    • ruim:從可移除的使用者身分識別模組 (RUIM) 讀取訂閱項目。
  • cdma prl_version version:轉儲目前的偏好漫遊清單 (PRL) 版本。版本號碼會用於 PRL 資料庫,該資料庫包含系統選取與獲取程序中使用的資訊。

管理模擬器中的感應器

這些指令與 AVD 中可用的感應器相關。除了使用感應器指令以外,您也可以在模擬器的「Virtual sensors」畫面中,透過「Accelerometer」和「Additional sensors」分頁查看及調整相關設定。

  • sensor status:列出所有感應器及其狀態。

  • sensor get sensor-name:取得 sensor-name 的設定。以下範例會取得加速感應器的值:

    sensor get acceleration
    acceleration = 2.23517e-07:9.77631:0.812348
    

    以冒號 (:) 分隔的加速度值,是指虛擬感應器的 x、y 和 z 座標。

  • sensor set sensor-name value-x:value-y:value-z:設定 sensor-name 的值。以下範例會將加速感應器設為 x、y 和 z 值 (以冒號分隔)。

    sensor set acceleration 2.23517e-07:9.77631:0.812348
    

簡訊模擬

  • sms send sender-phone-number textmessage 產生模擬的傳入簡訊。以下清單說明相關參數和參數值:

    • sender-phone-number:包含任意數字字串。
    • textmessage:簡訊內容。

    以下範例會將「hi there」訊息傳送至 4085555555 這支電話號碼:

    sms send 4085555555 hi there
    

主控台會將簡訊轉寄至 Android 架構,再由該架構將其傳送至模擬器中負責處理簡訊的應用程式 (例如「訊息」應用程式)。如果傳送 10 個數字,應用程式會將其格式化為電話號碼。長短數字字串會依您傳送的方式顯示。

指紋模擬

  • finger touch fingerprint-id:模擬手指觸碰感應器的情形。

  • finger remove:模擬手指移開的情形。

想瞭解如何使用這些指令,請參閱以下的「指紋模擬和驗證」一節。

螢幕畫面錄製

螢幕錄製指令可讓您直接從主機系統擷取模擬器實體螢幕的高畫質影片檔案。這項功能非常適合用於持續整合管道和自動錯誤報告。

  • screenrecord {start| stop} file 開始或停止螢幕錄製程序。
    • start file:開始錄製影片。輸出檔案必須以必要的 .webm 副檔名結尾。擷取的影片會直接儲存在 AVD 的控制台輸出目錄下:~/.android/avd/avd_name.avd/console_out/file。
    • stop file:停止執行中的螢幕錄製程序。

自動化與巨集

自動化子系統可讓開發人員在執行中的虛擬裝置上,記錄巨集狀態轉換,並播放這些轉換來執行自動化測試流程。

  • automation {record| stop-record| play| stop-play} 管理自動巨集錄製。
    • record:開始記錄裝置狀態變更和輸入內容。
    • stop-record:停止目前的巨集錄製工作階段。
    • play:開始播放錄製的巨集序列。
    • stop-play:停止執行中的巨集播放序列。

物理 (6DoF)

物理指令會管理記錄基準真相空間姿勢,用於六自由度 (6DoF) 物理動作模型,模擬進階動作追蹤。

  • physics {record-gt| stop} 管理身體姿勢模型錄製內容。
    • record-gt:開始記錄基準真相 6DoF 動作資料。
    • stop:停止目前的基準真相錄製程序。

進階裝置控制項

本節匯總了高度專業化的控制台指令端點,用於進階模擬設定,包括網路 Proxy、多螢幕設定、轉譯覆寫和管理程序直接偵錯。

  • multidisplay {add| del} 新增或刪除次要虛擬螢幕,測試多螢幕設定。注意:Pixel Fold 等摺疊設定檔或可調整大小的模擬器不支援次要螢幕。

  • proxy {set| clear} 透過控制台,以程式輔助方式設定網路 Proxy 轉送。

    • set host port:設定目標 Proxy。
    • clear:將 Proxy 設定重設為預設值。注意:在無頭執行環境中,Proxy 設定作業會失敗。
  • virtualscene-image {wall| table} image_path 使用自訂使用者圖片檔,自訂虛擬場景攝影機畫面中顯示的背景牆或水平表格。

  • resize-display scale 在預設比例之間動態調整螢幕解析度。注意:無頭設定不支援解析度調整。

  • nodraw {on| off} 停用主機螢幕上的實體 GUI 轉譯功能,在大量背景無頭自動化執行期間,減少系統記憶體和 GPU 負載。

  • grpc port 透過自訂 gRPC 通訊埠端點,設定進階程式輔助裝置控制項。

  • qemu monitor 提供直接互動式終端機存取權,可存取基礎 Hypervisor 的控制台。這個指令只能在有效的 Telnet 控制台工作階段中輸入。

  • icebox track pid 當指定的應用程式程序發生未處理的例外狀況或當機時,啟用自動系統快照。

  • phonenumber number 設定目標裝置的虛擬本地電話號碼。

gRPC 程式輔助介面

新版模擬器支援強大的 gRPC 程式輔助介面,以及舊版 Telnet 控制台。Telnet 控制台適合用於快速互動式工作階段或基本指令碼,而 gRPC 介面則專為在持續整合 (CI) 和無頭環境中,提供高效能、安全且穩健的自動化控制而設計。gRPC 提供直接服務端點,因此不需要剖析文字串流、管理終端機工作階段交握,或公開未加密的 localhost 通訊埠。

如要選擇使用舊版 Telnet 控制台或新版 gRPC 程式輔助介面,請參閱下列效能、安全性和功能比較:

功能 Telnet 控制台 gRPC 介面
適用情境 手動偵錯、互動式工作階段。 無頭 CI/CD、重型自動化測試設備。
速度 速度較慢;文字負擔、連線延遲。 最佳化;多工 HTTP/2,快速 proto。
安全性 未加密;本機通訊埠 (5554–5585)。 可透過 TLS 保護,並在網路上運作。
串流 不支援;僅限要求-回應。 logcat、訪客音訊擷取的串流。
媒體 將輸出檔案寫入主機/訪客磁碟。 直接透過網路傳輸二進位緩衝區。
訪客 OS 僅限固定的模擬器指令。 執行原生訪客 Bash 殼層指令。

啟動及呼叫 gRPC

如要使用 gRPC 端點,請從指令列啟動 Android Emulator,並加入 -grpc 旗標,指定目標回送通訊埠。

# Start the emulator with the gRPC service enabled on port 8556
emulator -grpc localhost:8556 @Pixel_Fold

模擬器在啟用 gRPC 服務的情況下執行後,您就可以發出程式輔助 RPC 呼叫。如要進行指令列測試,請使用 grpcurl 公用程式與模擬器服務通訊。所有要求都採用 JSON 格式,並透過純文字傳送。

# Query the status of the virtual device using grpcurl
grpcurl -plaintext -d '{}' localhost:8556 \
  android.emulation.control.EmulatorController/getStatus

# Simulate an incoming phone call
grpcurl -plaintext -d '{"operation": "InitCall", "number": "1234567890"}' localhost:8556 \
  android.emulation.control.EmulatorController/sendPhone

# Simulate typing text into the guest OS
grpcurl -plaintext -d '{"text": "Hello"}' localhost:8556 \
  android.emulation.control.EmulatorController/sendKey

Telnet 控制台與 gRPC 服務的對應關係

下方的參考表格列出舊版 Telnet 控制台指令與對應 gRPC 服務和方法的對應關係,說明如何以程式輔助方式自動執行常見的虛擬裝置互動:

類別 舊版 Telnet 指令 gRPC 服務/方法
Status ping EmulatorController/getStatus
Status avd name incubating.AvdService/getAvdInfo
Status kill EmulatorController/setVmState
Status restart EmulatorController/setVmState
電源 power display EmulatorController/getBattery
電源 power capacity EmulatorController/setBattery
地理位置 geo fix EmulatorController/setGps
感應器 sensor set incubating.SensorService/setSensor
生物辨識 finger touch EmulatorController/sendFingerprint
防護機制 posture EmulatorController/setPosture
安全防護機制 physics/fold EmulatorController/setPhysicalModel
簡訊 sms send EmulatorController/sendSms
GSM 通話 gsm call EmulatorController/sendPhone
GSM 通話 phonenumber EmulatorController/setPhoneNumber
重新導向 redir add Waterfall/ForwardPort
輸入功率 event send EV_KEY EmulatorController/sendKey
輸入功率 event send EV_ABS EmulatorController/sendTouch
媒體 screenrecord incubating.ScreenRecording
轉譯 nodraw EmulatorController/setDisplayMode
快照 avd snapshot list SnapshotService/ListSnapshots
快照 avd snapshot load/save SnapshotService/LoadSnapshot

gRPC 專屬的程式輔助指令

gRPC 介面提供多項先進功能,這些功能在實體上無法透過舊版 Telnet 控制台連線執行。包括直接 Logcat 串流、雙向音訊擷取或插入、主機 GUI 修改,以及直接殼層存取。

gRPC 服務/方法 參數 功能
streamLogcat {"maxLines": 100} 串流訪客系統 logcat 輸出內容
streamAudio {} 透過線路串流揚聲器音訊
injectAudio {"audio": "..."} 插入麥克風音訊串流
UiController {"theme": "DARK"} 修改主機視窗主題
Waterfall/Exec {"cmd": "ls"} 執行原生訪客 OS 殼層指令

指紋模擬和驗證

圖 1. 指紋驗證畫面。

使用 finger 指令模擬及驗證應用程式的指紋驗證程序。您必須使用 24.3 以上版本的 SDK 工具和 Android 6.0 (API 級別 23) 以上版本。

如要模擬及進行指紋驗證程序,請按照下列步驟操作:

  1. 如果您還沒有指紋 ID,請在模擬器中註冊新指紋,方法是依序選取「Settings」>「Security」 >「Fingerprint」,然後按照註冊指示操作。

  2. 將應用程式設為接受指紋驗證。完成這項設定後,裝置會顯示指紋驗證畫面。

  3. 應用程式顯示指紋驗證畫面時,前往主控台並輸入 finger touch 指令和您建立的指紋 ID。系統會模擬手指觸碰的情形。

  4. 接著輸入 finger remove 指令,模擬手指移開的情形。應用程式應該會有所回應,就好像使用者觸碰指紋感應器並移開手指一樣。