コンポーザブルは関数によって定義され、@Composable
アノテーションが付けられます。
@Composable fun SimpleComposable() { Text("Hello World") }
このコンポーザブルのプレビューを有効にするには、@Composable
と @Preview
アノテーションを付けた別のコンポーザブルを作成します。この新しいアノテーション付きコンポーザブルに、最初に作成したコンポーザブル SimpleComposable
が追加されました。
@Preview @Composable fun SimpleComposablePreview() { SimpleComposable() }
@Preview
アノテーションは、このコンポーザブルをこのファイルのデザインビューに表示する必要があることを Android Studio に伝えます。編集を行うと、コンポーザブルのプレビューがリアルタイムで更新されます。
コードに手動でパラメータを追加して、Android Studio が @Preview
をレンダリングする方法をカスタマイズできます。@Preview
アノテーションを同じ関数に複数回追加して、異なるプロパティを持つコンポーザブルをプレビューすることもできます。
@Preview
コンポーザブルを使用する主なメリットの 1 つは、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 以降では、マルチプレビュー API テンプレート @PreviewScreenSizes
、@PreviewFontScales
、@PreviewLightDark
、@PreviewDynamicColors
が導入されているため、1 つのアノテーションで一般的なシナリオで 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") ) }
これにより、シーケンスのデータ要素ごとに 1 つのプレビューがレンダリングされます。
複数のプレビューに同じプロバイダ クラスを使用できます。必要に応じて、limit パラメータを設定してプレビューの数を制限します。
@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
Android Studio では、いつでも @Preview
アノテーションを Ctrl または ⌘ を押しながらクリックすることで、プレビューをカスタマイズするときに調整できるパラメータの完全なリストが表示されます。
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 でビューを使用する