Preview を収集して UI カタログを構築する

このページでは、Compose Preview Lab を使って UI カタログ（コンポーネント一覧） を構築する方法を紹介します。

ゴール

• プロジェクト内のコンポーネントを Preview 単位で整理する
• PreviewLabGallery を使って「UI カタログ」画面を作る
• 各コンポーネントのバリエーションや状態を手早く確認できるようにする

1. プロジェクトを用意して Compose Preview Lab をインストール

1. Compose Multiplatform プロジェクトを用意します。Compose Multiplatform Wizard が便利です。
2. Install を参考にして Compose Preview Lab をプロジェクトにセットアップしてください。5. (オプション) ターゲットの設定 をスキップせずに jvm, js, wasmJs の ターゲットを設定してください。
3. アプリ内にいくつか @Preview を用意してください。

2. Preview の収集ポイントを宣言する

collectModulePreviews() を使って Preview の収集ポイントを宣言します。

src/commonMain/kotlin/Previews.kt

package app

import me.tbsten.compose.preview.lab.collectModulePreviews

val appPreviews by collectModulePreviews()

プロジェクトをビルドすると、Compiler Plugin がモジュール内の @Preview 関数を検出して appPreviews に自動的に注入します。

Collect Preview の Guide には Preview 収集のカスタマイズ方法が示されているため必要に応じて参照してください。

3. Gallery を実装

収集した Preview を UI として表示します。

プラットフォームごとに Gallery を表示するためのエントリーポイントとなる Composable・関数 が用意されています。

jvm

fun main() {
    application {
        PreviewLabGalleryWindows(
            previewList = appPreviews,
        )
    }
}

js, wasmJs

fun main() {
    ComposeViewport(document.body!!) {
        EmbeddedPreviewOrGallery(
            previewList = appPreviews.toList(),
        )
    }
}

それ以外

PreviewLabGallery(
    previewList = appPreviews,
)

通常通りアプリケーションを実行することでアプリケーション内に Preview 一覧が表示されます。

Gallery の詳しいオプションについては PreviewLabGallery の Guide を参照してください。

4. (オプション) マルチモジュールプロジェクト

collectModulePreviews() はモジュールごとに Preview を収集します。 マルチモジュールプロジェクトでは、collectAllModulePreviews() を使うことで依存モジュールの Preview を自動的に含めることができます。

Step 1: 各依存モジュールで収集ポイントを宣言し、Gradle で export 設定

uiLib/src/commonMain/kotlin/Previews.kt

package uiLib

val uiLibPreviews by collectModulePreviews()

uiLib/build.gradle.kts

composePreviewLab {
    collectPreviewsExport = "uiLib.uiLibPreviews"
}

Step 2: アプリモジュールで collectAllModulePreviews() を使用

app/src/commonMain/kotlin/Previews.kt

package app

val appPreviews by collectAllModulePreviews()
// ↑ app 自身 + uiLib の Preview が自動的に含まれる

次のステップ

• UI カタログで Review 体験を向上する で PR レビューとの連携方法を学ぶ
• PreviewLabGallery の Guide で Gallery の詳細なオプション設定を確認する
• Featured Files で Preview のグループ管理を詳しく知る
• Inspector Tab でカスタムタブを追加し、ドキュメントや設計情報を UI カタログ内に埋め込む