Compose 工具

Android Studio 帶來許多專屬 Jetpack Compose 的新功能，這套系統採用程式碼優先的做法，同時還能改善開發人員的工作效率，而不需要在設計介面或程式碼編輯器之間二選一。

以檢視畫面為基礎的 UI 與 Jetpack Compose 的根本差異在於，Compose 不必仰賴 View 來算繪組件。這種架構方法帶來的結果之一，是 Android Studio 為 Jetpack Compose 提供額外功能時，不必像「Android Views」那樣開啟模擬器或連結裝置，這樣一來開發人員導入他們設計的 UI 時，就能加快疊代程序。

如要啟用 Android Studio 的 Jetpack Compose 專屬功能，您必須在應用程式 build.gradle 檔案中新增以下依附元件：

debugImplementation "androidx.compose.ui:ui-tooling:1.1.1"
implementation "androidx.compose.ui:ui-tooling-preview:1.1.1"

組件預覽

組件由函式定義，附有 @Composable 註解：

@Composable
fun SimpleComposable() {
    Text("Hello World")
}

包含「Hello World」字詞的簡單文字元素

如要啟用這個組件的預覽功能，您必須建立另一個組件，附加 @Composable 和 @Preview 註解，發送您最初建立的組件：

@Preview
@Composable
fun ComposablePreview() {
    SimpleComposable()
}

最後，按一下分割 (設計/程式碼) 畫面，即可開啟右側面板並在其中顯示預覽：

Android Studio「分割檢視畫面」選取器

預覽視窗中顯示的簡易文字檢視區塊

@Preview 可接受用參數自訂 Android Studio 的顯示方式。您可以在程式碼中手動新增這些參數，或是按一下 @Preview 旁邊的構槽圖示，顯示設定挑選器，以便在其中選取及變更這些設定參數。

@Preview 功能

Android Studio 提供了幾項可擴展組件預覽畫面的功能。您可以變更預覽畫面的容器設計、進行互動，或是直接將預覽畫面部署到模擬器或裝置中。

LocalInspectionMode

您可以透過 LocalInspectionMode CompositionLocal 讀取資料，查看系統是否在預覽畫面中算繪組件。這可讓您在預覽視窗中採用顯示預留位置圖片之類的做法，而不顯示實際資料。如果系統在預覽畫面中算繪組件，則 LocalInspectionMode.current 的評估值會是 true。

private fun ToolingSnippetLocalInspectionMode() {
    if (LocalInspectionMode.current) {
        // Show this text in a preview window:
        Text("Hello preview user!")
    } else {
        // Show this text in the app:
        Text("Hello $name!")
    }
}

互動模式

互動模式可讓您透過類似在裝置上互動的方式與預覽畫面互動。互動模式存在於沙箱環境中，與其他預覽隔離開來，您可在預覽畫面中點選元素，並輸入使用者輸入內容。此外，預覽畫面甚至還能播放動畫。這個做法可讓您快速測試可組合元件的各個狀態和手勢，例如核取方塊的已勾選或未勾選狀態。

預覽互動模式會直接在 Android Studio 中執行，無需執行模擬器。這會造成以下限制：

  • 沒有網路存取權
  • 沒有檔案存取權
  • 可能無法完整使用某些 Context API。

使用者點擊預覽的「互動」按鈕

使用者與預覽畫面互動的影片

部署預覽

您可以將特定的 @Preview 部署至模擬器或實體裝置。預覽是以新活動的形式部署在同一專案應用程式中，因此共用相同的情境和權限，也就是說，如果已授予權限，您就不必編寫樣板程式碼執行要求權限。

在 @Preview 註解旁邊或預覽頂端按一下「部署至裝置」圖示 ，Android Studio 就會將該 @Preview 部署至已連結的裝置或模擬器。

使用者點擊預覽畫面的「部署」按鈕

使用者將預覽部署到裝置的影片

程式碼導覽與組件概述

將滑鼠游標懸停在預覽畫面上，即可查看其中所含可組合項的概述。按一下組件概述，會觸發編輯器檢視畫面，供您查看定義。

使用者將滑鼠游標懸停在預覽畫面上，促使 Studio 顯示其中所含組件的概述

複製 @Preview 算繪

在任何算繪出的預覽畫面上按一下滑鼠右鍵，即可複製為圖片。

使用者在預覽畫面上按滑鼠右鍵，將其複製為圖片。

設定背景顏色

根據預設，組件將配合透明背景顯示。如要新增背景，請新增 showBackground 和 backgroundColor 參數。請注意，backgroundColor 是 ARGB Long，而不是 Color 值：

@Preview(showBackground = true, backgroundColor = 0xFF00FF00)
@Composable
fun WithGreenBackground() {
    Text("Hello World")
}

搭配綠色矩形顯示「Hello World」字詞

尺寸

根據預設，系統會自動選擇可包覆內容的 @Preview 尺寸。如要手動設定尺寸，可以新增 heightDp 和 widthDp 參數。請注意，系統已將這些值解譯為 Dp，您不需要在值的結尾再加上 .dp：

@Preview(widthDp = 50, heightDp = 50)
@Composable
fun SquareComposablePreview() {
    Box(Modifier.background(Color.Yellow)) {
        Text("Hello World")
    }
}

搭配黃色正方形顯示「Hello World」字詞

語言代碼

如要測試不同的使用者語言代碼，您必須新增 locale 參數：

@Preview(locale = "fr-rFR")
@Composable
fun DifferentLocaleComposablePreview() {
    Text(text = stringResource(R.string.greetings))
}

包含「Bonjour」字詞且帶有法國國旗的簡單文字元素

系統 UI

如果您需要在預覽畫面中顯示狀態和動作列，請新增 showSystemUi 參數：

@Preview(showSystemUi = true)
@Composable
fun DecoratedComposablePreview() {
    Text("Hello World")
}

正在顯示附有狀態和動作列的一項活動的預覽視窗

@PreviewParameter

您可以將範例資料傳送到「組件預覽」函式，方法是新增含有 @PreviewParameter 註解的參數。

@Preview
@Composable
fun UserProfilePreview(
    @PreviewParameter(UserPreviewParameterProvider::class) user: User
) {
    UserProfile(user)
}

如要提供範例資料，請建立會導入 PreviewParameterProvider 並以序列傳回範例資料的類別。

class UserPreviewParameterProvider : PreviewParameterProvider<User> {
    override val values = sequenceOf(
        User("Elise"),
        User("Frank"),
        User("Julia")
    )
}

序列中每個資料元素會算繪出一個預覽畫面：

您可以將同一個提供者類別用於多個預覽。如有需要，請設定限制參數來限制算繪出的預覽數量。

@Preview
@Composable
fun UserProfilePreview(
    @PreviewParameter(UserPreviewParameterProvider::class, limit = 2) user: User
) {
    UserProfile(user)
}

UI 模式

uiMode 參數可以採用任何 Configuration.UI_* 常數，並允許您據此變更預覽行為。舉例來說，您可以將預覽畫面設為夜間模式，看看主題的回應方式。

Compose 預覽 UI

編輯器動作

Android Studio 也會在編輯器區域提供相關功能，改善您使用 Jetpack Compose 的工作效率。

即時範本

Android Studio 新增了以下與 Compose 相關的即時範本，讓您只要輸入對應的範本縮寫，就能輸入程式碼片段，實現快速插入：

  • comp 用來設定 @Composable 函式
  • prev 用來建立 @Preview 可組合函式
  • paddp 用來在 dp 中新增 padding 修飾符
  • weight 用來新增 weight 修飾符
  • W、WR、WC 用來設定以 Box、Row 或 Column 容器包圍目前的組件。

溝槽圖示

溝槽圖示是側欄中可見的關聯動作，位在行編號旁邊。Android Studio 推出了數個 Jetpack Compose 專屬的溝槽圖示，改善開發人員體驗。

部署預覽

您可以透過溝槽圖示直接將 @Preview 部署到模擬器或實體裝置上：

使用者點選預覽函式的部署溝槽圖示，將預覽部署到裝置上。

顏色挑選器

每當在組件內部或外部定義顏色時，其預覽畫面就會顯示於溝槽。您可以透過顏色挑選器變更顏色，點選方式如下所示：

使用者在溝槽中點選某個顏色，系統隨即顯示顏色挑選器

圖片資源挑選器

每當在組件內部或外部定義可繪項目、向量或圖片時，其預覽畫面就會顯示於溝槽。您可以透過圖片資源挑選器加以變更，點選方式如下所示：

使用者在溝槽中點選某個圖示，系統隨即顯示資源挑選器

疊代程式碼開發

行動開發人員通常會逐步開發應用程式的 UI，而非一次完成所有開發作業。Android Studio 也透過 Jetpack Compose 實踐這種做法，我們提供不需要完整建構就能檢查、修改值並驗證最終結果的各種工具。

常值即時編輯

Android Studio 可以在預覽、模擬器和實體裝置內，即時更新組件中使用的部分常數常值。以下列舉部分支援的類型：

  • Int
  • String
  • Color
  • Dp
  • Boolean

影片：使用者變更原始碼中的常值，預覽畫面隨之動態更新

只要透過常值即時編輯功能的使用者介面指標啟用常值裝飾功能，就能查看觸發即時更新的常數常值，而不必進行編譯步驟：

啟用常值即時編輯

套用變更

套用變更可讓您更新程式碼和資源而不必重新將應用程式部署到模擬器或實體裝置上 (有幾項限制)。

新增、修改或刪除可組合項時，只要按一下這個按鈕就能更新應用程式，不必重新部署：

使用者按一下「套用變更」按鈕

版面配置檢查器

版面配置檢查器可讓您在模擬器或實體裝置中檢查運作中的應用程式內部的 Compose 版面配置。

動畫

Android Studio 可讓您透過「動畫預覽」檢查動畫。如果在組件預覽中描述了某個動畫，您可以檢查指定時間內各動畫值的確切值、暫停動畫、迴圈播放動畫、快轉動畫，或慢速播放動畫，以便對整個動畫的轉換過程進行偵錯：

播放、拖曳和放慢 AnimatedVisibility

此外，您也可以透過「動畫預覽」繪制動畫曲線圖，這有助於確保動畫值的編排妥善無誤：

動畫曲線的視覺化呈現

「動畫預覽」會自動偵測可檢查的動畫，偵測到的項目會以開始檢查動畫圖示 執行圖示 標示。

「設計」視窗中的「開始檢查動畫」圖示

「動畫預覽」目前支援 updateTransition API。如要搭配 updateTransition 使用「動畫預覽」，請使用 Compose 1.0.1 以上版本。

啟用實驗功能

您必須先手動啟用 Android Studio 偏好設定中的實驗功能，才能使用某些功能，啟用的步驟如下：「File」(檔案) >「Settings」(設定) >「Experimental」(實驗功能)。在 Mac 中的啟用步驟則為「Android Studio」>「Preferences」(偏好設定) >「Experimental」(實驗功能)。

在 Android Studio 實驗偏好設定中啟用的 Compose 工具