【Android】＜Kotlin＞Jetpack ComposeのPreview機能についてわかりやすく解説

2025年4月30日

すだ

みなさまこんにちは〜！
メモリアインクのすだです。

Android開発をしていて、
「毎回ビルドしてエミュレータで確認するの、正直面倒くさい…」
と思ったことはありませんか？
Jetpack Compose には、そんな悩みを解消する便利な機能として、 @Preview アノテーションがあります。
今回はこのPreview機能ついて解説していきます。

この記事を読んでわかること…
・Jetpack Compose のPreview機能について

環境

Kotlin (ver 1.9.0)
Android Studio (Giraffe | 2022.3.1 Patch 3)

Jetpack Composeとは？（ざっくり）

Jetpack Compose は、Android公式の宣言的UIツールキットです。
https://developer.android.com/codelabs/jetpack-compose-basics?hl=ja#0

XMLではなくKotlinコードだけでUIを作れるのが特徴です。

（宣言的UIとは：「この状態のとき、このUIを表示してね」と書くスタイルのことです。）

Jetpack ComposeのPreview機能とは？

@Preview は、@Composable 関数に付けることで、Android Studioの画面上でUIをすぐにプレビュー表示できる機能です。
主に以下の特徴があります：

ビルド・実行せずにUIの見た目が確認できる
背景・サイズ・テーマ（ダークモードなど）も指定可能
ライト／ダークの切り替え、複数のプレビュー表示も可能

基本的な使い方とサンプルコード

@Preview(showBackground = true, name = "挨拶プレビュー")
@Composable
fun GreetingPreview() {
    Greeting(name = "山田太郎")
}

@Composable
fun Greeting(name: String) {
    Text(text = "こんにちは、$name さん！")
}

@Composableの上に@Preview(...) を付けるだけで、Android Studio が自動でプレビュー表示してくれます。

showBackground = true をつけると、白背景が表示されてレイアウトが見やすくなるほか、
name = "..." でプレビューラベルを付けられます。

Android StudioのエディタをSplitにすると↓

このようにプレビューを確認することができます。

複数テーマで表示したいとき

@Composable
fun PreviewCard() {
    Surface(
        modifier = Modifier
            .fillMaxWidth()
            .padding(16.dp),
        color = MaterialTheme.colorScheme.background
    ) {
        Text(
            "ダークかライトか確認",
            color = MaterialTheme.colorScheme.onBackground,
            modifier = Modifier.padding(16.dp)
        )
    }
}

@Preview(name = "Light Mode", uiMode = Configuration.UI_MODE_NIGHT_NO)
@Preview(name = "Dark Mode", uiMode = Configuration.UI_MODE_NIGHT_YES)
@Composable
fun PreviewCardWrapper() {
    MyAppTheme {
        PreviewCard()
    }
}

たとえばライトモードのプレビュー（白背景）とダークモードのプレビュー（黒背景）両方を確認したいとき、
このように2つ書くと一度に確認することができます。

よく使うオプションと使い分け

オプション	説明
showBackground = true	背景色（白）を表示してUIを見やすくする
backgroundColor = 0xFFE0E0E0	カスタム背景色（ARGB）を指定
widthDp, heightDp	プレビューの幅・高さを固定する
name = “ラベル名”	Android Studio上のプレビュー名を指定
uiMode = Configuration.UI_MODE_NIGHT_YES	ダークモード用プレビューに切り替える

注意点

Jetpack Compose の @Preview は、基本的に「引数なし or 引数にデフォルト値がある関数」しかプレビューできません。

例えば以下のようなコード：

@Composable
fun Greeting(name: String) {
    Text("こんにちは、$name さん")
}

@Preview
@Composable
fun PreviewGreeting() {
    Greeting() // ← これは name にデフォルト値がないのでエラー
}

これはエラーになります。

解決策としては：

解決策①

@Composable
fun Greeting(name: String = "プレビュー") {
    Text("こんにちは、$name さん")
}

このようにデフォルト値をつけるか、

解決策②

@Composable
fun Greeting(name: String) {
    Text("こんにちは、$name さん")
}

@Preview
@Composable
fun PreviewGreeting() {
    Greeting(name = "佐藤さん") // モック値を渡す
}

引数を明示的に渡す @Preview 用関数を別に作るかなどの対策を行ってください。