使用可組合項預覽預覽 UI

可組合項由函式定義，並加上 @Composable 註解：

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

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

如要啟用這個可組合項的預覽功能，請建立另一個可組合項，並加上 @Composable 和 @Preview 註解。這個新的註解可組合函式現在包含您最初建立的可組合函式 SimpleComposable：

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

@Preview 註解會告知 Android Studio，這個可組合函式應當在此檔案的設計檢視畫面中顯示。編輯時，可查看可組合項預覽畫面的即時更新。

GIF 圖片：使用 Compose 預覽畫面顯示即時更新

您可以在程式碼中手動新增參數，自訂 Android Studio 轉譯 @Preview 的方式。您甚至可以多次將 @Preview 註解新增至同一個函式，預覽具有不同屬性的可組合函式。

使用 @Preview 可組合項的主要優點之一，是避免依賴 Android Studio 中的模擬器。您可以將模擬器耗用大量記憶體的啟動作業，留給最終外觀和風格變更，並利用 @Preview 輕鬆進行及測試小幅程式碼變更。

如要最有效地運用 @Preview 註解，請務必根據畫面接收的輸入狀態和輸出的事件定義畫面。

定義@Preview

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

尺寸

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

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

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

動態色彩預覽

如果您已在應用程式中啟用動態色彩，請使用 wallpaper 屬性切換桌布，查看 UI 如何因應不同使用者所選的桌布做出調整。從 Wallpaper 類別提供的不同桌布主題中選取。這項功能需要 Compose 1.4.0 以上版本。

在不同裝置上使用

在 Android Studio Flamingo 中，您可以編輯 Preview 註解的 device 參數，定義可組合函式在不同裝置的設定。

可組合函式範例

當裝置參數包含空字串 (@Preview(device = "")) 時，您可以按下 Ctrl + Space 叫用自動完成功能。接著，您可以設定各個參數的值。

編輯範例函式

您可以從自動完成清單中選取任何裝置選項，例如 @Preview(device = "id:pixel_4")。或者，您也可以選擇 spec:width=px,height=px,dpi=int… 來設定每個參數的個別值，藉此輸入自訂裝置。

規格 清單

如要套用，請按下 Enter 鍵；如要取消，請按下 Esc 鍵。

如果您設定的值無效，宣告下方會顯示紅色底線，且可能提供修正選項 (Alt + Enter (macOS 為 ⌥ + ⏎) >「Replace with …」。檢查工具會嘗試提供最接近您輸入內容的修正選項。

無效值範例

語言代碼

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

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

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

設定背景顏色

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

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

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

系統 UI

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

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

預覽視窗，顯示含有狀態和動作列的活動。

UI 模式

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

Compose 預覽 UI

LocalInspectionMode

您可以透過 LocalInspectionMode CompositionLocal 讀取資料，查看系統是否在預覽畫面 (位於可檢查元件中) 算繪可組合項。如果系統在預覽畫面中算繪組合結構，則 LocalInspectionMode.current 的評估值會是 true。這項資訊可讓您自訂預覽畫面，例如在預覽視窗中顯示預留位置圖片，而非實際資料。

這樣一來，您也可以避開限制。例如顯示樣本資料，而非呼叫網路要求。

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

與 @Preview 互動

Android Studio 提供多項功能，可讓您與定義的預覽畫面互動。這項互動有助於您瞭解預覽畫面的執行階段行為，並透過預覽畫面更輕鬆地瀏覽 UI。

互動模式

互動模式可讓您與預覽畫面互動，就像在執行程式的裝置 (例如手機或平板電腦) 上一樣。互動模式存在於沙箱環境中，與其他預覽畫面隔離開來，您可在預覽畫面中點選元素，並輸入使用者輸入內容。透過這種模式，您可以快速測試可組合項的各個狀態、手勢，甚至是動畫。

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

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

程式碼導覽與組件概述

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

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

執行更多預覽動作

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

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

使用者點選預覽畫面的

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

複製 @Preview 算繪

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

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

同一個 @Preview 註解的多個預覽畫面

您可以展示同一個 @Preview 可組合函式的多個版本，並使用不同的規格，或將不同的參數傳遞至可組合函式。這樣一來，您就能減少需要編寫的樣板程式碼。

多重預覽範本

androidx.compose.ui:ui-tooling-preview 1.6.0-alpha01+ 導入了 Multipreview API 範本：@PreviewScreenSizes、@PreviewFontScales、@PreviewLightDark，以及 @PreviewDynamicColors，因此您只要使用單一註解，即可在常見情境中預覽 Compose UI。

使用範本預覽不同字型和螢幕大小

建立自訂多重預覽註解

使用多重預覽時，您可以定義註解類別，且其本身具有多個使用不同設定的 @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 = "Spanish",
    group = "locale",
    locale = "es"
)
@FontScalePreviews
annotation class CombinedPreviews

@CombinedPreviews
@Composable
fun HelloWorldPreview2() {
    MaterialTheme { Surface { Text(stringResource(R.string.hello_world)) } }
}

Android Studio 設計分頁，顯示所有設定中的可組合函式

多重預覽和一般預覽的混搭特性，可讓您更全面地測試大型專案的多項屬性。

@Preview和大型資料集

您通常需要將大型資料集傳遞至可組合項預覽畫面。如要這麼做，只要新增含有 @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")
    )
}

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

Elise、Frank 和 Julia 可組合項的預覽畫面

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

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

根據預設，使用 @PreviewParameter 的預覽畫面會以參數索引和屬性名稱 (使用者 0、使用者 1、使用者 2 等) 命名，因此可能難以區分。如要提高預覽清晰度，您可以覆寫 PreviewParameterProvider 中的 getDisplayName()，為每個預覽提供自訂顯示名稱。這有助於區分不同的資料變化版本或 UI 狀態。舉例來說，您可以根據輸入資料為預覽畫面加上標籤：

class UserAgePreviewParameterProvider : PreviewParameterProvider<User> {
    // Using a List internally for efficient index-based access
    private val userList = listOf(
        User(name = "Elise", age = 30),
        User(name = "Frank", age = 31),
        User(name = "Julia", age = 40)
    )

    override val values = userList.asSequence()

    override fun getDisplayName(index: Int): String? {
        // Return null or an empty string to use the default index-based name
        val user = userList.getOrNull(index) ?: return null
        return "${user.name} - ${user.age}"
    }
}

含有自訂顯示名稱的預覽畫面，顯示 Elise - 30、Frank - 31 和 Julia - 40 可組合項

AI 輔助生成預覽

Android Studio 中的 AI 代理可自動為可組合函式生成 Compose 預覽畫面。在可組合函式上按一下滑鼠右鍵，然後依序選取「AI」>「Generate Preview for [Composable name]」。代理會分析可組合函式，產生必要的 @Preview 樣板和正確參數，協助您快速驗證 UI 是否正常算繪。

使用 AI 生成 Compose 預覽畫面。

註解類別 @Preview

您隨時可以在 Android Studio 中按住「Ctrl」或「⌘」鍵並點選 @Preview 註解，查看自訂預覽畫面時可調整的完整參數清單。

annotation class Preview(
    val name: String = "",
    val group: String = "",
    @IntRange(from = 1) val apiLevel: Int = -1,
    val widthDp: Int = -1,
    val heightDp: Int = -1,
    val locale: String = "",
    @FloatRange(from = 0.01) val fontScale: Float = 1f,
    val showSystemUi: Boolean = false,
    val showBackground: Boolean = false,
    val backgroundColor: Long = 0,
    @UiMode val uiMode: Int = 0,
    @Device val device: String = Devices.DEFAULT,
    @Wallpaper val wallpaper: Int = Wallpapers.NONE,
)

限制與最佳做法

Android Studio 會直接在預覽區域執行預覽程式碼。這項工具會運用 Android 架構中名為 Layoutlib 的移植部分，因此不必執行模擬器或實體裝置。Layoutlib 是 Android 架構的自訂版本，可在 Android 裝置以外的環境執行。這個程式庫的目標是在 Android Studio 中提供版面配置預覽，與裝置上的轉譯效果非常接近。

預先發布版限制

由於預覽畫面在 Android Studio 中的算繪方式，因此預覽畫面相當輕量，不需要整個 Android 架構來算繪。但有以下限制：

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

預覽和ViewModels

在可組合函式中使用 ViewModel 時，預覽功能會受到限制。預覽系統無法建構傳遞至 ViewModel 的所有參數，例如存放區、用途、管理工具等。此外，如果 ViewModel 參與依附元件插入 (例如使用 Hilt)，預覽系統就無法建構整個依附元件圖表來建構 ViewModel。

嘗試使用 ViewModel 預覽可組合函式時，Android Studio 會在算繪特定可組合函式時顯示錯誤：

Android Studio 問題窗格，顯示「Failed to instantiate a `ViewModel`」訊息

如要預覽使用 ViewModel 的可組合項，請建立另一個可組合項，並將 ViewModel 的參數做為可組合項的引數傳遞。這樣一來，您就不需要預覽使用 ViewModel 的可組合項。

@Composable
fun AuthorScreen(viewModel: AuthorViewModel = viewModel()) {
  AuthorScreen(
    name = viewModel.authorName,
    // ViewModel sends the network requests and makes posts available as a state
    posts = viewModel.posts
  )
}

@Composable
fun AuthorScreen(
  name: NameLabel,
  posts: PostsList
) {
  // ...
}

@Preview
@Composable
fun AuthorScreenPreview(
  // You can use some sample data to preview your composable without the need to construct the ViewModel
  name: String = sampleAuthor.name,
  posts: List<Post> = samplePosts[sampleAuthor]
) {
  AuthorScreen(
      name = NameLabel(name),
      posts = PostsList(posts)
  )
}

其他資源

下一頁
動畫預覽及偵錯