Skip to main content

All Fields Reference

1. Primitive Fields​

Kotlin の基本的なプリミティブ型（String、Boolean、数値型など）に対応するフィールドです。最も基本的で頻繁に使用されるフィールド群です。

StringField​

対応する 型 kotlin.String
利用頻度 ⭐⭐⭐
KDoc StringField

文字列を入力するためのフィールドです。TextField による文字列入力が可能です。

PreviewLab {
    MyButton(
        text = fieldValue { StringField("text", "Click Me") },
    )
}
prefix や suffix を指定する

prefix と suffix パラメータを使用して、TextField の前後にコンポーザブルを追加できます。 例えば単位を表示する際に有用です。

PreviewLab {
    MyButton(
        text = fieldValue {
            StringField(
                label = "text",
                initialValue = "Click Me",
                prefix = { Text("$") },
                suffix = { Text("USD") },
            )
        },
    )
}
.withTextHint() でよく使うテキスト候補を追加する

MutablePreviewLabField<String>.withTextHint() 拡張関数を使うと、よく使うテキストパターン（空文字・短いテキスト・本文テキスト・長文など）をワンタップで切り替えられるヒントを追加できます。

PreviewLab {
    val description = fieldValue {
        StringField("description", "Short")
            .withTextHint()
    }
    Text(description)
}

withTextHint() の内部では withHint() が使われており、以下のような候補があらかじめ用意されています（実装は StringField の KDoc を参照してください）。

  • Empty: 空文字列
  • Short: 短いテキスト
  • Body: 複数行の本文テキスト
  • Long: 非常に長いテキスト

BooleanField​

対応する 型 kotlin.Boolean
利用頻度 ⭐⭐⭐
KDoc BooleanField

Boolean 値を切り替えるためのフィールドです。トグルスイッチで true と false を選択できます。

PreviewLab {
    MyButton(
        enabled = fieldValue { BooleanField("enabled", true) },
    )
}

数値型フィールド​

Kotlin の数値型（Int、Long、Byte、Double、Float）に対応するフィールドです。数値入力が可能です。

フィールド対応する 型利用頻度KDoc
IntField kotlin.Int ⭐⭐⭐ IntField
LongField kotlin.Long ⭐⭐ LongField
ByteField kotlin.Byte ⭐ ByteField
DoubleField kotlin.Double ⭐⭐ DoubleField
FloatField kotlin.Float ⭐⭐ FloatField

数値型の値を入力するためのフィールドです。TextField による数値入力が可能です。

PreviewLab {
    Counter(
        count = fieldValue { IntField("Count", 0) },
    )
}
inputType で prefix や suffix を指定する

inputType パラメータで NumberField.InputType.TextField を指定すると、prefix と suffix を追加できます。 例えば単位を表示する際に有用です。

PreviewLab {
    Counter(
        count = fieldValue {
            IntField(
                label = "Count",
                initialValue = 0,
                inputType = NumberField.InputType.TextField(
                    prefix = { Text("$") },
                    suffix = { Text("yen") }
                )
            )
        },
    )
}

2. Enhance Fields​

既存のフィールドを拡張・強化するためのフィールドです。選択肢から選ぶフィールド、複数のフィールドを組み合わせるフィールド、既存のフィールドを拡張するユーティリティフィールドが含まれます。詳細は Enhance Fields を参照してください。

SelectableField​

対応する 型 任意の型
利用頻度 ⭐⭐⭐
KDoc SelectableField

指定された選択肢のリストから1つのオプションを選択するためのフィールドです。ドロップダウンまたはチップ形式で表示できます。

PreviewLab {
    MyApp(
        theme = fieldValue {
            SelectableField(
                label = "Theme",
                choices = listOf("Light", "Dark", "Auto")
            )
        },
    )
}
type で表示形式を変更する

type パラメータで SelectableField.Type.CHIPS を指定すると、チップ形式で表示されます。

PreviewLab {
    MyApp(
        theme = fieldValue {
            SelectableField(
                label = "Theme",
                choices = listOf("Light", "Dark", "Auto"),
                type = SelectableField.Type.CHIPS
            )
        },
    )
}
Map から作成する

Map から作成すると、キーがラベル、値が選択肢の値として使用されます。

PreviewLab {
    MyApp(
        theme = fieldValue {
            SelectableField(
                label = "Theme",
                choices = mapOf(
                    "Light Mode" to "Light",
                    "Dark Mode" to "Dark",
                    "Auto (System)" to "Auto"
                )
            )
        },
    )
}
ビルダー構文から作成する

ビルダー構文を使用すると、各選択肢にラベルを設定したり、デフォルト値を指定したりできます。

PreviewLab {
    MyApp(
        theme = fieldValue {
            SelectableField<String>(label = "Theme") {
                choice("Light", label = "Light Mode", isDefault = true)
                choice("Dark", label = "Dark Mode")
                choice("Auto", label = "Auto (System)")
            }
        },
    )
}

EnumField​

対応する 型 kotlin.Enum
利用頻度 ⭐⭐⭐
KDoc EnumField

Enum クラスの値から選択するためのフィールドです。SelectableField のショートハンドとして実装されています。

enum class ButtonVariant { Primary, Secondary, Tertiary }

PreviewLab {
    MyButton(
        variant = fieldValue {
            EnumField("Variant", ButtonVariant.Primary)
        },
    )
}

CombinedField​

対応する 型 任意の複合型
利用頻度 ⭐⭐
KDoc CombinedField

複数のサブフィールドを1つの複合値に結合するフィールドです。combine 関数と split 関数を使用して、複数のフィールドを1つの値にまとめます。

data class Padding(val horizontal: Dp, val vertical: Dp)

PreviewLab {
    Box(
        modifier = Modifier
            .background(Color.LightGray)
            .padding(
                fieldValue {
                    CombinedField(
                        label = "Padding",
                        fields = listOf(
                            DpField("Horizontal", 16.dp),
                            DpField("Vertical", 8.dp)
                        ),
                        combine = { values -> Padding(values[0] as Dp, values[1] as Dp) },
                        split = { listOf(it.horizontal, it.vertical) }
                    )
                }.horizontal,
                fieldValue { /* ... */ }.vertical
            )
    ) {
        Text("Content")
    }
}
combine と split 引数について

combine 関数は、複数のサブフィールドの値を1つの複合値に結合する関数です。split 関数は、複合値を元のサブフィールドの値のリストに分解する関数です。

  • combine: List<Any> -> T の形式で、サブフィールドの値のリストを受け取り、複合型の値を返します
  • split: T -> List<Any> の形式で、複合型の値を受け取り、サブフィールドの値のリストを返します

これらの関数は、CombinedField がサブフィールドの値と複合値の間で変換を行うために使用されます。

combined 関数を使用する

combined 関数を使用すると、より簡潔に記述できます（1〜10個のフィールドに対応）。

1つのフィールドを変換する例：

data class UserId(val value: String)

PreviewLab {
    val userId: UserId = fieldValue {
        combined(
            label = "User ID",
            field1 = StringField("ID", "user-001"),
            combine = { id -> UserId(id) },
            split = { splitedOf(it.value) }
        )
    }

    Text("User ID: ${userId.value}")
}

2つのフィールドを結合する例：

data class Padding(val horizontal: Dp, val vertical: Dp)

PreviewLab {
    Box(
        modifier = Modifier
            .background(Color.LightGray)
            .padding(
                fieldValue {
                    combined(
                        label = "Padding",
                        field1 = DpField("Horizontal", 16.dp),
                        field2 = DpField("Vertical", 8.dp),
                        combine = { h, v -> Padding(h, v) },
                        split = { splitedOf(it.horizontal, it.vertical) }
                    )
                }.horizontal,
                fieldValue {
                    combined(
                        label = "Padding",
                        field1 = DpField("Horizontal", 16.dp),
                        field2 = DpField("Vertical", 8.dp),
                        combine = { h, v -> Padding(h, v) },
                        split = { splitedOf(it.horizontal, it.vertical) }
                    )
                }.vertical
            )
    ) {
        Text("Content")
    }
}

NullableField​

対応する 型 任意の Nullable 型
利用頻度 ⭐⭐
KDoc NullableField

既存のフィールドを Nullable にするためのフィールドです。チェックボックスで null と値の切り替えができます。

PreviewLab {
    UserName(
        userName = fieldValue {
            StringField("User Name", "John Doe").nullable()
        },
    )
}

TransformField​

対応する 型 変換後の任意の型
利用頻度 ⭐
KDoc TransformField

既存のフィールドの値を別の型に変換するためのフィールドです。transform 関数と reverse 関数を使用して型変換を行います。

PreviewLab {
    val intValue = fieldValue {
        StringField("number", "42")
            .transform(
                transform = { it.toIntOrNull() ?: 0 },
                reverse = { it.toString() }
            )
    }
}

WithHintField​

対応する 型 元のフィールドと同じ型
利用頻度 ⭐⭐
KDoc WithHintField

既存のフィールドにヒント選択肢を追加するフィールドです。定義済みの値から素早く選択できるチップが表示されます。

PreviewLab {
    Text(
        text = "Sample Text",
        fontSize = fieldValue {
            SpField(label = "Font Size", initialValue = 16.sp)
                .withHint(
                    "Small" to 12.sp,
                    "Medium" to 16.sp,
                    "Large" to 20.sp,
                    "XLarge" to 24.sp,
                )
        },
    )
}

PolymorphicField​

対応する 型 複数の型から選択可能な型
利用頻度 ⭐⭐
KDoc PolymorphicField

複数のフィールドから1つを選択して使用するフィールドです。値の型に応じて適切なフィールドが自動的に選択され、編集UIが切り替わります。sealed interface や sealed class など、継承階層があるクラスのField化に特に有用です。

sealed interface UiState {
    data object Loading : UiState
    data class Success(val data: String) : UiState
    data class Error(val message: String) : UiState
}

PreviewLab {
    val uiState: UiState = fieldValue {
        PolymorphicField(
            label = "UI State",
            initialValue = UiState.Loading,
            fields = listOf(
                FixedField("Loading", UiState.Loading),
                combined(
                    label = "Success",
                    field1 = StringField("Data", "Sample data"),
                    combine = { data -> UiState.Success(data) },
                    split = { splitedOf(it.data) }
                ),
                combined(
                    label = "Error",
                    field1 = StringField("Message", "Something went wrong"),
                    combine = { message -> UiState.Error(message) },
                    split = { splitedOf(it.message) }
                )
            )
        )
    }

    // ...
}

FixedField​

対応する 型 任意の型（固定値）
利用頻度 ⭐
KDoc FixedField

編集不可の固定値を持つフィールドです。PolymorphicField 内で固定値の選択肢を提供する場合などに使用します。

PreviewLab {
    val value = fieldValue {
        PolymorphicField(
            label = "Value",
            initialValue = "dynamic",
            fields = listOf(
                FixedField("Fixed", UiState.Initial),
                FixedField("Stable", UiState.Stable),
            )
        )
    }
}

WithValueCodeField / .withValueCode()​

任意の Field に対して、Inspector の Code タブに表示されるコード表現だけを差し替えるユーティリティです。UI や値の型はそのままに、コードスニペットを自分のプロジェクトの API 形式に合わせたいときに使用します。

詳細は Enhance Fields を参照してください。

WithSerializerField / .withSerializer()​

対応する 型 元のフィールドと同じ型
利用頻度 ⭐⭐
KDoc WithSerializerField

任意の Field にカスタムシリアライザを設定するユーティリティです。SelectableField で enum や sealed class を使用する場合など、デフォルトでシリアライザを持たない Field にシリアライズ機能を追加したいときに使用します。

@Serializable
enum class Theme { Light, Dark, System }

PreviewLab {
    val theme = fieldValue {
        SelectableField(
            label = "theme",
            choices = Theme.entries,
            choiceLabel = { it.name },
        )
            .withSerializer(Theme.serializer())
    }

    AppTheme(theme = theme)
}

詳細は Enhance Fields を参照してください。

3. Compose Value Fields​

Compose 固有の値型（Dp、Sp、Color、Offset、Size、Modifier、Composable など）に対応するフィールドです。Compose UI の構築に特化した型を扱います。

DpField​

対応する 型 androidx.compose.ui.unit.Dp
利用頻度 ⭐⭐⭐
KDoc DpField

Compose の Dp（密度非依存ピクセル）値を編集するためのフィールドです。自動的に "dp" サフィックスが付きます。

PreviewLab {
    Box(
        modifier = Modifier
            .padding(fieldValue { DpField("Padding", 16.dp) })
    ) {
        Text("Padded Content")
    }
}

SpField​

対応する 型 androidx.compose.ui.unit.TextUnit
利用頻度 ⭐⭐⭐
KDoc SpField

Compose の Sp（スケーラブルピクセル）値を編集するためのフィールドです。フォントサイズなどのテキスト関連の寸法に使用します。自動的に "sp" サフィックスが付きます。

PreviewLab {
    Text(
        text = "Sample Text",
        fontSize = fieldValue { SpField("Font Size", 16.sp) },
    )
}

ColorField​

対応する 型 androidx.compose.ui.graphics.Color
利用頻度 ⭐⭐⭐
KDoc ColorField

Compose の Color を選択するためのフィールドです。インタラクティブなカラーピッカーで HSV スライダーとアルファチャンネルコントロールを使用して色を選択できます。

PreviewLab {
    Box(
        modifier = Modifier
            .size(100.dp)
            .background(fieldValue { ColorField("Background", Color.Blue) })
    )
}

Offset / Size フィールド​

座標やサイズを編集するためのフィールドです。各座標や寸法を独立して編集できます。

フィールド対応する 型利用頻度KDoc
OffsetField androidx.compose.ui.geometry.Offset ⭐⭐ OffsetField
DpOffsetField androidx.compose.ui.unit.DpOffset ⭐⭐ DpOffsetField
SizeField androidx.compose.ui.geometry.Size ⭐⭐ SizeField
DpSizeField androidx.compose.ui.unit.DpSize ⭐⭐ DpSizeField 
PreviewLab {
    Column {
        // OffsetField: Float 単位の座標
        Box(
            modifier = Modifier
                .size(100.dp)
                .graphicsLayer {
                    val offset = fieldValue { OffsetField("Position", Offset(50f, 100f)) }
                    translationX = offset.x
                    translationY = offset.y
                }
        )

        // DpOffsetField: Dp 単位の座標
        Text(
            text = "Positioned Text",
            modifier = Modifier
                .offset(fieldValue { DpOffsetField("Text Offset", DpOffset(16.dp, 8.dp)) })
        )

        // SizeField: Float 単位のサイズ
        Canvas(
            modifier = Modifier.size(200.dp)
        ) {
            val canvasSize = fieldValue { SizeField("Canvas Size", Size(200f, 150f)) }
            drawRect(Color.Blue, size = canvasSize)
        }

        // DpSizeField: Dp 単位のサイズ
        Button(
            onClick = { },
            modifier = Modifier
                .size(fieldValue { DpSizeField("Button Size", DpSize(120.dp, 48.dp)) })
        ) {
            Text("Sized Button")
        }
    }
}

ModifierField​

対応する 型 androidx.compose.ui.Modifier
利用頻度 ⭐⭐⭐
KDoc ModifierField

Compose の Modifier チェーンを構築・編集するためのインタラクティブなフィールドです。ビルダーパターンで複雑な Modifier チェーンを視覚的に構築できます。

PreviewLab {
    Button(
        onClick = { },
        modifier = fieldValue { ModifierField("Button modifier") },
    ) {
        Text("Styled Button")
    }
}
ModifierFieldValue.mark() で視覚的なマーキングを追加する

ModifierFieldValue.mark() を使用すると、視覚的なマーキング（ボーダーと背景）を追加できます。

PreviewLab {
    Button(
        onClick = { },
        modifier = fieldValue {
            ModifierField(
                label = "Button modifier",
                initialValue = ModifierFieldValue.mark()
            )
        },
    ) {
        Text("Styled Button")
    }
}

ComposableField​

対応する 型 @Composable () -> Unit
利用頻度 ⭐⭐
KDoc ComposableField

定義済みの Composable コンテンツオプションから選択するためのフィールドです。

PreviewLab {
    MyContainer(
        content = fieldValue {
            ComposableField(
                label = "Content",
                initialValue = ComposableFieldValue.Red32X32
            )
        },
    )
}
ComposableFieldValue の定義済み値を使用する

ComposableFieldValue には、ColorBox、Text、Empty などの定義済み値が用意されています。

PreviewLab {
    MyContainer(
        content = fieldValue {
            ComposableField(
                label = "Content",
                initialValue = ComposableFieldValue.Red32X32,
                choices = listOf(
                    ComposableFieldValue.Red32X32,
                    ComposableFieldValue.SimpleText,
                    ComposableFieldValue.Empty
                )
            )
        },
    )
}