可組合項是由函式定義,並加上 @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 中,您可以編輯 Preview 註解的 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)) }
設定背景顏色
根據預設,組件會配合透明背景顯示。如要新增
背景,請加入 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
您隨時可以按住 Ctrl 或 ⌘ 鍵並點選 Android Studio 中的 @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