# 基礎自動化操作

本章節為您描述 FIRERPA 提供的自動化基礎功能，當然還有更進階的用法會在後續章節描述，本章將為您介紹一些常用的基礎功能介面。

## 取得裝置資訊

取得目前裝置的資訊，如裝置名稱、螢幕大小、螢幕方向和目前的應用程式等資訊。

```python
d.device_info()
```

```python
>>> d.device_info()
productName: "bumblebee"
sdkInt: 34
displayHeight: 2400
displaySizeDpX: 411
displaySizeDpY: 914
displayWidth: 1080
screenOn: true
naturalOrientation: true
currentPackageName: "com.android.launcher3"
```

```python
>>> result = d.device_info()
>>> print (result.displayWidth)
1080
```

## 取得服務資訊

取得目前服務的版本、裝置唯一 ID、版本、ABI 等資訊。

```python
d.server_info()
```

```python
>>> d.server_info( )
uniqueId: "673abbe0-ff7b-9d82-1792-8876cb72cf56"
version: "8.28"
architecture: "arm64-v8a"
uptime: 293
secure: True
```

```python
>>> result = d.server_info()
>>> print (result.secure)
False
```

## 螢幕休眠

以下介面將會使目前的手機螢幕休眠，相當於您在螢幕亮起時按一下電源鍵的效果。

```python
d.sleep()
```

## 喚醒螢幕

以下介面將會使目前的手機螢幕點亮，相當於您在螢幕休眠時按一下電源鍵的效果。

```python
d.wake_up()
```

## 螢幕是否點亮

您可以透過以下介面檢查目前裝置的螢幕是否為點亮狀態，以便判斷是否可以操作。

```python
d.is_screen_on()
```

## 螢幕是否鎖定

您可以透過以下介面檢查目前裝置的螢幕是否為解鎖狀態，以便判斷是否可以操作。

```python
d.is_screen_locked()
```

## 顯示 Toast

您可以使用以下介面，在手機的介面上顯示一則 `Hello from Lamda!` 的 Toast 訊息。

```python
d.show_toast("Hello from Lamda!")
```

## 讀取剪貼簿

以下介面用於讀取手機目前的剪貼簿內容，暫不支援 Android 10+。

```python
d.get_clipboard()
```

## 寫入剪貼簿

以下介面用於向目前裝置的剪貼簿寫入內容。

```python
d.set_clipboard("剪貼簿內容")
```

## 實體按鍵

您可以使用下列方法來執行模擬按鍵的操作，支援如 KEY_BACK、KEY_DOWN、KEY_HOME 等十多種按鍵。

```python
d.press_key(Keys.KEY_BACK)
d.press_key(Keys.KEY_CAMERA)
d.press_key(Keys.KEY_CENTER)
d.press_key(Keys.KEY_DELETE)
d.press_key(Keys.KEY_DOWN)
d.press_key(Keys.KEY_ENTER)
d.press_key(Keys.KEY_HOME)
d.press_key(Keys.KEY_LEFT)
d.press_key(Keys.KEY_MENU)
d.press_key(Keys.KEY_POWER)
d.press_key(Keys.KEY_RECENT)
d.press_key(Keys.KEY_RIGHT)
d.press_key(Keys.KEY_SEARCH)
d.press_key(Keys.KEY_UP)
d.press_key(Keys.KEY_VOLUME_DOWN)
d.press_key(Keys.KEY_VOLUME_MUTE)
d.press_key(Keys.KEY_VOLUME_UP)
```

同時，為了支援更多其他按鍵，也可以使用此方法來模擬。您可以在此 Android 官方文件中找到所有支援的按鍵名稱 [https://developer.android.com/reference/android/view/KeyEvent](https://developer.android.com/reference/android/view/KeyEvent#KEYCODE_0)。

```python
d.press_keycode(KeyCodes.KEYCODE_CALL)
```

## 螢幕截圖

我們提供了螢幕截圖的方法，讓您可以記錄流程或進行一些圖像辨識操作。以下的呼叫解釋為：截取品質為 60 的圖像，並儲存在目前目錄的 screenshot.png 檔案中。

```python
d.screenshot(60).save("screenshot.png")
```

```python
>>> result = d.screenshot(60)
>>> result
<lamda.types.BytesIO object at 0x7a28361d60>
>>> result.save("screenshot.png")
52917
>>> result.getvalue( )
b'\xff\xd8\xff\xe0\x00\x10JFIF\x00\x01....'
```

目前，我們也支援區域和元素截圖。元素截圖不在本章介紹，這裡為您介紹區域截圖。您需要了解區域的概念和定義，在我們的介面中，區域以 `Bound` 來定義，它包含四個參數：top、left、right、bottom。Android 螢幕與常規座標系不同，目前裝置螢幕的左上角為原點，其座標為 x=0, y=0。我們假設目前螢幕為直向，解析度為 1080x1920，那麼如果要截取一個全螢幕的區域截圖，您可以這樣做。

```python
d.screenshot(60, bound=Bound(top=0, left=0, right=1080, bottom=1920)).save("screenshot.png")
```

這樣將會產生一張全螢幕截圖，當然這是不必要的，因為預設就是全螢幕截圖。那麼，如果我們想要截取一張左上角 200x200 的圖像該怎麼做？這也很簡單，您只需要像下面這樣。

```python
d.screenshot(60, bound=Bound(top=0, left=0, right=200, bottom=200)).save("screenshot.png")
```

到這裡，我們該為您介紹這幾個參數的意義。參數中，top 代表從 Y 軸往下數 top 個像素，bottom 代表從 Y 軸往下數 bottom 個像素，left 以及 right 即代表從 X 軸往右數 N 個像素。其中，top 永遠小於 bottom，left 永遠小於 right。下面我們再示範一個截取螢幕右下角 200x200 圖像的例子，您只需要像下面這樣呼叫介面。

```python
d.screenshot(60, bound=Bound(top=1920-200, bottom=1920, left=1080-200, right=1080)).save("screenshot.png")
```

## 點擊螢幕上的一個點

您可以透過以下介面來模擬點擊螢幕，在範例中，我們點擊了螢幕上座標為 (100, 100) 的點。

```python
d.click(Point(x=100, y=100))
```

## 點按 A 點並將其拖曳至 B 點

透過以下介面可以實現將 A 點位置的物件拖曳到 B 點，例如將圖示拖曳到資料夾這類操作。

```python
A = Point(x=100, y=100)
B = Point(x=500, y=500)

d.drag(A, B)
```

## 從 A 點滑動至 B 點

透過以下介面可以實現從螢幕的 (100, 100) 座標滑動到 (500, 500) 座標。

```python
A = Point(x=100, y=100)
B = Point(x=500, y=500)

d.swipe(A, B)
```

## 較複雜的多點滑動

以下介面可以模擬多點滑動，例如以下呼叫將會從 (100, 100) 滑動到 (500, 500) 再回到 (200, 200)。下面的示範中只滑動了三個點，實際上您可以提供更多的點位，甚至實現九宮格解鎖。

```python
p1 = Point(x=100, y=100)
p2 = Point(x=500, y=500)
p3 = Point(x=200, y=200)

d.swipe_points(p1, p2, p3)
```

## 開啟快捷設定

以下呼叫可以開啟螢幕上的通知欄，但是是半開的狀態。

```python
d.open_quick_settings()
```

## 開啟通知欄

以下呼叫可以開啟螢幕上的通知欄。

```python
d.open_notification()
```

## 取得頁面佈局

以下呼叫可以取得目前頁面的 XML 佈局，您也可以自行解析以支援 XPath 自動化。

```python
d.dump_window_hierarchy()
```

```python
>>> result = d.dump_window_hierarchy()
>>> result
<lamda.types.BytesIO object at 0x7add660680>
>>> result.getvalue()
b'<?xml version=\'1.0\' encoding=\'UTF-8\' standalone=\'yes\' ?>\r\n<hierarchy rotation="0">\r\n  <node index="0" text="" resource-id="" class="android.widget.FrameLayout" package="com.android.systemui" content-desc="" checkable="false" checked="false" clickable="false"...
```

## 等待視窗靜止

您可以執行以下呼叫來等待目前視窗處於靜止狀態，類似於 Selenium 的 implicitly_wait。參數的單位是毫秒，5*1000 代表等待 5 秒鐘，毫秒轉換為秒的單位是 1000。

```python
d.wait_for_idle(5*1000)
```

## 取得最近的 Toast

您可以執行以下的呼叫來取得系統中最近一則 Toast 訊息。但需要注意，只支援系統內 API 發送的 Toast 訊息，第三方實作的類 Toast UI 訊息無法取得。

```python
d.get_last_toast()
```

```python
>>> result = d.get_last_toast()
>>> print (result)
timestamp: 1700000000000
package: "com.android.settings"
message: "\346\202\250\345\267\262\345\244\204\344\272\216\345\274\200\345\217\221\350\200\205\346\250\241\345\274\217\357\274\214\346\227\240\351\234\200\350\277\233\350\241\214\346\255\244\346\223\215\344\275\234\343\200\202"
>>> print (result.message)
您已處於開發者模式，無需進行此操作。
```