Collect Preview

Compose Preview Lab は、Compiler Plugin を使用してプロジェクト内の @Preview アノテーションを自動的に収集します。

collectModulePreviews() / collectAllModulePreviews() を使って、収集ポイントを宣言します。

val appPreviews by collectModulePreviews()

PreviewLabGallery(
    previewList = appPreviews,
)

セットアップ

1. Gradle Plugin の設定

インストールに従って Gradle Plugin をセットアップします。

`<compose-preview-lab-version>`

<module>/build.gradle.kts
plugins {
    // ⭐️ Compose Preview Lab (Compose Compiler より前に記述)
    id("me.tbsten.compose.preview.lab") version "<compose-preview-lab-version>"
    // Compose Compiler
    id("org.jetbrains.kotlin.plugin.compose")
}

kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("me.tbsten.compose.preview.lab:starter:<compose-preview-lab-version>")
        }
    }
}

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

val プロパティを commonMain に作成します。

src/commonMain/kotlin/Previews.kt
package app

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

val appPreviews by collectModulePreviews()

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

`collectModulePreviews()` vs `collectAllModulePreviews()`

関数	収集範囲
`collectModulePreviews()`	このモジュールの `@Preview` 関数のみ
`collectAllModulePreviews()`	このモジュール + 依存モジュールの `@Preview` 関数

`collectAllModulePreviews()` のセットアップ

依存モジュールの Preview を自動で含めるには、各依存モジュールで collectPreviewsExport を設定します。

uiLib/build.gradle.kts
composePreviewLab {
    collectPreviewsExport = "uiLib.uiLibPreviews"
}

uiLib/src/commonMain/kotlin/Previews.kt
package uiLib

val uiLibPreviews by collectModulePreviews()

app/src/commonMain/kotlin/Previews.kt
package app

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

`@ComposePreviewLabOption`

ComposePreviewLabOption アノテーションを利用して、Preview 収集時のオプションを指定できます。

@ComposePreviewLabOption(
    id = "my_button_preview",
    displayName = "Basic Button Example",
    ignore = false,
)
@Preview
@Composable
private fun MyButtonPreview() = ...

現在サポートされているのは以下の3つです。

`id`	内部管理用のIDを指定します。
`displayName`	PreviewLabGallery で表示する名前を決定します。placeholder, `.` による階層化をサポートしています。（下記参照）
`ignore`	true を設定すると収集を抑制します。

displayName の placeholder

{{qualifiedName}} {{simpleName}} などを displayName の文字列内に含めることでその部分を Composable の変数で置換します。

例えば com.sample.MyButtonPreview に displayName = "{{simpleName}}_1" オプションを指定すると、displayName は MyButtonPreview_1 のように設定されます。

displayName の . による階層化

displayName 内の . は特別な意味を持ちます。

. で区切られたセグメントはディレクトリのように認識されます。

詳しくは ComposePreviewLabOption の KDoc も参照してください。

private Preview

@Preview 関数は通常他のファイルから利用しないため private にするのが一般的です。

Compose Preview Lab の Compiler Plugin は、@Preview が付与された private 関数の visibility を自動的に internal に変更します。これにより、収集された Preview リストから各 Preview 関数を呼び出すことが可能になります。

ソースコード上の private 宣言は変更されません。Compiler Plugin が FIR フェーズで内部的に visibility を変換するため、ユーザーのコードには影響しません。

セットアップ​

1. Gradle Plugin の設定​

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

collectModulePreviews() vs collectAllModulePreviews()​

collectAllModulePreviews() のセットアップ​

@ComposePreviewLabOption​

private Preview​