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.2.1"
implementation "androidx.compose.ui:ui-tooling-preview:1.2.1"

組件預覽

組件由函式定義,附有 @Composable 註解:

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

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

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

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

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

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

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

您可以在程式碼中手動新增參數,以自訂 Android Studio 轉譯 @Preview 的方式。

@Preview 功能

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

LocalInspectionMode

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

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。

使用者點選預覽畫面的「interactive」(互動) 按鈕

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

部署預覽

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

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

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

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

多重預覽註解

使用多重預覽時,您可以定義註解類別,且其本身具有多個使用不同設定的 @Preview 註解。將此註解新增至組件後,就會自動一次轉譯所有不同的預覽。舉例來說,您可以使用此註解同時預覽多種裝置、字型大小或主題,不需要針對每一個組件重複執行這些定義。

首先,請建立您的自訂註解類別:

@Preview(
    name = "small font",
    group = "font scales",
    fontScale = 0.5f
)
@Preview(
    name = "large font",
    group = "font scales",
    fontScale = 1.5f
)
annotation class FontScalePreviews

您可以針對預覽組件使用此自訂註解:

@FontScalePreviews
@Composable
fun HelloWorldPreview() {
    Text("Hello World")
}

顯示小字體與大字型的 Android Studio 設計分頁

您可以合併多重預覽註解和一般預覽註解,以建立更完整的預覽組合。合併多重預覽註解並不代表會顯示其他不同的組合。因此,每個多重預覽註解都會分開運作,並且只會顯示各自的變化版本。

@Preview(
    name = "dark theme",
    group = "themes",
    uiMode = UI_MODE_NIGHT_YES
)
@FontScalePreviews
@DevicePreviews
annotation class CombinedPreviews

@CombinedPreviews
@Composable
fun HelloWorldPreview() {
    MyTheme { Surface { Text("Hello world") } }
}

顯示所有設定中組件的 Android Studio 設計分頁

程式碼導覽與組件概述

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

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

複製 @Preview 算繪

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

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

設定背景顏色

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

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

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

尺寸

根據預設,系統會自動選擇可包覆內容的 @Preview 尺寸。如要手動設定尺寸,可以新增 heightDpwidthDp 參數。請注意,系統已將這些值解譯為 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 修飾符
  • WWRWC 用來設定以 BoxRowColumn 容器包圍目前的組件。

溝槽圖示

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

部署預覽

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

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

顏色挑選器

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

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

圖片資源挑選器

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

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

疊代程式碼開發

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

常值即時編輯

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

  • Int
  • String
  • Color
  • Dp
  • Boolean

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

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

啟用常值即時編輯

即時編輯

您可以在 Android Studio Flamingo 的初期測試版中使用即時編輯功能,藉此加快 Compose 開發速度。「即時編輯」是更強大的常值即時編輯功能。這項功能可讓您在模擬器或裝置中自動部署程式碼變更,即時查看組件更新所造成的影響。

即時編輯 UI 總覽

套用變更

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

新增、修改或刪除可組合項時,按一下這個按鈕即可更新應用程式,不必重新部署:

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

版面配置檢查器

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

取得重組程序計數

您可以使用版面配置檢查器,檢查某個組件的撰寫或略過頻率。如果您的 UI 效能不佳,這通常是因為程式碼錯誤導致強制過度重組 UI。另一方面,某些程式設計錯誤也可能會導致 UI 在需要變更時無法重組,畫面中因此就不會顯示 UI 的變更。追蹤重組可以幫助您找出這兩種問題。

若要追蹤重組,請在檢視選項中開啟「Show Recomposition Counts」

檢視選項中已啟用重組計數

啟用後,版面配置檢查器會在左側顯示重組計數,並在右側顯示略過的重組:

版面配置檢查器中顯示的重組計數

如果在版面配置檢查器中按兩下某個可組合項,系統會引導您前往對應的程式碼進行分析。

動畫

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

播放、拖曳和放慢 AnimatedVisibility

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

動畫曲線的視覺化呈現

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

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

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

啟用實驗功能

您必須先在 Android Studio 偏好設定的「experimental」部分中啟用後,才能使用某些功能,啟用步驟如下:依序點選「File」>「Settings」>「Experimental」;在 Mac 中的啟用步驟則為:「Android Studio」>「Preferences」>「Experimental」

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