コンポーザブルのプレビューで UI をプレビューする

コンポーザブルは、関数で定義され、@Composable アノテーションが付けられます。

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

「Hello World」という語句を含む単純なテキスト要素

このコンポーザブルのプレビューを有効にするには、@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 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（macOS の場合は ⌥ + ⏎）> [Replace with …]）。インスペクションでは、入力に最も近い修正が提供されます。

無効な値の例

言語/地域

さまざまなユーザーロケールをテストするには、locale パラメータを追加します。

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

「Bonjour」という単語とフランス国旗を含むシンプルなテキスト要素

背景色の設定

デフォルトでは、コンポーザブルは透明の背景で表示されます。背景を追加するには、showBackground パラメータと backgroundColor パラメータを追加します。は ARGB Long 値ではなく Color であることに注意してください。backgroundColor

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

「Hello World」と書かれた緑色の長方形

システム 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 としてデプロイされるので、同じコンテキストと権限を共有します。すでに権限が付与されている場合は、権限の要求などのボイラープレートコードを記述する必要はありません。

[プレビューを実行] アイコン @Preview アノテーションの隣またはプレビューの上部にあるをクリックすると、その @Preview が Android Studio によって接続済みのデバイスまたはエミュレータにデプロイされます。

プレビューの「プレビューを実行」ボタンをクリックするユーザー

デバイスにプレビューをデプロイするユーザーの動画

`@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 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

これにより、シーケンス内のデータ要素ごとに 1 つのプレビューがレンダリングされます。

Elise、Frank、Julia コンポーザブルのプレビュー

複数のプレビューに同じプロバイダクラスを使用できます。必要に応じて limit パラメータを設定して、プレビューの数を制限します。

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

@PreviewParameter を使用するプレビューには、デフォルトでパラメータインデックスとプロパティ名（user 0、user 1、user 2 など）が使用されるため、区別が難しい場合があります。プレビューの明瞭さを高めるには、PreviewParameterProvider で getDisplayName() をオーバーライドして、各プレビューにカスタム表示名を指定します。これにより、さまざまなデータのバリエーションや UI の状態を区別できます。たとえば、入力データに基づいてプレビューにラベルを付けることができます。

class UserAgePreviewParameterProvider : PreviewParameterProvider<User> {
    // Using a List internally for efficient index-based access
    private val userList = listOf(
        User(name = "Elise", age = 30),
        User(name = "Frank", age = 31),
        User(name = "Julia", age = 40)
    )

    override val values = userList.asSequence()

    override fun getDisplayName(index: Int): String? {
        // Return null or an empty string to use the default index-based name
        val user = userList.getOrNull(index) ?: return null
        return "${user.name} - ${user.age}"
    }
}AndroidStudioComposeSnippets.kt

カスタム表示名でプレビューを表示し、Elise - 30、Frank - 31、Julia - 40 のコンポーザブルを表示する

AI を活用したプレビューの生成

Android Studio の AI エージェントは、コンポーザブルの Compose プレビューを自動的に生成できます。コンポーズ可能な関数を右クリックして、AI > Generate Preview for [コンポーザブル名] を選択します。エージェントはコンポーザブルを分析して、正しいパラメータで必要な @Preview ボイラープレートを生成し、UI が想定どおりにレンダリングされることを迅速に確認できるようにします。

アノテーションクラス `@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,
)AndroidStudioComposeSnippets.kt

制限事項とベストプラクティス

Android Studio は、プレビュー領域でプレビューコードを直接実行します。Layoutlib という Android フレームワークの移植された部分を活用しているため、エミュレータや実機を実行する必要はありません。Layoutlib は、Android デバイス以外で実行できるように設計された Android フレームワークのカスタムバージョンです。このライブラリの目的は、Android Studio で、デバイスでのレンダリングに非常に近いレイアウトのプレビューを提供することです。

プレビューの制限事項

Android Studio 内でプレビューがレンダリングされる方法により、プレビューは軽量で、レンダリングに Android フレームワーク全体を必要としません。ただし、次のような制限があります。

ネットワークにアクセスできない
ファイルにアクセスできない
一部の Context API を使用できない可能性がある

プレビューと `ViewModels`

コンポーザブル内で ViewModel を使用する場合、プレビューは制限されます。プレビューシステムは、リポジトリ、ユースケース、マネージャーなど、ViewModel に渡されるすべてのパラメータを構築できません。また、ViewModel が依存性注入（such as with Hilt など）に参加している場合、プレビューシステムは依存関係グラフ全体を構築して ViewModel を構築できません。

ViewModel を使用してコンポーザブルをプレビューしようとすると、特定のコンポーザブルのレンダリング時に Android Studio にエラーが表示されます。

Android Studio の問題ペインに「Failed to instantiate a `ViewModel`」というメッセージが表示されている

ViewModel を使用するコンポーザブルをプレビューする場合は、ViewModel のパラメータをコンポーザブルの引数として渡して、別のコンポーザブルを作成する必要があります。このようにすると、ViewModel を使用するコンポーザブルをプレビューする必要がなくなります。

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

@Composable
fun AuthorScreen(
  name: NameLabel,
  posts: PostsList
) {
  // ...
}

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

参考情報

Android Studio での @Preview の使いやすさの向上について詳しくは、Tooling のヒントやブログ Compose Tooling をご覧ください。

あなたへのおすすめ

注: JavaScript がオフになっている場合はリンクテキストが表示されます
CompositionLocal でローカルにスコープ設定されたデータ
Compose のマテリアルデザイン 2
Compose でビューを使用する

アニメーションのプレビューとデバッグ

コンポーザブルのプレビューで UI をプレビューする コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

@Preview を定義する

サイズ

ダイナミック カラーのプレビュー

さまざまなデバイスで使用する

言語/地域

背景色の設定

システム UI

UI モード

LocalInspectionMode

@Preview を操作する

インタラクティブ モード

コード ナビゲーションとコンポーザブルの枠線