本頁面由 Cloud Translation API 翻譯而成。

使用可組合項預覽預覽 UI

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

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

包含「Hello」字詞的簡單文字元素
全世界」

如要啟用這個可組合函式的預覽畫面，請建立另一個並加上註解的可組合函式搭配 @Composable 和 @Preview。這個新的註解可組合項現在包含您先前建立的可組合函式 SimpleComposable：

@Preview
@Composable
fun SimpleComposablePreview() {
    SimpleComposable()
}AndroidStudioComposeSnippets.kt

@Preview 註解會告知 Android Studio 可組合項應顯示在這個檔案的設計檢視畫面中。您可以在進行編輯時，可組合函式預覽畫面會隨之更新。

使用 Compose 顯示即時更新項目的 GIF 圖片
預覽

您可以在程式碼中手動新增參數，以自訂 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")
    }
}AndroidStudioComposeSnippets.kt

顯示「Hello」字樣的黃色正方形
全世界」

動態色彩預覽

如果您已啟用動態調整顏色、使用 wallpaper 屬性切換桌布，查看 UI 的回應方式不同使用者選擇桌布選擇不同的桌布主題提供的 Wallpaper 類別這項功能需要 Compose 1.4.0 以上版本。

搭配不同裝置使用

在 Android Studio Flamingo 中，您可以編輯預覽畫面的 device 參數註解來定義可組合項在不同裝置上的設定。

可組合函式範例
函式

如果裝置參數包含空白字串 (@Preview(device = ""))，您可以按下 Ctrl + Space 鍵可叫用自動完成功能。然後，您可以。

編輯樣本
函式

你可以在自動完成功能中選取任一裝置選項，例如： @Preview(device = "id:pixel_4")。您也可以輸入自訂裝置選擇 spec:width=px,height=px,dpi=int… 來設定個別值每個參數

規格
清單

如要套用，請按下 Enter 鍵，或透過 Esc 取消。

如果您設定的值無效，宣告會以紅色底線標示，修正項目可能會可以使用 (Alt + Enter (⌥ + ⏎) > 取代為 ...。檢查功能會嘗試提供最接近輸入內容的修正方式。

無效示例
值

語言代碼

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

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

包含「Bonjour」字詞的簡單文字元素法語
標記

設定背景顏色

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

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

顯示「Hello」的綠色矩形
全世界」

系統 UI

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

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

UI 模式

uiMode 參數可接受任何 Configuration.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!")
    }
}AndroidStudioComposeSnippets.kt

與 `@Preview` 互動

Android Studio 提供的功能可讓您與定義的預覽。這項互動可協助您瞭解預覽畫面執行階段行為讓您在使用預覽畫面時能更順暢地瀏覽 UI

互動模式

互動模式可讓您以類似的方式與預覽畫面互動透過手機或平板電腦等執行程式的裝置互動模式隔離於沙箱環境中 (意即與其他預覽隔離) 您可在預覽畫面中點選各個元素，並輸入使用者輸入內容。驗證問題可讓您測試各種狀態、手勢，甚至是動畫的可組合項。

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

使用者與某人互動的影片
預先發布版

程式碼導覽與組件概述

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

執行預覽

您可以在模擬器或實體裝置上執行特定 @Preview。預覽會以新的 Activity 部署在相同的專案應用程式中，因此共用相同的背景資訊和權限這個過程不會要求撰寫樣板程式碼，在已取得權限的情況下要求權限。

按一下「Run Preview」圖示。 (位於 @Preview 註解旁邊或預覽頂端) 旁邊 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 FontScalePreviewsAndroidStudioComposeSnippets.kt

您可以將這個自訂註解用於預覽可組合項：

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

顯示大小為大和小的 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)) } }
}AndroidStudioComposeSnippets.kt

顯示可組合函式的 Android Studio 設計分頁
配置

多重預覽的混搭性質和一般預覽！全面測試大型專案的許多屬性

`@Preview` 和大型資料集

往往需要將大型資料集傳遞至可組合項預覽。做法是將範例資料傳送至可組合函式預覽函式，方法是使用 @PreviewParameter 新增參數註解。

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

如要提供範例資料，請建立實作 PreviewParameterProvider，然後傳回用序列式樣本資料

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

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

預覽畫面顯示 Elise、Frank 和 Julia
可組合函式

您可以在多個預覽中使用同一個提供者類別。視需要限制設定限制參數即可預覽試聽次數

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

限制與最佳做法

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 問題窗格，但無法將 `ViewModel` 執行個體化
訊息

如要預覽使用 ViewModel 的可組合項，則應建立另一個可組合函式與 ViewModel 的參數傳遞，並以可組合函式。如此一來，您不需要預覽使用 ViewModel。

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

@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]
) {
  AuthorColumn(...) {
    name = NameLabel(name),
    posts = PostsList(posts)
  }
}

註解類別 `@Preview`

您可以隨時按下「Ctrl」或「⌘ + 」鍵Android 中的 @Preview 註解 Studio 會列出完整的參數清單，可在自訂預覽。

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,
)AndroidStudioComposeSnippets.kt

其他資源

如要進一步瞭解 Android Studio 如何提升 @Preview 的使用便利性，以及瞭解相關知識如需更多工具秘訣，請瀏覽網誌 Compose 工具。

為您推薦

注意：系統會在 JavaScript 關閉時顯示連結文字
使用 CompositionLocal 的本機範圍資料
Compose 中的質感設計 2
在 Compose 中使用 View

動畫預覽及偵錯