Compose 平板适配

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

composeApp/src/commonMain/kotlin/com/example/app/
├─ App.kt
├─ navigation/
│  ├─ AppNavigationHost.kt       # NavDisplay 入口，给 route 绑定 pane 元数据
│  ├─ AppNavigationState.kt      # 统一维护返回栈和 Push/Pop/Replace 语义
│  ├─ AppRoute.kt                # 强类型路由定义
│  └─ AppStartEndScene.kt        # 平板双栏 Scene 与 SceneStrategy 核心实现
└─ ui/
   ├─ FeatureScreens.kt          # 模块页、详情页、二级页、三级页、全屏页
   └─ StartEndPlaceholderScreen.kt # 平板右侧空状态欢迎页

1
2
3
4
5

commonMain.dependencies {
    implementation(libs.compose.material3)
    implementation(libs.compose.material3.adaptive.navigation3)
    implementation(libs.jetbrains.navigation3.ui)
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

@Composable
@OptIn(ExperimentalMaterial3AdaptiveApi::class)
fun <T : Any> rememberAppStartEndSceneStrategy(
    navigationOperation: NavigationOperation,
): AppStartEndSceneStrategy<T> {
    val windowSizeClass = currentWindowAdaptiveInfo().windowSizeClass
    val containerDpSize = LocalWindowInfo.current.containerDpSize
    val isLandscapeLike = containerDpSize.width > containerDpSize.height
    return remember(windowSizeClass, isLandscapeLike, navigationOperation) {
        AppStartEndSceneStrategy(
            windowSizeClass = windowSizeClass,
            isLandscapeLike = isLandscapeLike,
            navigationOperation = navigationOperation,
        )
    }
}

1
2
3
4
5

if (deviceInfo.isTablet) {
    useTwoPaneLayout()
} else {
    useSinglePaneLayout()
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

override fun SceneStrategyScope<T>.calculateScene(
    entries: List<NavEntry<T>>,
): Scene<T>? {
    val topEntry = entries.lastOrNull()

    if (
        !windowSizeClass.isWidthAtLeastBreakpoint(WIDTH_DP_MEDIUM_LOWER_BOUND) ||
        !isLandscapeLike
    ) {
        return null
    }

    if (topEntry?.isFullScreenPane() == true) {
        return null
    }

    // 后面继续从返回栈中找 startEntry / endEntry，组装 AppStartEndScene
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

entry<AppRoute.FeatureFullScreen>(
    metadata = AppStartEndScene.fullScreenPane(),
) { route ->
    FeatureFullScreenScreen(
        module = route.module,
        platformName = platformName,
        onBack = {
            navigationState.popIfPossible()
        },
    )
}

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320

package com.example.app.navigation

import androidx.compose.animation.AnimatedContent
import androidx.compose.animation.EnterTransition
import androidx.compose.animation.ExitTransition
import androidx.compose.animation.slideInHorizontally
import androidx.compose.animation.slideOutHorizontally
import androidx.compose.animation.togetherWith
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.material3.adaptive.ExperimentalMaterial3AdaptiveApi
import androidx.compose.material3.adaptive.currentWindowAdaptiveInfo
import androidx.compose.runtime.Composable
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier
import androidx.compose.ui.platform.LocalWindowInfo
import androidx.navigation3.runtime.NavEntry
import androidx.navigation3.scene.Scene
import androidx.navigation3.scene.SceneStrategy
import androidx.navigation3.scene.SceneStrategyScope
import androidx.window.core.layout.WindowSizeClass
import androidx.window.core.layout.WindowSizeClass.Companion.WIDTH_DP_MEDIUM_LOWER_BOUND
import com.example.app.ui.StartEndWelcomeScreen

private const val APP_START_PANE_KEY = "AppStartEndScene-Start"
private const val APP_END_PANE_KEY = "AppStartEndScene-End"
private const val APP_FULL_SCREEN_PANE_KEY = "AppStartEndScene-FullScreen"
private const val APP_END_PLACEHOLDER_KEY = "AppStartEndScene-Placeholder"
private const val APP_START_END_SCENE_KEY = "AppStartEndScene-Key"

/**
 * 应用自己的 start-end Scene。
 *
 * 为什么这里不继续沿用早期的 list/detail 命名？
 *
 * 因为当前这套布局在正式项目里，更接近“起始侧 / 结束侧”的通用双栏模型：
 * - 左边是 start pane
 * - 右边是 end pane
 *
 * 这样命名后，不会把这套能力绑死在“列表 + 详情”这个特定业务语义上。
 * 未来即使左边不是列表、右边也不是详情页，这个 Scene 仍然成立。
 */
class AppStartEndScene<T : Any>(
    override val key: Any,
    override val previousEntries: List<NavEntry<T>>,
    private val startEntry: NavEntry<T>,
    private val endRootContentKey: Any,
    private val endEntry: NavEntry<T>?,
    private val navigationOperation: NavigationOperation,
) : Scene<T> {

    /**
     * 当前 Scene 真正参与渲染的 entry。
     *
     * 它只关心两件事：
     * - start pane 里显示谁
     * - end pane 当前顶部显示谁
     */
    override val entries: List<NavEntry<T>> = buildList {
        add(startEntry)
        endEntry?.let(::add)
    }

    /**
     * Scene 的 UI 定义。
     *
     * start pane 始终稳定；
     * end pane 内部通过 `AnimatedContent` 做页面切换。
     *
     * 这样手机和 Pad 共享同一份返回栈时：
     * - 手机上，仍然是全屏逐级跳转
     * - Pad 上，只有右侧 end pane 在变化
     */
    override val content: @Composable (() -> Unit) = {
        Row(
            modifier = Modifier.fillMaxSize(),
        ) {
            Column(
                modifier = Modifier.weight(0.35f),
            ) {
                startEntry.Content()
            }

            Column(
                modifier = Modifier.weight(0.65f),
            ) {
                AnimatedContent(
                    targetState = EndPaneState(
                        entry = endEntry,
                        rootContentKey = endRootContentKey,
                    ),
                    contentKey = { state -> state.contentKey },
                    transitionSpec = {
                        /**
                         * end pane 的动画规则有两层语义：
                         *
                         * 1. 左侧切换到另一个功能模块
                         *    例如：`存储 -> 权限`
                         *    这种属于整条 end flow 被替换，应直接切换
                         *
                         * 2. 同一功能模块内部继续深入
                         *    例如：`详情 -> 二级页 -> 三级页`
                         *    这种才属于真正的 push/pop，需要左右滑动
                         *
                         * 因此这里同时比较：
                         * - `rootContentKey`：当前 end flow 属于哪个根页面
                         * - `navigationOperation`：最近一次导航语义
                         *
                         * 这样页面作者只需要声明：
                         * - 我是不是 end pane
                         *
                         * 不需要再声明：
                         * - 我是第几层页面
                         */
                        if (initialState.rootContentKey != targetState.rootContentKey) {
                            EnterTransition.None togetherWith ExitTransition.None
                        } else {
                            when (navigationOperation) {
                                NavigationOperation.Push -> {
                                    slideInHorizontally(
                                        initialOffsetX = { width -> width },
                                    ) togetherWith slideOutHorizontally(
                                        targetOffsetX = { width -> -width },
                                    )
                                }

                                NavigationOperation.Pop -> {
                                    slideInHorizontally(
                                        initialOffsetX = { width -> -width },
                                    ) togetherWith slideOutHorizontally(
                                        targetOffsetX = { width -> width },
                                    )
                                }

                                NavigationOperation.Replace,
                                NavigationOperation.Restore -> {
                                    EnterTransition.None togetherWith ExitTransition.None
                                }
                            }
                        }
                    },
                    label = "app-end-pane-transition",
                ) { state ->
                    if (state.entry == null) {
                        StartEndWelcomeScreen()
                    } else {
                        state.entry.Content()
                    }
                }
            }
        }
    }

    companion object {
        /**
         * 标记这个 entry 可以出现在 start pane。
         */
        fun startPane() = mapOf(APP_START_PANE_KEY to true)

        /**
         * 显式标记这个 entry 可以出现在 end pane。
         *
         * 当前项目里，end pane 已经是默认约定：
         * - 没有标记为 `startPane`
         * - 也没有标记为 `fullScreenPane`
         *
         * 那么就默认视为 end pane。
         *
         * 所以这个方法现在更多是“允许显式声明”，
         * 而不是必须在每个右侧页面上手写。
         */
        fun endPane() = mapOf(APP_END_PANE_KEY to true)

        /**
         * 标记这个 entry 是一个真正的全屏页面。
         *
         * 它不再属于 start/end 双栏里的 end pane，
         * 而是要临时退出双栏 Scene，交给 `NavDisplay` 按整屏方式展示。
         */
        fun fullScreenPane() = mapOf(APP_FULL_SCREEN_PANE_KEY to true)
    }
}

/**
 * 记住应用自己的 start-end SceneStrategy。
 *
 * 判定规则保持简单：
 * - 宽度至少达到中等断点
 * - 且窗口更偏横向，避免大屏竖屏也强行双栏
 * - start pane 必须存在
 * - end pane 可以为空；为空时右侧显示占位页
 */
@Composable
@OptIn(ExperimentalMaterial3AdaptiveApi::class)
fun <T : Any> rememberAppStartEndSceneStrategy(
    navigationOperation: NavigationOperation,
): AppStartEndSceneStrategy<T> {
    val windowSizeClass = currentWindowAdaptiveInfo().windowSizeClass
    val containerDpSize = LocalWindowInfo.current.containerDpSize
    val isLandscapeLike = containerDpSize.width > containerDpSize.height
    return remember(windowSizeClass, isLandscapeLike, navigationOperation) {
        AppStartEndSceneStrategy(
            windowSizeClass = windowSizeClass,
            isLandscapeLike = isLandscapeLike,
            navigationOperation = navigationOperation,
        )
    }
}

/**
 * 应用自己的 SceneStrategy。
 *
 * 这里最关键的是：
 * Scene 的 `key` 固定为同一个常量 key。
 *
 * 这样无论 start pane 是“模块页”还是“登录页”，
 * 只要它们都属于同一个 start/end 双栏场景，
 * Navigation 3 都不会把整个 Scene 当成“整块替换”。
 *
 * 这样一来：
 * - start pane 底部 Tab 切换时，不会触发整页级的场景替换
 * - end pane 的动画机会仍然留给 Scene 内部的 `AnimatedContent`
 */
class AppStartEndSceneStrategy<T : Any>(
    private val windowSizeClass: WindowSizeClass,
    private val isLandscapeLike: Boolean,
    private val navigationOperation: NavigationOperation,
) : SceneStrategy<T> {

    override fun SceneStrategyScope<T>.calculateScene(
        entries: List<NavEntry<T>>,
    ): Scene<T>? {
        val topEntry = entries.lastOrNull()

        if (
            !windowSizeClass.isWidthAtLeastBreakpoint(WIDTH_DP_MEDIUM_LOWER_BOUND) ||
            !isLandscapeLike
        ) {
            return null
        }

        /**
         * 如果当前顶部页面已经是全屏页，
         * 那么双栏 Scene 必须主动退出。
         *
         * 这样 Pad 下才会真正显示“覆盖整个内容区”的全屏页面，
         * 而不是继续把它硬塞进 end pane。
         */
        if (topEntry?.isFullScreenPane() == true) {
            return null
        }

        val endEntry = topEntry
            ?.takeIf { entry -> entry.isEndPane() }
        val endRootEntry = entries.firstOrNull { entry ->
            entry.isEndPane()
        }
        val startEntry = entries.findLast { entry ->
            entry.isStartPane()
        } ?: return null

        return AppStartEndScene(
            key = APP_START_END_SCENE_KEY,
            previousEntries = entries.dropLast(1),
            startEntry = startEntry,
            endRootContentKey = endRootEntry?.contentKey ?: APP_END_PLACEHOLDER_KEY,
            endEntry = endEntry,
            navigationOperation = navigationOperation,
        )
    }
}

/**
 * end pane 当前要展示的状态。
 *
 * 这里故意不直接把 `NavEntry?` 作为动画状态，
 * 而是再包一层，显式携带：
 * - 当前 end flow 属于哪个根页面
 *
 * 这样动画逻辑才能准确区分：
 * - 当前是不是同一条 end flow
 * - 当前内容是否真的发生切换
 */
private data class EndPaneState<T : Any>(
    val entry: NavEntry<T>?,
    val rootContentKey: Any,
) {
    val contentKey: Any = entry?.contentKey ?: APP_END_PLACEHOLDER_KEY
}

/**
 * 当前 entry 是否属于 start pane。
 */
private fun <T : Any> NavEntry<T>.isStartPane(): Boolean {
    return metadata.containsKey(APP_START_PANE_KEY)
}

/**
 * 当前 entry 是否属于 full screen 页面。
 */
private fun <T : Any> NavEntry<T>.isFullScreenPane(): Boolean {
    return metadata.containsKey(APP_FULL_SCREEN_PANE_KEY)
}

/**
 * 当前 entry 是否属于 end pane。
 *
 * 当前项目采用“默认右侧”的约定：
 * - 不是 start pane
 * - 不是 full screen
 *
 * 那么就按 end pane 处理。
 *
 * 这样多数业务页面都不需要反复写：
 * `metadata = AppStartEndScene.endPane()`
 */
private fun <T : Any> NavEntry<T>.isEndPane(): Boolean {
    return metadata.containsKey(APP_END_PANE_KEY) || (!isStartPane() && !isFullScreenPane())
}

1
2
3
4
5
6
7
8

class AppStartEndScene<T : Any>(
    override val key: Any,
    override val previousEntries: List<NavEntry<T>>,
    private val startEntry: NavEntry<T>,
    private val endRootContentKey: Any,
    private val endEntry: NavEntry<T>?,
    private val navigationOperation: NavigationOperation,
) : Scene<T>

1

栈顶 entry -> 全屏显示

1
2

startEntry -> 左侧显示
endEntry   -> 右侧显示

1
2
3
4
5
6

override val key: Any,
override val previousEntries: List<NavEntry<T>>,
private val startEntry: NavEntry<T>,
private val endRootContentKey: Any,
private val endEntry: NavEntry<T>?,
private val navigationOperation: NavigationOperation,

1
2
3
4

override val entries: List<NavEntry<T>> = buildList {
    add(startEntry)
    endEntry?.let(::add)
}

1

Home -> Feature -> FeatureSubPage -> FeatureThirdPage

1
2

左侧：Home
右侧：FeatureThirdPage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

override val content: @Composable (() -> Unit) = {
    Row(modifier = Modifier.fillMaxSize()) {
        Column(modifier = Modifier.weight(0.35f)) {
            startEntry.Content()
        }

        Column(modifier = Modifier.weight(0.65f)) {
            AnimatedContent(
                targetState = EndPaneState(
                    entry = endEntry,
                    rootContentKey = endRootContentKey,
                ),
                transitionSpec = { createEndPaneTransition() },
                contentKey = { state -> state.entry?.contentKey },
            ) { state ->
                if (state.entry == null) {
                    StartEndWelcomeScreen()
                } else {
                    state.entry.Content()
                }
            }
        }
    }
}

1
2
3
4
5
6
7
8
9

Row(modifier = Modifier.fillMaxSize()) {
    Column(modifier = Modifier.weight(0.35f)) {
        startEntry.Content()
    }

    Column(modifier = Modifier.weight(0.65f)) {
        // end pane
    }
}

1
2

Column(modifier = Modifier.weight(0.35f))
Column(modifier = Modifier.weight(0.65f))

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

entry<AppRoute.Home> {
    ModuleHomeScreen(
        platformName = platformName,
        selectedModule = navigationState.currentModuleOrNull(),
        onOpenModule = { module ->
            navigationState.replacePath(
                AppRoute.Home,
                AppRoute.Feature(module),
            )
        },
        onOpenLoginTab = {
            navigationState.replacePath(
                AppRoute.LoginHome,
                AppRoute.LoginStatus,
            )
        },
    )
}

1

startEntry.Content()

1

state.entry.Content()

1
2
3
4

EndPaneState(
    entry = endEntry,
    rootContentKey = endRootContentKey,
)

1
2
3

if (initialState.rootContentKey != targetState.rootContentKey) {
    EnterTransition.None togetherWith ExitTransition.None
}

1
2
3

NavigationOperation.Push ->
    slideInHorizontally(initialOffsetX = { width -> width }) togetherWith
    slideOutHorizontally(targetOffsetX = { width -> -width })

1
2
3

NavigationOperation.Pop ->
    slideInHorizontally(initialOffsetX = { width -> -width }) togetherWith
    slideOutHorizontally(targetOffsetX = { width -> width })

1
2
3

NavigationOperation.Replace,
NavigationOperation.Restore ->
    EnterTransition.None togetherWith ExitTransition.None

1
2
3
4
5

if (state.entry == null) {
    StartEndWelcomeScreen()
} else {
    state.entry.Content()
}

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133

    NavDisplay(
        backStack = navigationState.backStack,
        modifier = modifier,
        onBack = {
            navigationState.popIfPossible()
        },
        sceneStrategy = rememberAppStartEndSceneStrategy<NavKey>(
            navigationOperation = navigationState.lastOperation,
        ),
        transitionSpec = {
            slideInHorizontally(
                initialOffsetX = { fullWidth -> fullWidth },
                animationSpec = tween(durationMillis = 300),
            ) togetherWith slideOutHorizontally(
                targetOffsetX = { fullWidth -> -fullWidth },
                animationSpec = tween(durationMillis = 300),
            )
        },
        popTransitionSpec = {
            slideInHorizontally(
                initialOffsetX = { fullWidth -> -fullWidth },
                animationSpec = tween(durationMillis = 300),
            ) togetherWith slideOutHorizontally(
                targetOffsetX = { fullWidth -> fullWidth },
                animationSpec = tween(durationMillis = 300),
            )
        },
        predictivePopTransitionSpec = {
            slideInHorizontally(
                initialOffsetX = { fullWidth -> -fullWidth },
                animationSpec = tween(durationMillis = 300),
            ) togetherWith slideOutHorizontally(
                targetOffsetX = { fullWidth -> fullWidth },
                animationSpec = tween(durationMillis = 300),
            )
        },
        entryProvider = entryProvider {
            entry<AppRoute.Home>(
                metadata = AppStartEndScene.startPane(),
            ) {
                ModuleHomeScreen(
                    platformName = platformName,
                    selectedModule = navigationState.currentModuleOrNull(),
                    onOpenModule = { module ->
                        navigationState.replacePath(
                            AppRoute.Home,
                            AppRoute.Feature(module),
                        )
                    },
                    onOpenLoginTab = {
                        navigationState.replacePath(
                            AppRoute.LoginHome,
                            AppRoute.LoginStatus,
                        )
                    },
                )
            }

            entry<AppRoute.LoginHome>(
                metadata = AppStartEndScene.startPane(),
            ) {
                LoginHomeScreen(
                    platformName = platformName,
                    onOpenModuleTab = {
                        navigationState.replacePath(AppRoute.Home)
                    },
                )
            }

            entry<AppRoute.LoginStatus> {
                LoginStatusScreen(
                    platformName = platformName,
                )
            }

            entry<AppRoute.Feature> { route ->
                FeatureDetailScreen(
                    module = route.module,
                    platformName = platformName,
                    onOpenSubPage = {
                        navigationState.navigateTo(
                            AppRoute.FeatureSubPage(route.module),
                        )
                    },
                    onBack = {
                        navigationState.popIfPossible()
                    },
                )
            }

            entry<AppRoute.FeatureSubPage> { route ->
                FeatureSubPageScreen(
                    module = route.module,
                    platformName = platformName,
                    onOpenThirdPage = {
                        navigationState.navigateTo(
                            AppRoute.FeatureThirdPage(route.module),
                        )
                    },
                    onBack = {
                        navigationState.popIfPossible()
                    },
                )
            }

            entry<AppRoute.FeatureThirdPage> { route ->
                FeatureThirdPageScreen(
                    module = route.module,
                    platformName = platformName,
                    onOpenFullScreenPage = {
                        navigationState.navigateTo(
                            AppRoute.FeatureFullScreen(route.module),
                        )
                    },
                    onBack = {
                        navigationState.popIfPossible()
                    },
                )
            }

            entry<AppRoute.FeatureFullScreen>(
                metadata = AppStartEndScene.fullScreenPane(),
            ) { route ->
                FeatureFullScreenScreen(
                    module = route.module,
                    platformName = platformName,
                    onBack = {
                        navigationState.popIfPossible()
                    },
                )
            }
        },
    )

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

NavDisplay(
    backStack = navigationState.backStack,
    onBack = { navigationState.popIfPossible() },
    sceneStrategy = rememberAppStartEndSceneStrategy<NavKey>(
        navigationOperation = navigationState.lastOperation,
    ),
    entryProvider = entryProvider {
        entry<AppRoute.Home>(
            metadata = AppStartEndScene.startPane(),
        ) {
            ModuleHomeScreen(
                platformName = platformName,
                selectedModule = navigationState.currentModuleOrNull(),
                onOpenModule = { module ->
                    navigationState.replacePath(AppRoute.Home, AppRoute.Feature(module))
                },
                onOpenLoginTab = {
                    navigationState.replacePath(AppRoute.LoginHome, AppRoute.LoginStatus)
                },
            )
        }
    },
)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

entry<AppRoute.Home>(
    metadata = AppStartEndScene.startPane(),
) {
    ModuleHomeScreen(
        platformName = platformName,
        selectedModule = navigationState.currentModuleOrNull(),
        onOpenModule = { module ->
            navigationState.replacePath(AppRoute.Home, AppRoute.Feature(module))
        },
        onOpenLoginTab = {
            navigationState.replacePath(AppRoute.LoginHome, AppRoute.LoginStatus)
        },
    )
}

entry<AppRoute.LoginHome>(
    metadata = AppStartEndScene.startPane(),
) {
    LoginHomeScreen(
        platformName = platformName,
        onOpenModuleTab = {
            navigationState.replacePath(AppRoute.Home)
        },
    )
}

1
2
3

private fun <T : Any> NavEntry<T>.isEndPane(): Boolean {
    return metadata.containsKey(APP_END_PANE_KEY) || (!isStartPane() && !isFullScreenPane())
}

1

不是 start pane，也不是 full screen，那就是 end pane。

1

metadata = AppStartEndScene.endPane()

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

entry<AppRoute.FeatureFullScreen>(
    metadata = AppStartEndScene.fullScreenPane(),
) { route ->
    FeatureFullScreenScreen(
        module = route.module,
        platformName = platformName,
        onBack = {
            navigationState.popIfPossible()
        },
    )
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

@Composable
fun <T : Any> rememberAppStartEndSceneStrategy(
    navigationOperation: NavigationOperation,
): SceneStrategy<T> {
    val windowSizeClass = currentWindowAdaptiveInfo().windowSizeClass
    val containerDpSize = LocalWindowInfo.current.containerDpSize
    val isLandscapeLike = containerDpSize.width > containerDpSize.height

    return remember(windowSizeClass, isLandscapeLike, navigationOperation) {
        AppStartEndSceneStrategy(
            windowSizeClass = windowSizeClass,
            isLandscapeLike = isLandscapeLike,
            navigationOperation = navigationOperation,
        )
    }
}

1
2
3

override fun SceneStrategyScope<T>.calculateScene(
    entries: List<NavEntry<T>>,
): Scene<T>?

1
2
3
4
5

1. 窗口宽度不够 -> return null
2. 不是横向空间充足 -> return null
3. 栈顶是 full screen -> return null
4. 找不到 start pane -> return null
5. 条件满足 -> 返回 AppStartEndScene

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

flowchart TD
    A[calculateScene(entries)] --> B{宽度达到 Medium 吗}
    B -- 否 --> N[return null]
    B -- 是 --> C{横向空间更多吗}
    C -- 否 --> N
    C -- 是 --> D{topEntry 是 fullScreenPane 吗}
    D -- 是 --> N
    D -- 否 --> E{能找到 startEntry 吗}
    E -- 否 --> N
    E -- 是 --> F[return AppStartEndScene]

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

if (
    !windowSizeClass.isWidthAtLeastBreakpoint(WIDTH_DP_MEDIUM_LOWER_BOUND) ||
    !isLandscapeLike
) {
    return null
}

if (topEntry?.isFullScreenPane() == true) {
    return null
}

val endEntry = topEntry
    ?.takeIf { entry -> entry.isEndPane() }
val endRootEntry = entries.firstOrNull { entry ->
    entry.isEndPane()
}
val startEntry = entries.findLast { entry ->
    entry.isStartPane()
} ?: return null

return AppStartEndScene(
    key = APP_START_END_SCENE_KEY,
    previousEntries = entries.dropLast(1),
    startEntry = startEntry,
    endRootContentKey = endRootEntry?.contentKey ?: APP_END_PLACEHOLDER_KEY,
    endEntry = endEntry,
    navigationOperation = navigationOperation,
)

1

val startEntry = entries.findLast { entry -> entry.isStartPane() }

1

val endRootEntry = entries.firstOrNull { entry -> entry.isEndPane() }

1

Home -> Feature -> FeatureSubPage -> FeatureThirdPage

1

key = APP_START_END_SCENE_KEY

1

只要还是 start/end 双栏模式，这就是同一个 Scene。

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213

package com.example.app.navigation

import androidx.compose.runtime.Composable
import androidx.compose.runtime.Stable
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import androidx.navigation3.runtime.NavBackStack
import androidx.navigation3.runtime.NavKey
import androidx.navigation3.runtime.rememberNavBackStack
import androidx.savedstate.serialization.SavedStateConfiguration
import com.example.app.feature.AppModule
import kotlinx.serialization.modules.SerializersModule
import kotlinx.serialization.modules.polymorphic
import kotlinx.serialization.modules.subclass

/**
 * 最近一次导航操作的语义。
 *
 * 这个枚举的职责只有一个：
 * 告诉导航层“这次返回栈变化属于哪种操作”。
 *
 * 为什么要单独维护这层语义？
 *
 * 因为当前项目除了顶层 `NavDisplay` 动画，
 * 还需要在 Pad 的右侧 end pane 内部做局部切换动画。
 *
 * 对于这类“Scene 内部动画”来说，仅仅知道“页面内容变了”还不够，
 * 还需要知道：
 * - 这是继续前进
 * - 还是返回上一层
 * - 还是直接替换整条路径
 *
 * 这样才能决定右侧是：
 * - 正向滑入
 * - 反向滑回
 * - 还是直接切换
 */
enum class NavigationOperation {
    /**
     * 向当前路径继续深入一层。
     */
    Push,

    /**
     * 从当前路径返回上一层。
     */
    Pop,

    /**
     * 直接替换整条导航路径。
     *
     * 例如：
     * - 切换底部 Tab
     * - 在左侧重新选择另一个模块
     */
    Replace,

    /**
     * 恢复已有状态，而不是一次用户主动导航。
     *
     * 例如：
     * - 首次进入页面
     * - 设备旋转后的重新组合
     * - 状态恢复
     */
    Restore,
}

/**
 * 应用级导航状态。
 *
 * 为什么这里不再只暴露 `NavBackStack` 扩展函数？
 *
 * 因为当前项目已经不只是“把 route 放进栈里”这么简单，
 * 还需要统一维护：
 * - 返回栈本身
 * - 最近一次导航操作语义
 * - 当前选中的业务模块
 *
 * 如果继续让页面直接操作 `backStack.add/removeLast()`，
 * 那么右侧动画所依赖的“Push / Pop / Replace”语义就会丢失。
 *
 * 所以正式项目里更合理的方式是：
 * 由一个统一的 `AppNavigationState` 负责导航入口，
 * 页面只调用它提供的方法，不直接修改返回栈。
 */
@Stable
class AppNavigationState internal constructor(
    val backStack: NavBackStack<NavKey>,
) {
    /**
     * 最近一次导航操作。
     *
     * 这个状态由导航基础设施统一维护，
     * 不是让具体页面自己上报。
     */
    var lastOperation by mutableStateOf(NavigationOperation.Restore)
        private set

    /**
     * 压入一个新的 route。
     *
     * 这属于标准的前进语义，因此记录为 `Push`。
     */
    fun navigateTo(route: NavKey) {
        lastOperation = NavigationOperation.Push
        backStack.add(route)
    }

    /**
     * 用一整条新路径替换当前返回栈。
     *
     * 这类操作不属于“继续深入”或“返回上一层”，
     * 而是直接重建当前显示路径，因此记录为 `Replace`。
     */
    fun replacePath(
        vararg routes: NavKey,
    ) {
        lastOperation = NavigationOperation.Replace
        clearStack()

        if (routes.isEmpty()) {
            backStack.add(AppRoute.Home)
            return
        }

        routes.forEach(backStack::add)
    }

    /**
     * 返回上一页，同时保留根页面。
     *
     * 返回成功时，记录为 `Pop`；
     * 如果已经没有可返回页面，则不修改导航语义。
     */
    fun popIfPossible(): Boolean {
        if (backStack.size <= 1) {
            return false
        }

        lastOperation = NavigationOperation.Pop
        backStack.removeLast()
        return true
    }

    /**
     * 读取当前正在查看的模块。
     *
     * 这个值主要给宽屏 start pane 做“当前选中项”高亮。
     */
    fun currentModuleOrNull(): AppModule? {
        for (index in backStack.size - 1 downTo 0) {
            when (val route = backStack.get(index)) {
                is AppRoute.Feature -> return route.module
                is AppRoute.FeatureSubPage -> return route.module
                is AppRoute.FeatureThirdPage -> return route.module
                is AppRoute.FeatureFullScreen -> return route.module
                else -> Unit
            }
        }

        return null
    }

    /**
     * 清空整个返回栈。
     *
     * 这里保持私有，避免业务代码绕开统一导航入口。
     */
    private fun clearStack() {
        while (backStack.isNotEmpty()) {
            backStack.removeLast()
        }
    }
}

/**
 * 创建并记住应用级导航状态。
 *
 * KMP 下需要显式提供 `SavedStateConfiguration`，
 * 这样 iOS 也能正确保存和恢复强类型 route。
 */
@Composable
fun rememberAppNavigationState(): AppNavigationState {
    val savedStateConfiguration = remember {
        SavedStateConfiguration {
            serializersModule = SerializersModule {
                polymorphic(baseClass = NavKey::class) {
                    subclass(AppRoute.Home.serializer())
                    subclass(AppRoute.LoginHome.serializer())
                    subclass(AppRoute.LoginStatus.serializer())
                    subclass(AppRoute.Feature.serializer())
                    subclass(AppRoute.FeatureSubPage.serializer())
                    subclass(AppRoute.FeatureThirdPage.serializer())
                    subclass(AppRoute.FeatureFullScreen.serializer())
                }
            }
        }
    }

    val backStack = rememberNavBackStack(
        savedStateConfiguration,
        AppRoute.Home,
    )

    return remember(backStack) {
        AppNavigationState(
            backStack = backStack,
        )
    }
}

1
2

var lastOperation by mutableStateOf(NavigationOperation.Restore)
    private set

1
2
3
4

navigationState.replacePath(
    AppRoute.Home,
    AppRoute.Feature(module),
)

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101

package com.example.app.navigation

import androidx.navigation3.runtime.NavKey
import com.example.app.feature.AppModule
import kotlinx.serialization.Serializable

/**
 * 应用的强类型路由定义。
 *
 * Navigation 3 直接把路由对象放进返回栈，因此这里的每个路由都实现 `NavKey`。
 */
@Serializable
sealed interface AppRoute : NavKey {
    @Serializable
    data object Home : AppRoute

    /**
     * start pane 的登录页。
     *
     * 这个页面本身仍然属于左侧 start pane，
     * 但当它成为当前 start 页面时，
     * 右侧 end pane 会切换到正式的 `LoginStatus` screen。
     */
    @Serializable
    data object LoginHome : AppRoute

    /**
     * 登录模块的右侧状态页。
     *
     * 这个页面是一个真正的 end screen，
     * 不是简单的占位文案。
     *
     * 这样后续即使这里要接：
     * - ViewModel
     * - 登录态查询
     * - 网络请求
     * - 权限校验
     * - 用户资料加载
     *
     * 也都可以继续沿着正式页面的结构扩展，
     * 不需要再从 placeholder 里拆代码出来。
     */
    @Serializable
    data object LoginStatus : AppRoute

    @Serializable
    data class Feature(
        val module: AppModule,
    ) : AppRoute

    /**
     * 功能详情下的二级页。
     *
     * 这个路由的职责很单纯：
     * - 手机模式下，它就是详情页继续向下 push 的下一页
     * - Pad 模式下，它仍然属于右侧 end pane 里的下一层
     *
     * 这里先不继续拆更多类型，
     * 因为当前目标只是先把“详情 -> 二级页”的布局和返回关系跑通。
     */
    @Serializable
    data class FeatureSubPage(
        val module: AppModule,
    ) : AppRoute

    /**
     * 功能详情下的三级页。
     *
     * 这一层继续沿用同样的设计原则：
     * - 手机下，它是更深一层的全屏页面
     * - Pad 下，它仍然属于右侧 end flow
     *
     * 这里故意不再把三级页拆成更复杂的数据结构，
     * 因为当前目标只是让你观察 Navigation 3 在更深层级下的切换效果。
     */
    @Serializable
    data class FeatureThirdPage(
        val module: AppModule,
    ) : AppRoute

    /**
     * 功能链路中的全屏页。
     *
     * 它和前面的 `Feature / FeatureSubPage / FeatureThirdPage` 有一个本质区别：
     *
     * - 前三者属于右侧 end flow
     * - 这个页面不再属于右侧 end flow，而是一个真正的全屏页面
     *
     * 这样设计后：
     * - 手机下，它仍然只是正常的全屏下一页
     * - Pad 下，它会临时退出主从布局，直接覆盖整个内容区域
     *
     * 这正好可以给你演示：
     * “同一个功能链里，前几层属于右侧 end pane，继续深入后再切到全屏页”
     * 这样的混合导航模型是怎么落到一份共享返回栈上的。
     */
    @Serializable
    data class FeatureFullScreen(
        val module: AppModule,
    ) : AppRoute
}

1

Home -> Feature(Storage) -> FeatureSubPage(Storage) -> FeatureThirdPage(Storage)

1
2

左侧：Home
右侧：FeatureThirdPage(Storage)

1
2
3

navigationState.navigateTo(AppRoute.FeatureSubPage(route.module))
navigationState.popIfPossible()
navigationState.replacePath(AppRoute.Home, AppRoute.Feature(module))

1
2
3
4
5
6
7

if (windowSizeClass.isWidthAtLeastBreakpoint(WIDTH_DP_MEDIUM_LOWER_BOUND)) {
    // 大屏横向窗口：交给 SceneStrategy 渲染 start/end 双栏
    renderStartEndScene()
} else {
    // 小屏或不适合双栏的窗口：仍按普通单页导航渲染
    renderSingleEntryScene()
}

1

start / end 双栏页 -> end pane 深入页 -> end pane 三级页 -> 全屏页

1
2

Column(modifier = Modifier.weight(0.35f))
Column(modifier = Modifier.weight(0.65f))

1
2
3

startPane()
endPane()
fullScreenPane()

1
2
3
4
5
6
7
8
9

flowchart LR
    A[一份 NavBackStack] --> B{SceneStrategy 判断窗口能力}
    B -->|手机 / 竖屏 / 窄窗口| C[默认全屏 Scene]
    B -->|宽窗口 + 横屏| D[AppStartEndScene]
    D --> E[start pane]
    D --> F[end pane]
    F --> G{顶部 route 是否 fullScreenPane}
    G -->|是| C
    G -->|否| F