コンポーザブルのプレビューで 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 を押してキャンセルしてください。

無効な値を設定すると、宣言に赤い下線が引かれて修正が行われることがあります。 利用可能（macOS の場合は Alt + Enter（⌥ +⏎））> ...に置換。 検査では、入力に最も近い修正が提示されます。

無効な値の例

言語 / 地域

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

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

「Bonjour」という単語を含む単純なテキスト要素フランス語の フラグ

背景色の設定

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

@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_* を指定できます。 定数を使用して、プレビューの動作を適宜変更できます。たとえば、プレビューを夜間モードに設定して、テーマがどのように反応するかを確認できます。

Compose プレビューの 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 を操作しやすくなります

インタラクティブ モード

インタラクティブ モードでは、プログラムを実行しているデバイス（スマートフォンやタブレットなど）で行う場合と同じようにプレビューを操作できます。インタラクティブ モード サンドボックス環境で分離されている（つまり、他のプレビューから分離されている） 要素をクリックし、プレビューでユーザー入力を入力できます。このモードを使用することで、コンポーザブルのさまざまな状態、操作、アニメーションを簡単にテストできます。

プレビューの「インタラクティブ」ボタンをクリックするユーザー

Google Chat を操作するユーザーの動画 プレビュー

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

プレビューにカーソルを合わせると、中に含まれるコンポーザブルの枠線が表示されます。コンポーザブルの枠線をクリックすると、エディタビューがトリガーされ、そこからコンポーザブルの定義に移動できます。

ユーザーがプレビューにカーソルを合わせると、コンポーザブルの枠線が表示される

プレビューを実行

特定の @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 FontScalePreviews
AndroidStudioComposeSnippets.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 つのプレビューがレンダリングされます。

エリーズ、フランク、ジュリアが写ったプレビュー コンポーザブル

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

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

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

Android Studio は、プレビュー コードをプレビュー領域で直接実行します。いいえ エミュレータまたは実機を実行する必要があります。これは、 Layoutlib という Android フレームワークの一部です。Layoutlib はカスタムです Android デバイスの外部で動作するように設計された Android フレームワークのバージョン。「 このライブラリの目的は、Android Studio でレイアウトのプレビューを提供することです。 デバイス上でのレンダリングと非常によく似ています。

プレビューの制限事項

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

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

プレビューと ViewModels

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

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

Android Studio の問題ペインに「ViewModel」をインスタンス化できない メッセージ

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 アノテーション カスタマイズするときに調整できるパラメータの一覧は、 プレビューします。

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 がどのように @Preview の使いやすさを高めているかについて詳しくは、 その他のツールのヒントについては、Compose のブログ Tooling。

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