可組合項是由函式定義,並加上 @Composable
註解:
@Composable fun SimpleComposable() { Text("Hello World") }
如要啟用此可組合項的預覽,請建立另一個可組合項,並加上 @Composable
和 @Preview
註解。這個新的註解可組合項現在包含您一開始建立的可組合項 SimpleComposable
:
@Preview @Composable fun SimpleComposablePreview() { SimpleComposable() }
@Preview
註解會指示 Android Studio 此可組合項應顯示在此檔案的設計檢視畫面中。您可以在編輯內容時,查看可組合函式預覽畫面的即時更新內容。
您可以在程式碼中手動新增參數,以自訂 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") } }
動態色彩預覽
如果已在應用程式中啟用動態色彩,請使用 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
(⌥ + ⏎,適用於 macOS) >「Replace with ...」)。檢查功能會嘗試提供最接近輸入內容的修正方式。
語言代碼
如要測試不同使用者語言代碼,請新增 locale
參數:
@Preview(locale = "fr-rFR") @Composable fun DifferentLocaleComposablePreview() { Text(text = stringResource(R.string.greeting)) }
設定背景顏色
可組合函式預設會以透明背景顯示。如要新增背景,請新增 showBackground
和 backgroundColor
參數。請注意,backgroundColor
是 ARGB Long
,而不是 Color
值:
@Preview(showBackground = true, backgroundColor = 0xFF00FF00) @Composable fun WithGreenBackground() { Text("Hello World") }
系統 UI
如果您需要在預覽畫面中顯示狀態和動作列,請新增 showSystemUi
參數:
@Preview(showSystemUi = true) @Composable fun DecoratedComposablePreview() { Text("Hello World") }
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!") } }
與 @Preview
互動
Android Studio 提供多項功能,可讓您與定義的預覽畫面互動。這項互動可協助您瞭解預覽的執行階段行為,並讓您在使用預覽時更順利瀏覽 UI。
互動模式
互動模式可讓您與預覽互動,就像在手機或平板電腦等執行程式的裝置上互動一樣。互動模式在沙箱環境 (意即與其他預覽隔離) 中隔離,因此您能在預覽畫面中點選元素,並輸入使用者輸入內容。透過這種模式,您可以快速測試可組合項的不同狀態、手勢,甚至是動畫。
程式碼導覽與組件概述
將滑鼠遊標懸停在預覽畫面上,即可查看內含可組合項的外框。按一下組件概述,會觸發編輯器檢視畫面,供您查看定義。
執行預覽
您可以在模擬器或實體裝置上執行特定 @Preview
。預覽會以新的 Activity
形式部署在相同的專案應用程式中,因此會共用相同的背景資訊和權限。如果已經授予權限,則您無須編寫要求權限的樣板程式碼。
在 @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") }
您可以合併多個多重預覽註解和一般預覽註解,建立更完整的預覽組合。合併多重預覽註解並不代表會顯示各種不同的組合。因此,每個多重預覽註解都會獨立運作,且只會轉譯各自的變化版本。
@Preview( name = "Spanish", group = "locale", locale = "es" ) @FontScalePreviews annotation class CombinedPreviews @CombinedPreviews @Composable fun HelloWorldPreview2() { MaterialTheme { Surface { Text(stringResource(R.string.hello_world)) } } }
多重預覽模式的混合及比對性質和一般預覽!可讓您更全面地測試大型專案的許多屬性。
@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") ) }
這樣會為序列中每個資料元素算繪一個預覽畫面:
您可以在多個預覽中使用同一個提供者類別。如有需要,請設定限制參數來限制預覽數量。
@Preview @Composable fun UserProfilePreview2( @PreviewParameter(UserPreviewParameterProvider::class, limit = 2) user: User ) { UserProfile(user) }
限制與最佳做法
Android Studio 會直接在預覽區域中執行預覽程式碼。它不需要執行模擬器或實體裝置,因為利用了名為 Layoutlib
的 Android 架構移植部分。Layoutlib
是 Android 架構的自訂版本,可在 Android 裝置以外的地方執行。這個程式庫的目標是在 Android Studio 中提供最接近在裝置上算繪的版面配置的預覽功能。
試聽功能的限制
預覽在 Android Studio 中算繪的方式,因此輕微,不需要整個 Android 架構即可算繪。但有下列限制:
- 沒有網路存取權
- 沒有檔案存取權
- 可能無法完整使用某些
Context
API。
預覽和ViewModels
在可組合項中使用 ViewModel
時,預覽會受到限制。預覽系統無法建構所有傳遞至 ViewModel
的參數,例如存放區、用途、管理工具或類似項目。此外,如果您的 ViewModel
採用依附元件插入 (例如使用 Hilt),則預覽系統無法建構完整的依附元件圖表來建構 ViewModel
。
當您嘗試使用 ViewModel
預覽可組合項時,Android Studio 會在算繪特定可組合項時顯示錯誤:
如要預覽使用 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
您隨時可以在 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 如何提升 @Preview
的易用性,並瞭解更多工具使用秘訣,請參閱網誌:Compose 工具。
為您推薦
- 注意:系統會在 JavaScript 關閉時顯示連結文字
- 使用 CompositionLocal 的本機範圍資料
- Compose 中的質感設計 2
- 在 Compose 中使用 View