대화상자 장면 데코레이터 레시피

이 레시피는 대화상자 내에 장면을 표시하는 한 가지 접근 방식을 보여줍니다. 예를 들어 앱이 확장된 창에 있을 때는 목록-세부정보 설정 UI를 오버레이로 표시하지만 그 외의 경우에는 전체 화면 페이지로 표시하는 데 사용할 수 있습니다.

작동 방식

대화상자 내에 장면을 표시하려면 다음을 실행해야 합니다.

  1. 대화상자 SceneDecorationStrategy 만들기: 이 레시피는 DialogSceneDecoratorStrategy와 대화상자 내에서 입력 Scene을 표시하는 데 사용하는 DialogDecoratorScene을 정의합니다. 대화상자 장면 데코레이션 전략을 정의할 때는 다음을 고려하세요.
    1. 장면은 언제 대화상자 내에 표시될 수 있나요? 이 레시피에서 장면은 창 너비가 최소한 확장된 경우에만 대화상자에 표시됩니다.
    2. 장면을 대화상자 내에 표시할 수 있는지 결정하는 메타데이터는 무엇인가요? 이 레시피에서 장면 내의 첫 번째 항목에 DialogSceneMetadataKey 메타데이터가 있으면 장면이 대화상자에 표시됩니다. 사용 사례에 따라 장면 내의 모든 항목에 동일한 메타데이터가 있어야 하는 것과 같은 다른 접근 방식이 더 적절할 수 있습니다.
    3. 대화상자의 닫기 동작은 무엇인가요? 이 레시피에서 대화상자 외부를 클릭하면 장면의 모든 항목이 삭제되는 반면 뒤로 동작 또는 뒤로 버튼을 누르면 한 번에 하나씩만 삭제됩니다. 이 레시피는 DialogDecoratorSceneConfiguration 클래스를 통해 이 동작을 구성할 수 있도록 합니다.
  2. 대화상자 SceneDecorationStrategy 사용: 장면 데코레이터 전략을 사용하려면 NavDisplay 매개변수의 일부로 sceneDecoratorStrategies에 전달합니다.
    1. 주의: NavDisplay는 OverlayScene 인스턴스를 데코레이션하지 않으므로 sceneDecoratorStrategies 목록 내에서 대화상자 장면 데코레이션 전략의 위치에 주의해야 할 수 있습니다. 장면을 데코레이션하면 장면 데코레이션 전략을 따르는 데코레이션이 방지됩니다.
    2. 주의: contentKey를 사용하여 닫을 항목을 식별하는 onDismissAll을 구현할 때는 기본적으로 contentKey가 key.toString()을 사용한다는 점에 유의하세요. 이 레시피에서는 간단한 객체 키에 작동하지만 더 복잡한 키 또는 맞춤 contentKey 구현의 경우 조정이 필요할 수 있는 backStack.removeAll { it.toString() in contentKeys }를 사용합니다.
package com.example.nav3recipes.dialogscenedecorator

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.animation.SharedTransitionLayout
import androidx.compose.material3.Button
import androidx.compose.material3.Text
import androidx.lifecycle.compose.dropUnlessResumed
import androidx.navigation3.runtime.NavKey
import androidx.navigation3.runtime.entryProvider
import androidx.navigation3.runtime.rememberNavBackStack
import androidx.navigation3.ui.NavDisplay
import com.example.nav3recipes.content.ContentBlue
import com.example.nav3recipes.content.ContentGreen
import com.example.nav3recipes.content.ContentYellow
import com.example.nav3recipes.scenes.listdetail.ListDetailScene
import com.example.nav3recipes.scenes.listdetail.rememberListDetailSceneStrategy
import com.example.nav3recipes.ui.setEdgeToEdgeConfig
import kotlinx.serialization.Serializable

@Serializable
private data object Main : NavKey

@Serializable
private data object SettingsList : NavKey

@Serializable
private data object SettingsDetail : NavKey

class DialogSceneDecoratorActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setEdgeToEdgeConfig()

        setContent {
            val backStack = rememberNavBackStack(Main)
            val listDetailSceneStrategy = rememberListDetailSceneStrategy<NavKey>()

            val dialogSceneDecoratorStrategy = rememberDialogSceneDecoratorStrategy<NavKey>(
                onDismissAll = { entriesToDismiss ->
                    // Caution: This relies on the default behavior of NavEntry using key.toString()
                    // to define its contentKey property.
                    entriesToDismiss.forEach { entry ->
                        backStack
                            .indexOfLast { it.toString() == entry.contentKey }
                            .takeIf { it >= 0 }
                            ?.let { backStack.removeAt(it) }
                    }
                }
            )

            SharedTransitionLayout {
                NavDisplay(
                    backStack = backStack,
                    onBack = { backStack.removeLastOrNull() },
                    sceneStrategies = listOf(listDetailSceneStrategy),
                    sceneDecoratorStrategies = listOf(dialogSceneDecoratorStrategy),
                    sharedTransitionScope = this,
                    entryProvider = entryProvider {
                        entry<Main> {
                            ContentGreen("Welcome to Nav3") {
                                Button(onClick = dropUnlessResumed {
                                    backStack.add(SettingsList)
                                }) {
                                    Text("Click to open settings")
                                }
                            }
                        }
                        entry<SettingsList>(
                            metadata = DialogSceneDecoratorStrategy.sceneDialog(
                                DialogDecoratorSceneConfiguration(
                                    backDismissalBehavior = DismissalBehavior.Single
                                )
                            ) + ListDetailScene.listPane()
                        ) {
                            ContentBlue(
                                title = "Settings List",
                            ) {
                                Button(onClick = dropUnlessResumed {
                                    if (backStack.last() !is SettingsDetail) {
                                        backStack.add(SettingsDetail)
                                    }
                                }) {
                                    Text("Open detail")
                                }
                            }
                        }
                        entry<SettingsDetail>(
                            metadata = ListDetailScene.detailPane()
                        ) {
                            ContentYellow("Settings Detail")
                        }
                    }
                )
            }
        }
    }
}

package com.example.nav3recipes.dialogscenedecorator

import androidx.activity.compose.BackHandler
import androidx.compose.foundation.shape.RoundedCornerShape
import androidx.compose.material3.Surface
import androidx.compose.material3.adaptive.currentWindowAdaptiveInfoV2
import androidx.compose.runtime.Composable
import androidx.compose.runtime.remember
import androidx.compose.ui.graphics.Shape
import androidx.compose.ui.unit.dp
import androidx.compose.ui.window.Dialog
import androidx.compose.ui.window.DialogProperties
import androidx.compose.ui.window.SecureFlagPolicy
import androidx.navigation3.runtime.NavEntry
import androidx.navigation3.runtime.NavMetadataKey
import androidx.navigation3.runtime.get
import androidx.navigation3.runtime.metadata
import androidx.navigation3.scene.OverlayScene
import androidx.navigation3.scene.Scene
import androidx.navigation3.scene.SceneDecoratorStrategy
import androidx.navigation3.scene.SceneDecoratorStrategyScope
import androidx.window.core.layout.WindowSizeClass

fun DialogProperties.copy(
    dismissOnBackPress: Boolean = this.dismissOnBackPress,
    dismissOnClickOutside: Boolean = this.dismissOnClickOutside,
    securePolicy: SecureFlagPolicy = this.securePolicy,
    usePlatformDefaultWidth: Boolean = this.usePlatformDefaultWidth,
    decorFitsSystemWindows: Boolean = this.decorFitsSystemWindows,
    windowTitle: String = this.windowTitle
): DialogProperties = DialogProperties(
    dismissOnBackPress = dismissOnBackPress,
    dismissOnClickOutside = dismissOnClickOutside,
    securePolicy = securePolicy,
    usePlatformDefaultWidth = usePlatformDefaultWidth,
    decorFitsSystemWindows = decorFitsSystemWindows,
    windowTitle = windowTitle
)

enum class DismissalBehavior {
    All, Single
}

/**
 * Configuration for the [DialogDecoratorScene].
 *
 * @property dialogProperties The [DialogProperties] used to configure the dialog.
 * @property backDismissalBehavior Whether all entries in the scene should be dismissed when the
 * back button is pressed. This configuration only applies if the
 * [DialogProperties.dismissOnBackPress] is set to `true`.
 *
 */
class DialogDecoratorSceneConfiguration(
    val dialogProperties: DialogProperties = DialogProperties(),
    val backDismissalBehavior: DismissalBehavior = DismissalBehavior.Single,
    val shape: Shape = RoundedCornerShape(16.dp),
) {
    fun toDialogProperties(): DialogProperties {
        // If the desired behavior is to not dismiss all, the DialogProperties passed to the Dialog
        // needs to be configured to not handle the back press itself.
        if (dialogProperties.dismissOnBackPress && backDismissalBehavior != DismissalBehavior.All) {
            return dialogProperties.copy(dismissOnBackPress = false)
        }

        return dialogProperties
    }

    fun shouldDismissSingleOnBackPress() =
        dialogProperties.dismissOnBackPress && backDismissalBehavior == DismissalBehavior.Single

    override fun equals(other: Any?): Boolean {
        if (this === other) return true
        if (other == null || this::class != other::class) return false
        other as DialogDecoratorSceneConfiguration
        return dialogProperties == other.dialogProperties &&
                backDismissalBehavior == other.backDismissalBehavior &&
                shape == other.shape
    }

    override fun hashCode(): Int {
        return dialogProperties.hashCode() * 31 +
                backDismissalBehavior.hashCode() * 31 +
                shape.hashCode() * 31
    }
}

/**
 * [DialogDecoratorScene] is an [OverlayScene] used by [DialogSceneDecoratorStrategy] to present
 * another [Scene] within a [Dialog].
 *
 * @property scene The [Scene] to be displayed within the dialog.
 * @property overlaidEntries The [NavEntry]s that are overlaid by the dialog.
 * @property dialogDecoratorSceneConfiguration The [DialogDecoratorSceneConfiguration] used to
 * configure the dialog scene.
 * @property onBack The callback to be invoked when a back event should be handled
 * @property onDismissAll The callback to be invoked when the entire dialog stack should be dismissed
 **/
data class DialogDecoratorScene<T : Any>(
    private val scene: Scene<T>,
    override val overlaidEntries: List<NavEntry<T>>,
    private val dialogDecoratorSceneConfiguration: DialogDecoratorSceneConfiguration,
    private val onBack: () -> Unit,
    private val onDismissAll: () -> Unit
) : OverlayScene<T>, Scene<T> by scene {

    override val content: @Composable () -> Unit = {
        Dialog(
            onDismissRequest = onDismissAll,
            properties = dialogDecoratorSceneConfiguration.toDialogProperties()
        ) {
            Surface(
                shape = dialogDecoratorSceneConfiguration.shape
            ) {
                scene.content()
            }

            // Because back events are dispatched to the currently focused window, this back handler
            // must be contained within the dialog's content to receive the events.
            BackHandler(dialogDecoratorSceneConfiguration.shouldDismissSingleOnBackPress()) {
                onBack()
            }
        }
    }
}

@Composable
fun <T : Any> rememberDialogSceneDecoratorStrategy(
    windowSizeClass: WindowSizeClass = currentWindowAdaptiveInfoV2().windowSizeClass,
    onDismissAll: ((List<NavEntry<T>>) -> Unit)
): DialogSceneDecoratorStrategy<T> = remember(windowSizeClass, onDismissAll) {
    DialogSceneDecoratorStrategy(windowSizeClass, onDismissAll = onDismissAll)
}

/**
 * A [SceneDecoratorStrategy] that wraps a [Scene] in a [DialogDecoratorScene] if the first
 * [NavEntry] within it has been marked with the [DialogSceneMetadataKey] and the window width
 * is at least [WindowSizeClass.WIDTH_DP_EXPANDED_LOWER_BOUND].
 *
 * If you only need to display a single [NavEntry] in a [Dialog], using
 * [androidx.navigation3.scene.DialogSceneStrategy] instead may be preferable.
 *
 * @property windowSizeClass The current [WindowSizeClass] used to determine if dialogs should be used.
 * @property windowWidthDpBreakpoint the width in dp at or above which a dialog should be displayed.
 * @property onDismissAll callback invoked to dismiss all dialog entries, receives the entries that
 * are currently in the dialog.
 */
class DialogSceneDecoratorStrategy<T : Any>(
    private val windowSizeClass: WindowSizeClass,
    private val windowWidthDpBreakpoint: Int = WindowSizeClass.WIDTH_DP_EXPANDED_LOWER_BOUND,
    private val onDismissAll: (List<NavEntry<T>>) -> Unit
) : SceneDecoratorStrategy<T> {

    override fun SceneDecoratorStrategyScope<T>.decorateScene(scene: Scene<T>): Scene<T> {
        if (!windowSizeClass.isWidthAtLeastBreakpoint(windowWidthDpBreakpoint)) return scene

        val dialogDecoratorSceneConfiguration =
            scene.entries.firstOrNull()?.metadata[DialogSceneMetadataKey] ?: return scene

        // This is critical to ensure that the scenes rendered beneath the dialog don't contain
        // any entries that are in the dialog.
        val overlaidEntries = scene.previousEntries.dropLastWhile { it in scene.entries }

        return DialogDecoratorScene(
            scene,
            overlaidEntries,
            dialogDecoratorSceneConfiguration,
            onBack,
            onDismissAll = { onDismissAll.invoke(scene.entries) })
    }

    companion object {
        object DialogSceneMetadataKey : NavMetadataKey<DialogDecoratorSceneConfiguration>

        fun sceneDialog(dialogDecoratorSceneConfiguration: DialogDecoratorSceneConfiguration = DialogDecoratorSceneConfiguration()): Map<String, Any> =
            metadata {
                put(DialogSceneMetadataKey, dialogDecoratorSceneConfiguration)
            }
    }
}