可組合項是由函式定義,並加上 @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
(⌥ + ⏎) > 取代為 ...。
檢查功能會嘗試提供最接近輸入內容的修正方式。
語言代碼
如要測試不同使用者語言代碼,請新增 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") }
![預覽視窗顯示含有狀態和動作列的活動。](https://developer.android.google.cn/static/develop/ui/compose/images/tooling-decorated-preview.png?authuser=3&hl=zh-tw)
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
部署在相同的專案應用程式中,因此
共用相同的背景資訊和權限這個過程不會要求撰寫
樣板程式碼,在已取得權限的情況下要求權限。
按一下「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 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 會直接在預覽區域中執行預覽程式碼。這沒有
會需要執行模擬器或實體裝置,因為使用已攜碼轉移的裝置
為 Android 架構的一部分,名為 Layoutlib
。「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 中的 @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, )
其他資源
如要進一步瞭解 Android Studio 如何提升 @Preview
的使用便利性,以及瞭解相關知識
如需更多工具秘訣,請瀏覽網誌 Compose
工具。
為您推薦
- 注意:系統會在 JavaScript 關閉時顯示連結文字
- 使用 CompositionLocal 的本機範圍資料
- Compose 中的質感設計 2
- 在 Compose 中使用 View