从零开始的自研音乐播放器进程 3.2 UI 优化

UI 美化实施手册（完整代码）

本文档是 Plans/ui-polish-apple-music.md 的配套实施参考。
每个章节给出完整、可直接粘贴的 Kotlin 代码，保持项目已有风格：

• @HiltViewModel + @Inject constructor，ViewModel 写在同一文件的 Composable 之上
• 状态模式：private val _state = MutableStateFlow(...) + val state = _state.asStateFlow()
• 中文注释，私有工具函数放文件底部
• collectAsStateWithLifecycle() 收集 StateFlow，hiltViewModel() 注入 VM
• URI 字符串转换统一用 androidx.core.net.toUri

---

总览：改动清单

顺序	文件	操作
1	gradle/libs.versions.toml	已有 palette，确认版本
1	app/build.gradle.kts	已有 implementation(libs.androidx.palette)
2	ui/theme/MotionDefaults.kt	🆕 新建
3	ui/theme/PaletteExtractor.kt	🆕 新建
4	ui/component/MusicListItem.kt	🆕 新建
5	ui/screen/LibraryScannerViewModel.kt	🆕 新建
6	ui/component/AlbumArt.kt	✏️ 加 shape 参数（可选）
7	ui/component/MiniPlayer.kt	✏️ 布局微调
8	ui/screen/SongListScreen.kt	✏️ LargeTopAppBar + MusicListItem
9	ui/screen/AlbumListScreen.kt	✏️ LargeTopAppBar + 网格圆角
10	ui/screen/ArtistListScreen.kt	✏️ LargeTopAppBar + MusicListItem
11	ui/screen/FolderBrowserScreen.kt	✏️ LargeTopAppBar
12	ui/screen/AlbumDetailScreen.kt	✏️ 大封面头 + 渐变背景
13	ui/screen/ArtistDetailScreen.kt	✏️ 大头像头部 + 渐变
14	ui/screen/NowPlayingScreen.kt	✏️ 沉浸式渐变 + spring
15	ui/navigation/AppNavigation.kt	✏️ 底部 TabBar + slide 转场
16	ui/screen/LibraryScreen.kt	🗑️ 删除

---

1. 依赖（已有，确认即可）

gradle/libs.versions.toml：

[versions]
palette = "1.0.0"

[libraries]
androidx-palette = { group = "androidx.palette", name = "palette-ktx", version.ref = "palette" }

app/build.gradle.kts：

// palette
implementation(libs.androidx.palette)

---

2. ui/theme/MotionDefaults.kt 🆕

全局 spring 参数，避免散落各处自定义 animationSpec。

package io.kyonqi.musicplayer.ui.theme

import androidx.compose.animation.core.Spring
import androidx.compose.animation.core.spring

/**
 * 全局动效参数，仿 Apple Music 的弹性曲线
 * 三档预设：standard 平滑过渡、bouncy 有轻微回弹、subtle 快速响应
 */
object MotionDefaults {

    /** 默认过渡：无回弹，中等刚度。适合颜色、透明度、尺寸等连续值 */
    fun <T> standard() = spring<T>(
        dampingRatio = Spring.DampingRatioNoBouncy,
        stiffness = Spring.StiffnessMediumLow,
    )

    /** 弹性过渡：封面缩放、图标状态切换 */
    fun <T> bouncy() = spring<T>(
        dampingRatio = 0.6f,
        stiffness = Spring.StiffnessLow,
    )

    /** 轻量过渡：小幅布局变化、FilterChip 选中等 */
    fun <T> subtle() = spring<T>(
        dampingRatio = Spring.DampingRatioNoBouncy,
        stiffness = Spring.StiffnessHigh,
    )
}

---

3. ui/theme/PaletteExtractor.kt 🆕

从封面 Bitmap 提取主色。利用 Coil 共享 ImageLoader，避免重复解码；allowHardware(false) 是为了 Palette 能读到像素。

package io.kyonqi.musicplayer.ui.theme

import android.net.Uri
import androidx.compose.runtime.Composable
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.State
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.platform.LocalContext
import androidx.palette.graphics.Palette
import coil3.BitmapImage
import coil3.imageLoader
import coil3.request.ImageRequest
import coil3.request.SuccessResult
import coil3.request.allowHardware
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.withContext

/**
 * 从音频 URI 异步提取主色（dominant + muted），用于 NowPlayingScreen 的渐变背景
 *
 * 实现要点：
 *  - 走同一个 ImageLoader，封面位图由 AudioCoverFetcher 提供并经 Coil 缓存
 *  - allowHardware(false) 让 Coil 返回软件 Bitmap，否则 Palette 无法读取像素
 *  - Palette.generate 放到 Dispatchers.Default 避免阻塞 UI
 *  - 无封面或解码失败时返回 null，由调用方降级到主题色
 */
@Composable
fun rememberDominantColor(uri: Uri?): State<Pair<Color, Color>?> {
    val context = LocalContext.current
    val state = remember(uri) { mutableStateOf<Pair<Color, Color>?>(null) }

    LaunchedEffect(uri) {
        if (uri == null) {
            state.value = null
            return@LaunchedEffect
        }
        val result = context.imageLoader.execute(
            ImageRequest.Builder(context)
                .data(uri)
                .allowHardware(false)
                .build()
        )
        val bitmap = ((result as? SuccessResult)?.image as? BitmapImage)?.bitmap
            ?: return@LaunchedEffect

        val palette = withContext(Dispatchers.Default) {
            Palette.from(bitmap).maximumColorCount(16).generate()
        }
        val fallback = 0xFF1A1A1A.toInt()
        val dominant = palette.getDominantColor(fallback)
        val muted = palette.getMutedColor(dominant)
        state.value = Color(dominant) to Color(muted)
    }
    return state
}

---

4. ui/component/MusicListItem.kt 🆕

统一圆角卡片样式，替代 Material ListItem 的分隔线风格。

package io.kyonqi.musicplayer.ui.component

import androidx.compose.foundation.clickable
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.width
import androidx.compose.foundation.shape.RoundedCornerShape
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Surface
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.draw.clip
import androidx.compose.ui.text.style.TextOverflow
import androidx.compose.ui.unit.dp

/**
 * 通用的圆角卡片列表项
 * 用于 SongListScreen / ArtistDetailScreen 的歌曲列表等
 */
@Composable
fun MusicListItem(
    title: String,
    subtitle: String,
    leadingContent: @Composable () -> Unit,
    onClick: () -> Unit,
    modifier: Modifier = Modifier,
    trailingContent: (@Composable () -> Unit)? = null,
) {
    Surface(
        modifier = modifier
            .fillMaxWidth()
            .padding(horizontal = 16.dp, vertical = 4.dp)
            .clip(RoundedCornerShape(16.dp))
            .clickable(onClick = onClick),
        color = MaterialTheme.colorScheme.surfaceContainer,
        shape = RoundedCornerShape(16.dp),
    ) {
        Row(
            modifier = Modifier.padding(12.dp),
            verticalAlignment = Alignment.CenterVertically,
        ) {
            leadingContent()
            Spacer(Modifier.width(12.dp))
            Column(modifier = Modifier.weight(1f)) {
                Text(
                    text = title,
                    style = MaterialTheme.typography.titleMedium,
                    maxLines = 1,
                    overflow = TextOverflow.Ellipsis,
                )
                Text(
                    text = subtitle,
                    style = MaterialTheme.typography.bodySmall,
                    color = MaterialTheme.colorScheme.onSurfaceVariant,
                    maxLines = 1,
                    overflow = TextOverflow.Ellipsis,
                )
            }
            trailingContent?.invoke()
        }
    }
}

---

5. ui/screen/LibraryScannerViewModel.kt 🆕

把原 LibraryViewModel 的扫描逻辑抽出来，独立于任何 Tab 页。AppNavigation 顶层通过 hiltViewModel() 实例化一次，供所有 tab 共享。

package io.kyonqi.musicplayer.ui.screen

import androidx.lifecycle.ViewModel
import androidx.lifecycle.viewModelScope
import dagger.hilt.android.lifecycle.HiltViewModel
import io.kyonqi.musicplayer.data.dao.TrackDao
import io.kyonqi.musicplayer.scanner.LibraryScanner
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.launch
import javax.inject.Inject

/**
 * 音乐库扫描 ViewModel
 * 从原 LibraryViewModel 拆出，只负责扫描触发 + 进度暴露
 * Tab 切换状态改由 Navigation 承担
 */
@HiltViewModel
class LibraryScannerViewModel @Inject constructor(
    private val libraryScanner: LibraryScanner,
    private val trackDao: TrackDao,
) : ViewModel() {

    // 扫描进度
    val scanProgress = libraryScanner.scanProgress

    // 数据库中的音轨数量
    private val _trackCount = MutableStateFlow(0)
    val trackCount = _trackCount.asStateFlow()

    // 防止重复触发初始化
    private var initialized = false

    /** 首次加载时检查数据库，如果空则全量扫描 */
    fun initLibrary() {
        if (initialized) return
        initialized = true
        viewModelScope.launch {
            val count = trackDao.getTrackCount()
            _trackCount.value = count
            if (count == 0) {
                libraryScanner.fullScan()
                _trackCount.value = trackDao.getTrackCount()
            }
        }
    }

    /** 手动刷新：走增量扫描 */
    fun refreshLibrary() {
        viewModelScope.launch {
            libraryScanner.incrementalScan()
            _trackCount.value = trackDao.getTrackCount()
        }
    }
}

---

6. ui/component/AlbumArt.kt ✏️（可选扩展）

给封面加可选的 shape 参数，方便各处复用。保持原签名兼容（size + modifier 不变），只新增 shape 默认为 RoundedCornerShape(8.dp)。

package io.kyonqi.musicplayer.ui.component

import android.net.Uri
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.size
import androidx.compose.foundation.shape.RoundedCornerShape
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.MusicNote
import androidx.compose.material3.Icon
import androidx.compose.material3.MaterialTheme
import androidx.compose.runtime.Composable
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.draw.clip
import androidx.compose.ui.graphics.Shape
import androidx.compose.ui.layout.ContentScale
import androidx.compose.ui.platform.LocalContext
import androidx.compose.ui.unit.Dp
import androidx.compose.ui.unit.dp
import coil3.compose.SubcomposeAsyncImage
import coil3.request.ImageRequest
import coil3.request.crossfade

/**
 * 专辑封面组件
 * 使用 Coil AsyncImage，加载失败回退到 MusicNote 图标
 *
 * @param shape 可选圆角形状，默认 8.dp
 */
@Composable
fun AlbumArt(
    uri: Uri?,
    modifier: Modifier = Modifier,
    size: Dp = 48.dp,
    shape: Shape = RoundedCornerShape(8.dp),
    contentDescription: String? = "专辑封面",
) {
    if (uri == null) {
        AlbumArtPlaceHolder(modifier = modifier.size(size).clip(shape))
        return
    }

    val context = LocalContext.current
    val model = ImageRequest.Builder(context).data(uri).crossfade(true).build()
    SubcomposeAsyncImage(
        model = model,
        contentDescription = contentDescription,
        modifier = modifier.size(size).clip(shape),
        contentScale = ContentScale.Crop,
        error = {
            AlbumArtPlaceHolder(modifier = Modifier.fillMaxSize())
        },
    )
}

/**
 * 默认封面占位
 */
@Composable
private fun AlbumArtPlaceHolder(
    modifier: Modifier = Modifier,
) {
    Box(
        modifier = modifier,
        contentAlignment = Alignment.Center,
    ) {
        Icon(
            Icons.Default.MusicNote,
            contentDescription = null,
            modifier = Modifier.fillMaxSize(0.5f),
            tint = MaterialTheme.colorScheme.onSurfaceVariant,
        )
    }
}

---

7. ui/component/MiniPlayer.kt ✏️

布局微调：加圆角 + 更大内边距，封面加圆角。功能不变。

package io.kyonqi.musicplayer.ui.component

import androidx.compose.foundation.clickable
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.width
import androidx.compose.foundation.shape.RoundedCornerShape
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Pause
import androidx.compose.material.icons.filled.PlayArrow
import androidx.compose.material.icons.filled.SkipNext
import androidx.compose.material3.Icon
import androidx.compose.material3.IconButton
import androidx.compose.material3.LinearProgressIndicator
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Surface
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.draw.clip
import androidx.compose.ui.text.style.TextOverflow
import androidx.compose.ui.unit.dp
import androidx.core.net.toUri
import androidx.hilt.navigation.compose.hiltViewModel
import androidx.lifecycle.ViewModel
import androidx.lifecycle.compose.collectAsStateWithLifecycle
import dagger.hilt.android.lifecycle.HiltViewModel
import io.kyonqi.musicplayer.player.PlayerController
import javax.inject.Inject

@HiltViewModel
class MiniPlayerViewModel @Inject constructor(
    private val player: PlayerController,
) : ViewModel() {
    val playbackState = player.playbackState

    fun togglePlayPause() = player.togglePlayPause()

    fun next() = player.next()
}

/**
 * 底部迷你播放条
 * 没有当前播放时不显示
 */
@Composable
fun MiniPlayer(
    onClick: () -> Unit,
    viewModel: MiniPlayerViewModel = hiltViewModel(),
) {
    val state by viewModel.playbackState.collectAsStateWithLifecycle()
    val track = state.currentTrack ?: return

    Surface(
        tonalElevation = 3.dp,
        shape = RoundedCornerShape(16.dp),
        modifier = Modifier
            .fillMaxWidth()
            .padding(horizontal = 8.dp, vertical = 4.dp),
    ) {
        Column {
            if (state.durationMs > 0) {
                LinearProgressIndicator(
                    progress = { state.positionMs.toFloat() / state.durationMs.toFloat() },
                    modifier = Modifier.fillMaxWidth().height(2.dp),
                )
            }
            Row(
                modifier = Modifier
                    .fillMaxWidth()
                    .clickable(onClick = onClick)
                    .padding(horizontal = 12.dp, vertical = 8.dp),
                verticalAlignment = Alignment.CenterVertically,
            ) {
                AlbumArt(
                    uri = track.uri,
                    size = 44.dp,
                    modifier = Modifier.clip(RoundedCornerShape(8.dp)),
                )
                Spacer(Modifier.width(12.dp))
                Column(modifier = Modifier.weight(1f)) {
                    Text(
                        text = track.title,
                        maxLines = 1,
                        overflow = TextOverflow.Ellipsis,
                        style = MaterialTheme.typography.bodyMedium,
                    )
                    Text(
                        text = track.artist,
                        maxLines = 1,
                        overflow = TextOverflow.Ellipsis,
                        style = MaterialTheme.typography.bodySmall,
                        color = MaterialTheme.colorScheme.onSurfaceVariant,
                    )
                }
                IconButton(onClick = { viewModel.togglePlayPause() }) {
                    Icon(
                        if (state.isPlaying) Icons.Default.Pause else Icons.Default.PlayArrow,
                        contentDescription = if (state.isPlaying) "暂停" else "播放",
                    )
                }
                IconButton(onClick = { viewModel.next() }) {
                    Icon(Icons.Default.SkipNext, contentDescription = "下一首")
                }
            }
        }
    }
}

---

8. ui/screen/SongListScreen.kt ✏️

改动：LargeTopAppBar + MusicListItem 圆角卡片 + contentPadding 处理顶栏折叠。

package io.kyonqi.musicplayer.ui.screen

import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.PaddingValues
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.lazy.LazyColumn
import androidx.compose.foundation.lazy.itemsIndexed
import androidx.compose.foundation.shape.RoundedCornerShape
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.FilterChip
import androidx.compose.material3.LargeTopAppBar
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Scaffold
import androidx.compose.material3.Text
import androidx.compose.material3.TopAppBarDefaults
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.ui.Modifier
import androidx.compose.ui.draw.clip
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.input.nestedscroll.nestedScroll
import androidx.compose.ui.unit.dp
import androidx.core.net.toUri
import androidx.hilt.navigation.compose.hiltViewModel
import androidx.lifecycle.ViewModel
import androidx.lifecycle.compose.collectAsStateWithLifecycle
import androidx.lifecycle.viewModelScope
import dagger.hilt.android.lifecycle.HiltViewModel
import io.kyonqi.musicplayer.data.dao.TrackDao
import io.kyonqi.musicplayer.data.entity.TrackEntity
import io.kyonqi.musicplayer.data.mapper.toAudioFiles
import io.kyonqi.musicplayer.player.PlayerController
import io.kyonqi.musicplayer.ui.component.AlbumArt
import io.kyonqi.musicplayer.ui.component.MusicListItem
import kotlinx.coroutines.ExperimentalCoroutinesApi
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.SharingStarted
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.flow.WhileSubscribed
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.flow.flatMapLatest
import kotlinx.coroutines.flow.stateIn
import javax.inject.Inject

enum class SongSortOrder {
    TITLE,       // 按标题排序
    DATE_ADDED,  // 按添加时间
    DURATION,    // 按时长
}

@HiltViewModel
class SongListViewModel @Inject constructor(
    private val trackDao: TrackDao,
    private val player: PlayerController,
) : ViewModel() {
    private val _sortOrder = MutableStateFlow(SongSortOrder.TITLE)
    val sortOrder = _sortOrder.asStateFlow()

    // 根据排列方式切换数据源
    @OptIn(ExperimentalCoroutinesApi::class)
    val tracks: StateFlow<List<TrackEntity>> = _sortOrder.flatMapLatest { order ->
        when (order) {
            SongSortOrder.TITLE -> trackDao.getAllTracks()
            SongSortOrder.DATE_ADDED -> trackDao.getAllTracksByDateAdded()
            SongSortOrder.DURATION -> trackDao.getAllTracksByDuration()
        }
    }.stateIn(viewModelScope, SharingStarted.WhileSubscribed(5000), emptyList())

    fun setSortOrder(order: SongSortOrder) {
        _sortOrder.value = order
    }

    fun onTrackClick(index: Int) {
        val trackList = tracks.value
        if (index in trackList.indices) {
            player.setQueue(trackList.toAudioFiles(), index)
        }
    }
}

/**
 * 全部歌曲列表
 */
@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun SongListScreen(
    onNavigateToNowPlaying: () -> Unit = {},
    viewModel: SongListViewModel = hiltViewModel(),
) {
    val tracks by viewModel.tracks.collectAsStateWithLifecycle()
    val sortOrder by viewModel.sortOrder.collectAsStateWithLifecycle()

    val scrollBehavior = TopAppBarDefaults.exitUntilCollapsedScrollBehavior()

    Scaffold(
        modifier = Modifier.nestedScroll(scrollBehavior.nestedScrollConnection),
        topBar = {
            LargeTopAppBar(
                title = { Text("歌曲") },
                scrollBehavior = scrollBehavior,
                colors = TopAppBarDefaults.largeTopAppBarColors(
                    containerColor = Color.Transparent,
                    scrolledContainerColor = MaterialTheme.colorScheme.surface,
                ),
            )
        },
    ) { padding ->
        LazyColumn(
            contentPadding = padding,
            modifier = Modifier.fillMaxSize(),
        ) {
            // 排序选项栏
            item {
                SortBar(
                    currentOrder = sortOrder,
                    onOrderChange = { viewModel.setSortOrder(it) },
                )
            }
            itemsIndexed(tracks, key = { _, t -> t.id }) { index, track ->
                SongListItem(
                    track = track,
                    onClick = {
                        viewModel.onTrackClick(index)
                        onNavigateToNowPlaying()
                    },
                )
            }
        }
    }
}

/**
 * 排序选项栏
 */
@Composable
private fun SortBar(
    currentOrder: SongSortOrder,
    onOrderChange: (SongSortOrder) -> Unit,
) {
    Row(
        modifier = Modifier.fillMaxWidth().padding(horizontal = 16.dp, vertical = 8.dp),
        horizontalArrangement = Arrangement.spacedBy(8.dp),
    ) {
        SongSortOrder.entries.forEach { order ->
            FilterChip(
                selected = order == currentOrder,
                onClick = { onOrderChange(order) },
                label = {
                    Text(
                        when (order) {
                            SongSortOrder.TITLE -> "名称"
                            SongSortOrder.DATE_ADDED -> "添加时间"
                            SongSortOrder.DURATION -> "时长"
                        },
                    )
                },
            )
        }
    }
}

/**
 * 歌曲列表项：圆角卡片 + 封面 + 标题 + 艺术家 · 时长
 */
@Composable
internal fun SongListItem(
    track: TrackEntity,
    onClick: () -> Unit,
) {
    MusicListItem(
        title = track.title,
        subtitle = "${track.artist} · ${formatDuration(track.durationMs)}",
        leadingContent = {
            AlbumArt(
                uri = track.uri.toUri(),
                size = 56.dp,
                modifier = Modifier.clip(RoundedCornerShape(8.dp)),
            )
        },
        onClick = onClick,
    )
}

private fun formatDuration(ms: Long): String {
    val totalSeconds = ms / 1000
    return "%d:%02d".format(totalSeconds / 60, totalSeconds % 60)
}

---

9. ui/screen/AlbumListScreen.kt ✏️

改动：LargeTopAppBar + 网格 item 视觉收紧（移除外层 Card，只保留封面圆角 + 下方文字）。

package io.kyonqi.musicplayer.ui.screen

import androidx.compose.foundation.clickable
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.PaddingValues
import androidx.compose.foundation.layout.aspectRatio
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.lazy.grid.GridCells
import androidx.compose.foundation.lazy.grid.LazyVerticalGrid
import androidx.compose.foundation.lazy.grid.items
import androidx.compose.foundation.shape.RoundedCornerShape
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.LargeTopAppBar
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Scaffold
import androidx.compose.material3.Text
import androidx.compose.material3.TopAppBarDefaults
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.draw.clip
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.input.nestedscroll.nestedScroll
import androidx.compose.ui.text.style.TextOverflow
import androidx.compose.ui.unit.dp
import androidx.core.net.toUri
import androidx.hilt.navigation.compose.hiltViewModel
import androidx.lifecycle.ViewModel
import androidx.lifecycle.compose.collectAsStateWithLifecycle
import androidx.lifecycle.viewModelScope
import dagger.hilt.android.lifecycle.HiltViewModel
import io.kyonqi.musicplayer.data.dao.AlbumDao
import io.kyonqi.musicplayer.data.entity.AlbumEntity
import io.kyonqi.musicplayer.ui.component.AlbumArt
import kotlinx.coroutines.flow.SharingStarted
import kotlinx.coroutines.flow.WhileSubscribed
import kotlinx.coroutines.flow.stateIn
import javax.inject.Inject

@HiltViewModel
class AlbumListViewModel @Inject constructor(
    private val albumDao: AlbumDao,
) : ViewModel() {
    val albums = albumDao.getAllAlbums()
        .stateIn(viewModelScope, SharingStarted.WhileSubscribed(5000), emptyList())
}

/**
 * 专辑网格列表
 */
@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun AlbumListScreen(
    onAlbumClick: (Long) -> Unit,
    viewModel: AlbumListViewModel = hiltViewModel(),
) {
    val albums by viewModel.albums.collectAsStateWithLifecycle()
    val scrollBehavior = TopAppBarDefaults.exitUntilCollapsedScrollBehavior()

    Scaffold(
        modifier = Modifier.nestedScroll(scrollBehavior.nestedScrollConnection),
        topBar = {
            LargeTopAppBar(
                title = { Text("专辑") },
                scrollBehavior = scrollBehavior,
                colors = TopAppBarDefaults.largeTopAppBarColors(
                    containerColor = Color.Transparent,
                    scrolledContainerColor = MaterialTheme.colorScheme.surface,
                ),
            )
        },
    ) { padding ->
        if (albums.isEmpty()) {
            Box(
                modifier = Modifier.fillMaxSize().padding(padding),
                contentAlignment = Alignment.Center,
            ) {
                Text("暂无专辑", style = MaterialTheme.typography.bodyLarge)
            }
            return@Scaffold
        }

        LazyVerticalGrid(
            columns = GridCells.Adaptive(minSize = 150.dp),
            contentPadding = PaddingValues(
                start = 16.dp, end = 16.dp,
                top = padding.calculateTopPadding(),
                bottom = padding.calculateBottomPadding() + 16.dp,
            ),
            horizontalArrangement = Arrangement.spacedBy(12.dp),
            verticalArrangement = Arrangement.spacedBy(16.dp),
            modifier = Modifier.fillMaxSize(),
        ) {
            items(albums, key = { it.albumId }) { album ->
                AlbumGridItem(album) { onAlbumClick(album.albumId) }
            }
        }
    }
}

/**
 * 专辑网格项：封面 + 名称 + 艺术家
 */
@Composable
private fun AlbumGridItem(
    album: AlbumEntity,
    onClick: () -> Unit,
) {
    Column(
        modifier = Modifier
            .fillMaxWidth()
            .clip(RoundedCornerShape(12.dp))
            .clickable(onClick = onClick)
            .padding(4.dp),
    ) {
        AlbumArt(
            uri = album.coverUri.takeIf { it.isNotEmpty() }?.toUri(),
            modifier = Modifier.fillMaxWidth().aspectRatio(1f),
            size = 150.dp,
            shape = RoundedCornerShape(12.dp),
        )
        Text(
            text = album.name,
            style = MaterialTheme.typography.bodyMedium,
            maxLines = 1,
            overflow = TextOverflow.Ellipsis,
            modifier = Modifier.padding(top = 8.dp, start = 4.dp, end = 4.dp),
        )
        Text(
            text = album.artist,
            style = MaterialTheme.typography.bodySmall,
            color = MaterialTheme.colorScheme.onSurfaceVariant,
            maxLines = 1,
            overflow = TextOverflow.Ellipsis,
            modifier = Modifier.padding(horizontal = 4.dp),
        )
    }
}

---

10. ui/screen/ArtistListScreen.kt ✏️

改动：LargeTopAppBar + MusicListItem 圆角卡片。

package io.kyonqi.musicplayer.ui.screen

import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.size
import androidx.compose.foundation.lazy.LazyColumn
import androidx.compose.foundation.lazy.items
import androidx.compose.foundation.shape.CircleShape
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Person
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.Icon
import androidx.compose.material3.LargeTopAppBar
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Scaffold
import androidx.compose.material3.Surface
import androidx.compose.material3.Text
import androidx.compose.material3.TopAppBarDefaults
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.input.nestedscroll.nestedScroll
import androidx.compose.ui.unit.dp
import androidx.hilt.navigation.compose.hiltViewModel
import androidx.lifecycle.ViewModel
import androidx.lifecycle.compose.collectAsStateWithLifecycle
import androidx.lifecycle.viewModelScope
import dagger.hilt.android.lifecycle.HiltViewModel
import io.kyonqi.musicplayer.data.dao.ArtistDao
import io.kyonqi.musicplayer.data.entity.ArtistEntity
import io.kyonqi.musicplayer.ui.component.MusicListItem
import kotlinx.coroutines.flow.SharingStarted
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.flow.WhileSubscribed
import kotlinx.coroutines.flow.stateIn
import javax.inject.Inject

@HiltViewModel
class ArtistListViewModel @Inject constructor(
    private val artistDao: ArtistDao,
) : ViewModel() {
    val artists: StateFlow<List<ArtistEntity>> = artistDao.getAllArtists().stateIn(
        viewModelScope, SharingStarted.WhileSubscribed(5000), emptyList()
    )
}

/**
 * 艺术家列表
 */
@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun ArtistListScreen(
    onArtistClick: (Long) -> Unit,
    viewModel: ArtistListViewModel = hiltViewModel(),
) {
    val artists by viewModel.artists.collectAsStateWithLifecycle()
    val scrollBehavior = TopAppBarDefaults.exitUntilCollapsedScrollBehavior()

    Scaffold(
        modifier = Modifier.nestedScroll(scrollBehavior.nestedScrollConnection),
        topBar = {
            LargeTopAppBar(
                title = { Text("艺术家") },
                scrollBehavior = scrollBehavior,
                colors = TopAppBarDefaults.largeTopAppBarColors(
                    containerColor = Color.Transparent,
                    scrolledContainerColor = MaterialTheme.colorScheme.surface,
                ),
            )
        },
    ) { padding ->
        if (artists.isEmpty()) {
            Box(
                modifier = Modifier.fillMaxSize().padding(padding),
                contentAlignment = Alignment.Center,
            ) {
                Text("暂无艺术家", style = MaterialTheme.typography.bodyLarge)
            }
            return@Scaffold
        }

        LazyColumn(
            contentPadding = padding,
            modifier = Modifier.fillMaxSize(),
        ) {
            items(artists, key = { it.artistId }) { artist ->
                ArtistListItem(artist) { onArtistClick(artist.artistId) }
            }
        }
    }
}

/**
 * 艺术家列表项：圆形头像占位 + 名称 + 专辑数/歌曲数
 */
@Composable
private fun ArtistListItem(
    artist: ArtistEntity,
    onClick: () -> Unit,
) {
    MusicListItem(
        title = artist.name,
        subtitle = "${artist.albumCount} 张专辑 · ${artist.trackCount} 首歌曲",
        leadingContent = {
            Surface(
                modifier = Modifier.size(56.dp),
                shape = CircleShape,
                color = MaterialTheme.colorScheme.secondaryContainer,
            ) {
                Box(contentAlignment = Alignment.Center) {
                    Icon(Icons.Default.Person, null)
                }
            }
        },
        onClick = onClick,
    )
}

---

11. ui/screen/FolderBrowserScreen.kt ✏️

改动：LargeTopAppBar + 展开项用 MusicListItem。

package io.kyonqi.musicplayer.ui.screen

import androidx.compose.foundation.clickable
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.size
import androidx.compose.foundation.lazy.LazyColumn
import androidx.compose.foundation.lazy.itemsIndexed
import androidx.compose.foundation.shape.RoundedCornerShape
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.ExpandLess
import androidx.compose.material.icons.filled.ExpandMore
import androidx.compose.material.icons.filled.Folder
import androidx.compose.material.icons.filled.FolderOpen
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.Icon
import androidx.compose.material3.LargeTopAppBar
import androidx.compose.material3.ListItem
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Scaffold
import androidx.compose.material3.Text
import androidx.compose.material3.TopAppBarDefaults
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.draw.clip
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.input.nestedscroll.nestedScroll
import androidx.compose.ui.text.style.TextOverflow
import androidx.compose.ui.unit.dp
import androidx.core.net.toUri
import androidx.hilt.navigation.compose.hiltViewModel
import androidx.lifecycle.ViewModel
import androidx.lifecycle.compose.collectAsStateWithLifecycle
import androidx.lifecycle.viewModelScope
import dagger.hilt.android.lifecycle.HiltViewModel
import io.kyonqi.musicplayer.data.dao.TrackDao
import io.kyonqi.musicplayer.data.entity.TrackEntity
import io.kyonqi.musicplayer.data.mapper.toAudioFiles
import io.kyonqi.musicplayer.player.PlayerController
import io.kyonqi.musicplayer.ui.component.AlbumArt
import io.kyonqi.musicplayer.ui.component.MusicListItem
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.SharingStarted
import kotlinx.coroutines.flow.WhileSubscribed
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.flow.stateIn
import kotlinx.coroutines.launch
import javax.inject.Inject

@HiltViewModel
class FolderBrowserViewModel @Inject constructor(
    private val trackDao: TrackDao,
    private val player: PlayerController,
) : ViewModel() {

    // 所有文件夹路径
    val folders = trackDao.getAllFolders().stateIn(
        viewModelScope, SharingStarted.WhileSubscribed(5000), emptyList()
    )

    // 当前展开的文件夹和歌曲
    private val _expandedFolder = MutableStateFlow<String?>(null)
    val expandedFolder = _expandedFolder.asStateFlow()

    private val _folderTracks = MutableStateFlow<List<TrackEntity>>(emptyList())
    val folderTracks = _folderTracks.asStateFlow()

    fun toggleFolder(folderPath: String) {
        if (_expandedFolder.value == folderPath) {
            _expandedFolder.value = null
            _folderTracks.value = emptyList()
        } else {
            _expandedFolder.value = folderPath
            viewModelScope.launch {
                trackDao.getTracksByFolder(folderPath).collect {
                    _folderTracks.value = it
                }
            }
        }
    }

    fun playTrack(index: Int) {
        val trackList = _folderTracks.value
        if (index in trackList.indices) {
            player.setQueue(trackList.toAudioFiles(), index)
        }
    }
}

/**
 * 文件夹浏览页
 */
@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun FolderBrowserScreen(
    viewModel: FolderBrowserViewModel = hiltViewModel(),
) {
    val folders by viewModel.folders.collectAsStateWithLifecycle()
    val expandedFolder by viewModel.expandedFolder.collectAsStateWithLifecycle()
    val folderTracks by viewModel.folderTracks.collectAsStateWithLifecycle()
    val scrollBehavior = TopAppBarDefaults.exitUntilCollapsedScrollBehavior()

    Scaffold(
        modifier = Modifier.nestedScroll(scrollBehavior.nestedScrollConnection),
        topBar = {
            LargeTopAppBar(
                title = { Text("文件夹") },
                scrollBehavior = scrollBehavior,
                colors = TopAppBarDefaults.largeTopAppBarColors(
                    containerColor = Color.Transparent,
                    scrolledContainerColor = MaterialTheme.colorScheme.surface,
                ),
            )
        },
    ) { padding ->
        if (folders.isEmpty()) {
            Box(
                modifier = Modifier.fillMaxSize().padding(padding),
                contentAlignment = Alignment.Center,
            ) {
                Text("暂无文件", style = MaterialTheme.typography.bodyLarge)
            }
            return@Scaffold
        }

        LazyColumn(
            contentPadding = padding,
            modifier = Modifier.fillMaxSize(),
        ) {
            folders.forEach { folder ->
                // 文件夹项
                item(key = "folder_$folder") {
                    FolderItem(
                        folder = folder,
                        expanded = expandedFolder == folder,
                        onClick = { viewModel.toggleFolder(folder) },
                    )
                }
                // 展开时显示歌曲列表
                if (expandedFolder == folder) {
                    itemsIndexed(folderTracks, key = { _, t -> t.id }) { index, track ->
                        MusicListItem(
                            title = track.title,
                            subtitle = "${track.artist} · ${formatDuration(track.durationMs)}",
                            leadingContent = {
                                AlbumArt(
                                    uri = track.uri.toUri(),
                                    size = 48.dp,
                                    modifier = Modifier.clip(RoundedCornerShape(8.dp)),
                                )
                            },
                            onClick = { viewModel.playTrack(index) },
                            modifier = Modifier.padding(start = 24.dp),
                        )
                    }
                }
            }
        }
    }
}

/**
 * 文件夹项
 */
@Composable
private fun FolderItem(
    folder: String,
    expanded: Boolean,
    onClick: () -> Unit,
) {
    ListItem(
        headlineContent = {
            Text(
                folder.trimEnd('/').substringAfterLast('/'),
                maxLines = 1,
                overflow = TextOverflow.Ellipsis,
            )
        },
        supportingContent = {
            Text(folder, style = MaterialTheme.typography.bodySmall)
        },
        leadingContent = {
            Icon(
                if (expanded) Icons.Default.FolderOpen else Icons.Default.Folder,
                null,
            )
        },
        trailingContent = {
            Icon(
                if (expanded) Icons.Default.ExpandLess else Icons.Default.ExpandMore,
                null,
            )
        },
        modifier = Modifier.clickable(onClick = onClick),
    )
}

private fun formatDuration(ms: Long): String {
    val totalSeconds = ms / 1000
    return "%d:%02d".format(totalSeconds / 60, totalSeconds % 60)
}

---

12. ui/screen/AlbumDetailScreen.kt ✏️

改动：大封面头部 + 基于封面的渐变背景（用 rememberDominantColor）。

package io.kyonqi.musicplayer.ui.screen

import androidx.compose.foundation.background
import androidx.compose.foundation.clickable
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.size
import androidx.compose.foundation.layout.width
import androidx.compose.foundation.lazy.LazyColumn
import androidx.compose.foundation.lazy.itemsIndexed
import androidx.compose.foundation.shape.RoundedCornerShape
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.automirrored.filled.ArrowBack
import androidx.compose.material.icons.filled.PlayArrow
import androidx.compose.material3.Button
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.Icon
import androidx.compose.material3.IconButton
import androidx.compose.material3.ListItem
import androidx.compose.material3.ListItemDefaults
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Scaffold
import androidx.compose.material3.Text
import androidx.compose.material3.TopAppBar
import androidx.compose.material3.TopAppBarDefaults
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.draw.shadow
import androidx.compose.ui.graphics.Brush
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.text.style.TextAlign
import androidx.compose.ui.text.style.TextOverflow
import androidx.compose.ui.unit.dp
import androidx.core.net.toUri
import androidx.hilt.navigation.compose.hiltViewModel
import androidx.lifecycle.SavedStateHandle
import androidx.lifecycle.ViewModel
import androidx.lifecycle.compose.collectAsStateWithLifecycle
import androidx.lifecycle.viewModelScope
import dagger.hilt.android.lifecycle.HiltViewModel
import io.kyonqi.musicplayer.data.dao.AlbumDao
import io.kyonqi.musicplayer.data.dao.TrackDao
import io.kyonqi.musicplayer.data.entity.AlbumEntity
import io.kyonqi.musicplayer.data.entity.TrackEntity
import io.kyonqi.musicplayer.data.mapper.toAudioFiles
import io.kyonqi.musicplayer.player.PlayerController
import io.kyonqi.musicplayer.ui.component.AlbumArt
import io.kyonqi.musicplayer.ui.theme.rememberDominantColor
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.launch
import javax.inject.Inject

@HiltViewModel
class AlbumDetailViewModel @Inject constructor(
    savedStateHandle: SavedStateHandle,
    private val albumDao: AlbumDao,
    private val trackDao: TrackDao,
    private val player: PlayerController,
) : ViewModel() {
    private val albumId: Long = savedStateHandle.get<Long>("albumId") ?: 0L

    private val _album = MutableStateFlow<AlbumEntity?>(null)
    val album = _album.asStateFlow()

    private val _tracks = MutableStateFlow<List<TrackEntity>>(emptyList())
    val tracks = _tracks.asStateFlow()

    init {
        viewModelScope.launch {
            val albumEntity = albumDao.getAlbumById(albumId)
            _album.value = albumEntity
            albumEntity?.let { a ->
                trackDao.getTracksByAlbum(a.name).collect { trackList ->
                    _tracks.value = trackList
                }
            }
        }
    }

    fun playAll() {
        val trackList = _tracks.value
        if (trackList.isNotEmpty()) {
            player.setQueue(trackList.toAudioFiles(), 0)
        }
    }

    fun playAt(index: Int) {
        val trackList = _tracks.value
        if (index in trackList.indices) {
            player.setQueue(trackList.toAudioFiles(), index)
        }
    }
}

/**
 * 专辑详情页
 */
@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun AlbumDetailScreen(
    onBack: () -> Unit,
    viewModel: AlbumDetailViewModel = hiltViewModel(),
) {
    val album by viewModel.album.collectAsStateWithLifecycle()
    val tracks by viewModel.tracks.collectAsStateWithLifecycle()

    // 从封面提取主色，用于头部渐变
    val coverUri = album?.coverUri?.takeIf { it.isNotEmpty() }?.toUri()
    val colors by rememberDominantColor(coverUri)
    val dominant = colors?.first ?: MaterialTheme.colorScheme.surfaceVariant
    val surface = MaterialTheme.colorScheme.surface

    Scaffold(
        containerColor = Color.Transparent,
        topBar = {
            TopAppBar(
                title = { Text(album?.name ?: "专辑", maxLines = 1, overflow = TextOverflow.Ellipsis) },
                navigationIcon = {
                    IconButton(onClick = onBack) {
                        Icon(Icons.AutoMirrored.Filled.ArrowBack, "返回")
                    }
                },
                colors = TopAppBarDefaults.topAppBarColors(containerColor = Color.Transparent),
            )
        },
        modifier = Modifier.background(
            Brush.verticalGradient(
                colors = listOf(dominant.copy(alpha = 0.4f), surface),
                endY = 900f,
            )
        ),
    ) { padding ->
        LazyColumn(
            modifier = Modifier.fillMaxSize().padding(padding),
        ) {
            item {
                AlbumHeader(
                    album = album,
                    trackCount = tracks.size,
                    onPlayAll = { viewModel.playAll() },
                )
            }
            itemsIndexed(tracks, key = { _, t -> t.id }) { index, track ->
                AlbumTrackItem(
                    track = track,
                    trackIndex = index + 1,
                    onClick = { viewModel.playAt(index) },
                )
            }
            item { Spacer(Modifier.height(24.dp)) }
        }
    }
}

/**
 * 专辑头部：大封面 + 信息 + 全部播放
 */
@Composable
private fun AlbumHeader(
    album: AlbumEntity?,
    trackCount: Int,
    onPlayAll: () -> Unit,
) {
    Column(
        modifier = Modifier.fillMaxWidth().padding(horizontal = 16.dp, vertical = 24.dp),
        horizontalAlignment = Alignment.CenterHorizontally,
    ) {
        AlbumArt(
            uri = album?.coverUri?.takeIf { it.isNotEmpty() }?.toUri(),
            modifier = Modifier.shadow(12.dp, RoundedCornerShape(16.dp)),
            size = 220.dp,
            shape = RoundedCornerShape(16.dp),
        )

        Spacer(Modifier.height(20.dp))

        Text(
            text = album?.name ?: "",
            style = MaterialTheme.typography.headlineSmall,
            textAlign = TextAlign.Center,
            maxLines = 2,
            overflow = TextOverflow.Ellipsis,
        )
        Spacer(Modifier.height(4.dp))
        Text(
            text = "${album?.artist ?: ""} · $trackCount 首歌曲",
            style = MaterialTheme.typography.bodyMedium,
            color = MaterialTheme.colorScheme.onSurfaceVariant,
        )
        if ((album?.year ?: 0) > 0) {
            Text(
                "${album?.year}",
                style = MaterialTheme.typography.bodySmall,
                color = MaterialTheme.colorScheme.outline,
            )
        }

        Spacer(Modifier.height(16.dp))

        Button(
            onClick = onPlayAll,
            shape = RoundedCornerShape(24.dp),
        ) {
            Icon(Icons.Default.PlayArrow, null, modifier = Modifier.size(18.dp))
            Spacer(Modifier.width(8.dp))
            Text("全部播放")
        }
    }
}

/**
 * 专辑内部歌曲项（用大卡片内的紧凑样式）
 */
@Composable
private fun AlbumTrackItem(
    track: TrackEntity,
    trackIndex: Int,
    onClick: () -> Unit,
) {
    ListItem(
        headlineContent = {
            Text(track.title, maxLines = 1, overflow = TextOverflow.Ellipsis)
        },
        supportingContent = {
            Text(formatDuration(track.durationMs))
        },
        leadingContent = {
            Box(modifier = Modifier.size(32.dp), contentAlignment = Alignment.Center) {
                Text(
                    "$trackIndex",
                    style = MaterialTheme.typography.bodyMedium,
                    color = MaterialTheme.colorScheme.onSurfaceVariant,
                )
            }
        },
        colors = ListItemDefaults.colors(containerColor = Color.Transparent),
        modifier = Modifier.clickable(onClick = onClick),
    )
}

private fun formatDuration(ms: Long): String {
    val totalSeconds = ms / 1000
    return "%d:%02d".format(totalSeconds / 60, totalSeconds % 60)
}

---

13. ui/screen/ArtistDetailScreen.kt ✏️

改动：大头像头部 + 专辑行用横向滚动（保留原单独专辑 ListItem，视觉更紧凑）+ 歌曲用 SongListItem。

package io.kyonqi.musicplayer.ui.screen

import androidx.compose.foundation.background
import androidx.compose.foundation.clickable
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.PaddingValues
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.size
import androidx.compose.foundation.layout.width
import androidx.compose.foundation.lazy.LazyColumn
import androidx.compose.foundation.lazy.LazyRow
import androidx.compose.foundation.lazy.items
import androidx.compose.foundation.lazy.itemsIndexed
import androidx.compose.foundation.shape.CircleShape
import androidx.compose.foundation.shape.RoundedCornerShape
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.automirrored.filled.ArrowBack
import androidx.compose.material.icons.filled.Person
import androidx.compose.material.icons.filled.PlayArrow
import androidx.compose.material3.Button
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.Icon
import androidx.compose.material3.IconButton
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Scaffold
import androidx.compose.material3.Surface
import androidx.compose.material3.Text
import androidx.compose.material3.TopAppBar
import androidx.compose.material3.TopAppBarDefaults
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.draw.clip
import androidx.compose.ui.graphics.Brush
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.text.style.TextOverflow
import androidx.compose.ui.unit.dp
import androidx.core.net.toUri
import androidx.hilt.navigation.compose.hiltViewModel
import androidx.lifecycle.SavedStateHandle
import androidx.lifecycle.ViewModel
import androidx.lifecycle.compose.collectAsStateWithLifecycle
import androidx.lifecycle.viewModelScope
import dagger.hilt.android.lifecycle.HiltViewModel
import io.kyonqi.musicplayer.data.dao.AlbumDao
import io.kyonqi.musicplayer.data.dao.ArtistDao
import io.kyonqi.musicplayer.data.dao.TrackDao
import io.kyonqi.musicplayer.data.entity.AlbumEntity
import io.kyonqi.musicplayer.data.entity.ArtistEntity
import io.kyonqi.musicplayer.data.entity.TrackEntity
import io.kyonqi.musicplayer.data.mapper.toAudioFiles
import io.kyonqi.musicplayer.player.PlayerController
import io.kyonqi.musicplayer.ui.component.AlbumArt
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.launch
import javax.inject.Inject

@HiltViewModel
class ArtistDetailViewModel @Inject constructor(
    savedStateHandle: SavedStateHandle,
    private val artistDao: ArtistDao,
    private val albumDao: AlbumDao,
    private val trackDao: TrackDao,
    private val player: PlayerController,
) : ViewModel() {

    private val artistId: Long = savedStateHandle.get<Long>("artistId") ?: 0L

    private val _artist = MutableStateFlow<ArtistEntity?>(null)
    val artist = _artist.asStateFlow()

    private val _albums = MutableStateFlow<List<AlbumEntity>>(emptyList())
    val albums = _albums.asStateFlow()

    private val _tracks = MutableStateFlow<List<TrackEntity>>(emptyList())
    val tracks = _tracks.asStateFlow()

    init {
        viewModelScope.launch {
            val artistEntity = artistDao.getArtistById(artistId)
            _artist.value = artistEntity
            artistEntity?.let { a ->
                launch { albumDao.getAlbumByArtist(a.name).collect { _albums.value = it } }
                launch { trackDao.getTracksByArtist(a.name).collect { _tracks.value = it } }
            }
        }
    }

    fun playAll() {
        val trackList = _tracks.value
        if (trackList.isNotEmpty()) {
            player.setQueue(trackList.toAudioFiles(), 0)
        }
    }

    fun playAt(index: Int) {
        val trackList = _tracks.value
        if (index in trackList.indices) {
            player.setQueue(trackList.toAudioFiles(), index)
        }
    }
}

/**
 * 艺术家详情页
 */
@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun ArtistDetailScreen(
    onBack: () -> Unit,
    onAlbumClick: (Long) -> Unit,
    viewModel: ArtistDetailViewModel = hiltViewModel(),
) {
    val artist by viewModel.artist.collectAsStateWithLifecycle()
    val albums by viewModel.albums.collectAsStateWithLifecycle()
    val tracks by viewModel.tracks.collectAsStateWithLifecycle()

    val accent = MaterialTheme.colorScheme.secondaryContainer
    val surface = MaterialTheme.colorScheme.surface

    Scaffold(
        containerColor = Color.Transparent,
        topBar = {
            TopAppBar(
                title = { Text(artist?.name ?: "艺术家", maxLines = 1, overflow = TextOverflow.Ellipsis) },
                navigationIcon = {
                    IconButton(onClick = onBack) {
                        Icon(Icons.AutoMirrored.Filled.ArrowBack, "返回")
                    }
                },
                colors = TopAppBarDefaults.topAppBarColors(containerColor = Color.Transparent),
            )
        },
        modifier = Modifier.background(
            Brush.verticalGradient(
                colors = listOf(accent.copy(alpha = 0.5f), surface),
                endY = 700f,
            )
        ),
    ) { padding ->
        LazyColumn(modifier = Modifier.fillMaxSize().padding(padding)) {
            item {
                ArtistHeader(
                    artist = artist,
                    onPlayAll = { viewModel.playAll() },
                )
            }

            if (albums.isNotEmpty()) {
                item {
                    SectionTitle("专辑")
                    LazyRow(
                        contentPadding = PaddingValues(horizontal = 16.dp),
                        horizontalArrangement = Arrangement.spacedBy(12.dp),
                        modifier = Modifier.fillMaxWidth(),
                    ) {
                        items(albums, key = { it.albumId }) { album ->
                            ArtistAlbumCard(album = album, onClick = { onAlbumClick(album.albumId) })
                        }
                    }
                    Spacer(Modifier.height(8.dp))
                }
            }

            item { SectionTitle("歌曲") }
            itemsIndexed(tracks, key = { _, t -> t.id }) { index, track ->
                SongListItem(track = track, onClick = { viewModel.playAt(index) })
            }
            item { Spacer(Modifier.height(24.dp)) }
        }
    }
}

/**
 * 艺术家信息头：圆形头像 + 名字 + 统计 + 全部播放按钮
 */
@Composable
private fun ArtistHeader(
    artist: ArtistEntity?,
    onPlayAll: () -> Unit,
) {
    Column(
        modifier = Modifier.fillMaxWidth().padding(horizontal = 16.dp, vertical = 16.dp),
        horizontalAlignment = Alignment.CenterHorizontally,
    ) {
        Surface(
            modifier = Modifier.size(120.dp),
            shape = CircleShape,
            color = MaterialTheme.colorScheme.secondaryContainer,
        ) {
            Box(contentAlignment = Alignment.Center) {
                Icon(Icons.Default.Person, null, Modifier.size(56.dp))
            }
        }

        Spacer(Modifier.height(16.dp))

        Text(artist?.name ?: "", style = MaterialTheme.typography.headlineSmall)
        Spacer(Modifier.height(4.dp))
        Text(
            "${artist?.albumCount ?: 0} 张专辑 · ${artist?.trackCount ?: 0} 首歌曲",
            style = MaterialTheme.typography.bodyMedium,
            color = MaterialTheme.colorScheme.onSurfaceVariant,
        )

        Spacer(Modifier.height(16.dp))

        Button(onClick = onPlayAll, shape = RoundedCornerShape(24.dp)) {
            Icon(Icons.Default.PlayArrow, null, Modifier.size(18.dp))
            Spacer(Modifier.width(8.dp))
            Text("全部播放")
        }
    }
}

/**
 * 艺术家详情中的专辑小卡（横向滚动）
 */
@Composable
private fun ArtistAlbumCard(
    album: AlbumEntity,
    onClick: () -> Unit,
) {
    Column(
        modifier = Modifier
            .width(140.dp)
            .clip(RoundedCornerShape(12.dp))
            .clickable(onClick = onClick)
            .padding(4.dp),
    ) {
        AlbumArt(
            uri = album.coverUri.takeIf { it.isNotEmpty() }?.toUri(),
            size = 132.dp,
            modifier = Modifier.clip(RoundedCornerShape(12.dp)),
            shape = RoundedCornerShape(12.dp),
        )
        Text(
            text = album.name,
            style = MaterialTheme.typography.bodyMedium,
            maxLines = 1,
            overflow = TextOverflow.Ellipsis,
            modifier = Modifier.padding(top = 6.dp, start = 2.dp, end = 2.dp),
        )
        if (album.year > 0) {
            Text(
                text = "${album.year}",
                style = MaterialTheme.typography.bodySmall,
                color = MaterialTheme.colorScheme.onSurfaceVariant,
                modifier = Modifier.padding(horizontal = 2.dp),
            )
        }
    }
}

/**
 * 分区小标题
 */
@Composable
private fun SectionTitle(text: String) {
    Text(
        text = text,
        style = MaterialTheme.typography.titleMedium,
        modifier = Modifier.padding(horizontal = 16.dp, vertical = 12.dp),
    )
}

---

14. ui/screen/NowPlayingScreen.kt ✏️

沉浸式渐变 + spring 封面缩放 + 透明 TopAppBar。

package io.kyonqi.musicplayer.ui.screen

import androidx.compose.animation.animateColorAsState
import androidx.compose.animation.core.animateFloatAsState
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.aspectRatio
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.size
import androidx.compose.foundation.shape.RoundedCornerShape
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.automirrored.filled.ArrowBack
import androidx.compose.material.icons.filled.Pause
import androidx.compose.material.icons.filled.PlayArrow
import androidx.compose.material.icons.filled.SkipNext
import androidx.compose.material.icons.filled.SkipPrevious
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.FilledIconButton
import androidx.compose.material3.Icon
import androidx.compose.material3.IconButton
import androidx.compose.material3.IconButtonDefaults
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Scaffold
import androidx.compose.material3.Slider
import androidx.compose.material3.SliderDefaults
import androidx.compose.material3.Text
import androidx.compose.material3.TopAppBar
import androidx.compose.material3.TopAppBarDefaults
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.draw.shadow
import androidx.compose.ui.graphics.Brush
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.graphics.graphicsLayer
import androidx.compose.ui.text.style.TextAlign
import androidx.compose.ui.text.style.TextOverflow
import androidx.compose.ui.unit.dp
import androidx.hilt.navigation.compose.hiltViewModel
import androidx.lifecycle.ViewModel
import androidx.lifecycle.compose.collectAsStateWithLifecycle
import dagger.hilt.android.lifecycle.HiltViewModel
import io.kyonqi.musicplayer.player.PlayerController
import io.kyonqi.musicplayer.ui.component.AlbumArt
import io.kyonqi.musicplayer.ui.theme.MotionDefaults
import io.kyonqi.musicplayer.ui.theme.rememberDominantColor
import javax.inject.Inject

@HiltViewModel
class NowPlayingViewModel @Inject constructor(
    private val player: PlayerController,
) : ViewModel() {
    val playbackState = player.playbackState

    fun seekTo(ms: Long) = player.seekTo(ms)

    fun next() = player.next()

    fun previous() = player.previous()

    fun togglePlayPause() = player.togglePlayPause()
}

/**
 * 正在播放页
 * 背景根据封面动态取色做渐变，封面在播放中微妙放大
 */
@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun NowPlayingScreen(
    onBack: () -> Unit,
    viewModel: NowPlayingViewModel = hiltViewModel(),
) {
    val state by viewModel.playbackState.collectAsStateWithLifecycle()
    val colors by rememberDominantColor(state.currentTrack?.uri)

    val fallbackDominant = MaterialTheme.colorScheme.surfaceVariant
    val fallbackMuted = MaterialTheme.colorScheme.surface
    val targetDominant = colors?.first ?: fallbackDominant
    val targetMuted = colors?.second ?: fallbackMuted

    // 切歌时背景颜色平滑过渡
    val animatedDominant by animateColorAsState(
        targetValue = targetDominant,
        animationSpec = MotionDefaults.standard(),
        label = "dominant",
    )
    val animatedMuted by animateColorAsState(
        targetValue = targetMuted,
        animationSpec = MotionDefaults.standard(),
        label = "muted",
    )

    // 正在播放时封面轻微放大
    val coverScale by animateFloatAsState(
        targetValue = if (state.isPlaying) 1.0f else 0.92f,
        animationSpec = MotionDefaults.bouncy(),
        label = "coverScale",
    )

    Box(
        modifier = Modifier
            .fillMaxSize()
            .background(
                Brush.verticalGradient(
                    colors = listOf(
                        animatedDominant,
                        animatedMuted,
                        Color.Black.copy(alpha = 0.4f),
                    ),
                )
            ),
    ) {
        Scaffold(
            containerColor = Color.Transparent,
            topBar = {
                TopAppBar(
                    title = { },
                    navigationIcon = {
                        IconButton(onClick = onBack) {
                            Icon(
                                Icons.AutoMirrored.Filled.ArrowBack,
                                contentDescription = "返回",
                                tint = Color.White,
                            )
                        }
                    },
                    colors = TopAppBarDefaults.topAppBarColors(containerColor = Color.Transparent),
                )
            },
        ) { padding ->
            Column(
                modifier = Modifier
                    .fillMaxSize()
                    .padding(padding)
                    .padding(horizontal = 32.dp),
                horizontalAlignment = Alignment.CenterHorizontally,
            ) {
                Spacer(Modifier.weight(1f))

                // 封面
                AlbumArt(
                    uri = state.currentTrack?.uri,
                    size = 320.dp,
                    shape = RoundedCornerShape(20.dp),
                    modifier = Modifier
                        .fillMaxWidth()
                        .aspectRatio(1f)
                        .graphicsLayer {
                            scaleX = coverScale
                            scaleY = coverScale
                        }
                        .shadow(24.dp, RoundedCornerShape(20.dp)),
                )

                Spacer(Modifier.height(40.dp))

                // 标题 + 艺术家
                Text(
                    text = state.currentTrack?.title ?: "未播放",
                    style = MaterialTheme.typography.headlineSmall,
                    color = Color.White,
                    maxLines = 1,
                    overflow = TextOverflow.Ellipsis,
                    textAlign = TextAlign.Center,
                    modifier = Modifier.fillMaxWidth(),
                )
                Spacer(Modifier.height(4.dp))
                Text(
                    text = state.currentTrack?.artist ?: "",
                    style = MaterialTheme.typography.bodyLarge,
                    color = Color.White.copy(alpha = 0.7f),
                    maxLines = 1,
                    overflow = TextOverflow.Ellipsis,
                    textAlign = TextAlign.Center,
                    modifier = Modifier.fillMaxWidth(),
                )

                Spacer(Modifier.height(24.dp))

                // 进度条
                Column(modifier = Modifier.fillMaxWidth()) {
                    Slider(
                        value = if (state.durationMs > 0) {
                            state.positionMs.toFloat() / state.durationMs.toFloat()
                        } else 0f,
                        onValueChange = { fraction ->
                            viewModel.seekTo((fraction * state.durationMs).toLong())
                        },
                        colors = SliderDefaults.colors(
                            thumbColor = Color.White,
                            activeTrackColor = Color.White,
                            inactiveTrackColor = Color.White.copy(alpha = 0.3f),
                        ),
                    )
                    Row(
                        modifier = Modifier.fillMaxWidth(),
                        horizontalArrangement = Arrangement.SpaceBetween,
                    ) {
                        Text(
                            formatTime(state.positionMs),
                            style = MaterialTheme.typography.bodySmall,
                            color = Color.White.copy(alpha = 0.7f),
                        )
                        Text(
                            formatTime(state.durationMs),
                            style = MaterialTheme.typography.bodySmall,
                            color = Color.White.copy(alpha = 0.7f),
                        )
                    }
                }

                Spacer(Modifier.height(16.dp))

                // 播放器按钮
                Row(
                    modifier = Modifier.fillMaxWidth(),
                    horizontalArrangement = Arrangement.SpaceEvenly,
                    verticalAlignment = Alignment.CenterVertically,
                ) {
                    IconButton(onClick = { viewModel.previous() }) {
                        Icon(
                            Icons.Default.SkipPrevious,
                            "上一首",
                            Modifier.size(40.dp),
                            tint = Color.White,
                        )
                    }
                    FilledIconButton(
                        onClick = { viewModel.togglePlayPause() },
                        modifier = Modifier.size(72.dp),
                        colors = IconButtonDefaults.filledIconButtonColors(
                            containerColor = Color.White,
                            contentColor = Color.Black,
                        ),
                    ) {
                        Icon(
                            if (state.isPlaying) Icons.Default.Pause else Icons.Default.PlayArrow,
                            if (state.isPlaying) "暂停" else "播放",
                            modifier = Modifier.size(40.dp),
                        )
                    }
                    IconButton(onClick = { viewModel.next() }) {
                        Icon(
                            Icons.Default.SkipNext,
                            "下一首",
                            Modifier.size(40.dp),
                            tint = Color.White,
                        )
                    }
                }

                Spacer(Modifier.height(16.dp))

                // 输出信息
                if (state.outputInfo.sampleRate > 0) {
                    Text(
                        text = "${state.outputInfo.sampleRate}Hz / ${state.outputInfo.bitDepth}bit · ${state.outputInfo.outputDevice}",
                        style = MaterialTheme.typography.labelSmall,
                        color = Color.White.copy(alpha = 0.5f),
                    )
                }

                Spacer(Modifier.weight(1f))
            }
        }
    }
}

private fun formatTime(ms: Long): String {
    val totalSec = ms / 1000
    return "%d:%02d".format(totalSec / 60, totalSec % 60)
}

---

15. ui/navigation/AppNavigation.kt ✏️

完整重构：底部 TabBar（4 个 library tab） + MiniPlayer 在 Scaffold.bottomBar 里 + now_playing 走 slide-up/down 转场。扫描触发通过 LibraryScannerViewModel 在顶层激活。

package io.kyonqi.musicplayer.ui.navigation

import android.Manifest
import android.os.Build
import androidx.compose.animation.AnimatedContentTransitionScope
import androidx.compose.animation.AnimatedVisibility
import androidx.compose.animation.core.tween
import androidx.compose.animation.slideInVertically
import androidx.compose.animation.slideOutVertically
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.padding
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Album
import androidx.compose.material.icons.filled.Folder
import androidx.compose.material.icons.filled.MusicNote
import androidx.compose.material.icons.filled.Person
import androidx.compose.material3.Icon
import androidx.compose.material3.LinearProgressIndicator
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.NavigationBar
import androidx.compose.material3.NavigationBarItem
import androidx.compose.material3.Scaffold
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
import androidx.hilt.navigation.compose.hiltViewModel
import androidx.lifecycle.compose.collectAsStateWithLifecycle
import androidx.navigation.NavController
import androidx.navigation.NavGraph.Companion.findStartDestination
import androidx.navigation.NavType
import androidx.navigation.compose.NavHost
import androidx.navigation.compose.composable
import androidx.navigation.compose.currentBackStackEntryAsState
import androidx.navigation.compose.rememberNavController
import androidx.navigation.navArgument
import io.kyonqi.musicplayer.ui.component.MiniPlayer
import io.kyonqi.musicplayer.ui.component.PermissionHandler
import io.kyonqi.musicplayer.ui.screen.AlbumDetailScreen
import io.kyonqi.musicplayer.ui.screen.AlbumListScreen
import io.kyonqi.musicplayer.ui.screen.ArtistDetailScreen
import io.kyonqi.musicplayer.ui.screen.ArtistListScreen
import io.kyonqi.musicplayer.ui.screen.FolderBrowserScreen
import io.kyonqi.musicplayer.ui.screen.LibraryScannerViewModel
import io.kyonqi.musicplayer.ui.screen.NowPlayingScreen
import io.kyonqi.musicplayer.ui.screen.SongListScreen

/** 底部 Tab 路由 */
private object Routes {
    const val SONGS = "library_songs"
    const val ALBUMS = "library_albums"
    const val ARTISTS = "library_artists"
    const val FOLDERS = "library_folders"

    const val ALBUM_DETAIL = "album_detail"
    const val ARTIST_DETAIL = "artist_detail"
    const val NOW_PLAYING = "now_playing"
}

private val TabRoutes = setOf(Routes.SONGS, Routes.ALBUMS, Routes.ARTISTS, Routes.FOLDERS)
private val HiddenBottomBarRoutes = setOf(Routes.NOW_PLAYING)

@Composable
fun AppNavigation() {
    val navController = rememberNavController()
    val currentBackStackEntry by navController.currentBackStackEntryAsState()
    val currentRoute = currentBackStackEntry?.destination?.route

    // 顶层扫描 VM，Activity 作用域共享给 4 个 tab
    val scannerViewModel: LibraryScannerViewModel = hiltViewModel()
    val scanProgress by scannerViewModel.scanProgress.collectAsStateWithLifecycle()

    // 权限授予后触发一次扫描
    val permission = if (Build.VERSION.SDK_INT >= 33) {
        Manifest.permission.READ_MEDIA_AUDIO
    } else {
        Manifest.permission.READ_EXTERNAL_STORAGE
    }
    PermissionHandler(
        permission = permission,
        onGranted = { scannerViewModel.initLibrary() },
    )

    val showBottomBar = currentRoute !in HiddenBottomBarRoutes
    val showTabBar = currentRoute in TabRoutes

    Scaffold(
        modifier = Modifier.fillMaxSize(),
        bottomBar = {
            AnimatedVisibility(
                visible = showBottomBar,
                enter = slideInVertically { it },
                exit = slideOutVertically { it },
            ) {
                Column {
                    MiniPlayer(onClick = { navController.navigate(Routes.NOW_PLAYING) })
                    AnimatedVisibility(visible = showTabBar) {
                        LibraryBottomBar(navController = navController, currentRoute = currentRoute)
                    }
                }
            }
        },
    ) { padding ->
        Column(modifier = Modifier.fillMaxSize().padding(padding)) {
            // 扫描进度条（所有页面顶端共享）
            if (scanProgress.isScanning) {
                LinearProgressIndicator(
                    progress = {
                        if (scanProgress.total > 0)
                            scanProgress.current.toFloat() / scanProgress.total.toFloat()
                        else 0f
                    },
                    modifier = Modifier.fillMaxSize(),
                )
                Text(
                    text = scanProgress.message,
                    style = MaterialTheme.typography.labelSmall,
                    modifier = Modifier.padding(horizontal = 16.dp, vertical = 4.dp),
                )
            }

            NavHost(
                navController = navController,
                startDestination = Routes.SONGS,
                modifier = Modifier.fillMaxSize(),
            ) {
                // 四个 Tab 页
                composable(Routes.SONGS) {
                    SongListScreen(onNavigateToNowPlaying = { navController.navigate(Routes.NOW_PLAYING) })
                }
                composable(Routes.ALBUMS) {
                    AlbumListScreen(onAlbumClick = { id -> navController.navigate("${Routes.ALBUM_DETAIL}/$id") })
                }
                composable(Routes.ARTISTS) {
                    ArtistListScreen(onArtistClick = { id -> navController.navigate("${Routes.ARTIST_DETAIL}/$id") })
                }
                composable(Routes.FOLDERS) {
                    FolderBrowserScreen()
                }

                // 专辑详情
                composable(
                    route = "${Routes.ALBUM_DETAIL}/{albumId}",
                    arguments = listOf(navArgument("albumId") { type = NavType.LongType }),
                ) {
                    AlbumDetailScreen(onBack = { navController.popBackStack() })
                }

                // 艺术家详情
                composable(
                    route = "${Routes.ARTIST_DETAIL}/{artistId}",
                    arguments = listOf(navArgument("artistId") { type = NavType.LongType }),
                ) {
                    ArtistDetailScreen(
                        onBack = { navController.popBackStack() },
                        onAlbumClick = { id -> navController.navigate("${Routes.ALBUM_DETAIL}/$id") },
                    )
                }

                // 正在播放：从下往上滑入
                composable(
                    route = Routes.NOW_PLAYING,
                    enterTransition = {
                        slideIntoContainer(AnimatedContentTransitionScope.SlideDirection.Up, tween(400))
                    },
                    exitTransition = {
                        slideOutOfContainer(AnimatedContentTransitionScope.SlideDirection.Down, tween(400))
                    },
                    popEnterTransition = {
                        slideIntoContainer(AnimatedContentTransitionScope.SlideDirection.Up, tween(400))
                    },
                    popExitTransition = {
                        slideOutOfContainer(AnimatedContentTransitionScope.SlideDirection.Down, tween(400))
                    },
                ) {
                    NowPlayingScreen(onBack = { navController.popBackStack() })
                }
            }
        }
    }
}

/**
 * 底部四个 Tab
 * 切换时用 saveState / restoreState 保留滚动位置
 */
@Composable
private fun LibraryBottomBar(
    navController: NavController,
    currentRoute: String?,
) {
    NavigationBar {
        NavigationBarItem(
            selected = currentRoute == Routes.SONGS,
            onClick = { navController.navigateToTab(Routes.SONGS) },
            icon = { Icon(Icons.Default.MusicNote, null) },
            label = { Text("歌曲") },
        )
        NavigationBarItem(
            selected = currentRoute == Routes.ALBUMS,
            onClick = { navController.navigateToTab(Routes.ALBUMS) },
            icon = { Icon(Icons.Default.Album, null) },
            label = { Text("专辑") },
        )
        NavigationBarItem(
            selected = currentRoute == Routes.ARTISTS,
            onClick = { navController.navigateToTab(Routes.ARTISTS) },
            icon = { Icon(Icons.Default.Person, null) },
            label = { Text("艺术家") },
        )
        NavigationBarItem(
            selected = currentRoute == Routes.FOLDERS,
            onClick = { navController.navigateToTab(Routes.FOLDERS) },
            icon = { Icon(Icons.Default.Folder, null) },
            label = { Text("文件夹") },
        )
    }
}

/**
 * 切换 Tab 的标准做法：popUpTo 到起点 + saveState + restoreState
 * 否则切 Tab 会在回退栈堆积
 */
private fun NavController.navigateToTab(route: String) {
    navigate(route) {
        popUpTo(graph.findStartDestination().id) { saveState = true }
        launchSingleTop = true
        restoreState = true
    }
}

---

16. ui/screen/LibraryScreen.kt 🗑️

删除此文件。Tab 状态和扫描触发都已迁移：

• Tab index → AppNavigation + NavController
• initLibrary() / reflashLibrary() / scanProgress → LibraryScannerViewModel
• TopAppBar("音乐库") 被四个 LargeTopAppBar 替代

---

实施顺序建议（与 plan 的"实施顺序"章节对齐）

1. Day 1 — 新建 MotionDefaults.kt、PaletteExtractor.kt、MusicListItem.kt。编译通过即可
2. Day 2 — 改 SongListScreen.kt，验证 LargeTopAppBar + 圆角卡片观感
3. Day 3 — 改 AlbumListScreen.kt / ArtistListScreen.kt / FolderBrowserScreen.kt（批量应用 LargeTopAppBar）
4. Day 4-5 — 新建 LibraryScannerViewModel.kt，重构 AppNavigation.kt（底部 TabBar），删除 LibraryScreen.kt
5. Day 6 — 改 MiniPlayer.kt 布局
6. Day 7-8 — 改 NowPlayingScreen.kt（渐变 + spring），确认颜色过渡与按钮可见性
7. Day 9 — 改 AlbumDetailScreen.kt / ArtistDetailScreen.kt（大头 + 渐变）
8. Day 10 — AlbumArt.kt 加 shape 参数（可选，如果前面没提前做）
9. Day 11-14 — 联调、深浅色主题验证、空数据边界、长字符串 Ellipsis

---

常见坑

1. rememberDominantColor 返回 null — 说明 Coil 拿不到 Bitmap。检查 AudioCoverFetcher 是否生效（之前踩过的 coil3.Uri vs android.net.Uri 坑）
2. LargeTopAppBar 下面内容被盖住 — 记得给 LazyColumn 用 contentPadding = padding，不要用 Modifier.padding(padding) 加外层（前者让 TopAppBar 与内容有叠加效果，后者会把列表硬压下去）
3. 内层 Column 用 fillMaxSize() — 同样的 bug 之前踩过两次（SongListScreen、NowPlayingScreen 的按钮消失）。只有最外层容器能用 fillMaxSize()，内层一律 fillMaxWidth()
4. Tab 切换后再回来滚动位置丢了 — navigateToTab 必须带 saveState = true / restoreState = true，见 AppNavigation.navigateToTab
5. 渐变背景跳变 — 背景色一定要走 animateColorAsState，否则切歌瞬间闪白或闪黑
6. MiniPlayer 在 now_playing 页仍可见 — 确认 HiddenBottomBarRoutes 包含 Routes.NOW_PLAYING，并且 AnimatedVisibility(visible = showBottomBar) 包裹整个 bottomBar

---

验收清单

• [ ] 冷启动首次进入，扫描进度条能在顶部显示，扫完自动消失
• [ ] 底部 4 个 Tab 可切换，切换有短暂动画，且每个 tab 独立滚动位置
• [ ] 从 MiniPlayer 点击进入 NowPlaying，页面从下往上滑入；返回时滑下去消失
• [ ] NowPlaying 在 now_playing 路由下完全不显示 MiniPlayer 和 NavigationBar
• [ ] 切歌时 NowPlaying 背景颜色平滑过渡（animateColorAsState），封面有 spring 缩放
• [ ] 专辑详情顶部有根据封面的渐变
• [ ] 长歌名 / 长艺术家名 / 长专辑名都正确 ellipsize
• [ ] 深色模式和浅色模式都能正常工作（尤其确认 NowPlayingScreen 的白字在所有取色下可读；如果某些浅色封面下白字看不清，可以根据 dominant.luminance() 动态切换前景色）