life-echo/app-android/doc/透明化导航栏使用指南.md

# 透明化顶部导航栏使用指南

## 概述

本项目提供了两种方式来实现透明化顶部导航栏：

1. **TransparentTopAppBar** - 用于标准 Material3 TopAppBar 的透明化组件
2. **ChatHeader** - 自定义聊天头部组件，已支持透明化选项

## 使用方法

### 1. 使用 TransparentTopAppBar（推荐）

`TransparentTopAppBar` 是一个可复用的透明化 TopAppBar 组件，提供了三种透明化模式：

#### 完全透明模式

```kotlin
Scaffold(
    topBar = {
        TransparentTopAppBar(
            title = { Text("页面标题") },
            navigationIcon = {
                IconButton(onClick = { navController?.popBackStack() }) {
                    Icon(
                        imageVector = AppIcons.ArrowBack,
                        contentDescription = "返回"
                    )
                }
            },
            transparencyType = TransparencyType.FULLY_TRANSPARENT,
            titleContentColor = MaterialTheme.colorScheme.onSurface,
            navigationIconContentColor = MaterialTheme.colorScheme.onSurface
        )
    }
) { paddingValues ->
    // 页面内容
}
```

#### 半透明模式

```kotlin
TransparentTopAppBar(
    title = { Text("页面标题") },
    transparencyType = TransparencyType.SEMI_TRANSPARENT,
    backgroundColor = MaterialTheme.colorScheme.surface,
    alpha = 0.7f, // 透明度值（0.0-1.0）
    titleContentColor = MaterialTheme.colorScheme.onSurface
)
```

#### 渐变透明模式（推荐）

```kotlin
TransparentTopAppBar(
    title = { Text("页面标题") },
    transparencyType = TransparencyType.GRADIENT,
    backgroundColor = MaterialTheme.colorScheme.surface,
    gradientColors = listOf(
        MaterialTheme.colorScheme.surface.copy(alpha = 0.95f), // 顶部较不透明
        MaterialTheme.colorScheme.surface.copy(alpha = 0.0f)   // 底部完全透明
    ),
    titleContentColor = MaterialTheme.colorScheme.onSurface
)
```

### 2. 使用 ChatHeader 透明化

`ChatHeader` 组件已支持透明化选项：

#### 完全透明

```kotlin
ChatHeader(
    title = "聊天标题",
    isOnline = true,
    onBackClick = { navController?.popBackStack() },
    isTransparent = true,
    transparencyType = 0 // 完全透明
)
```

#### 半透明

```kotlin
ChatHeader(
    title = "聊天标题",
    isOnline = true,
    onBackClick = { navController?.popBackStack() },
    isTransparent = true,
    transparencyType = 1, // 半透明
    alpha = 0.6f // 透明度
)
```

#### 渐变透明

```kotlin
ChatHeader(
    title = "聊天标题",
    isOnline = true,
    onBackClick = { navController?.popBackStack() },
    isTransparent = true,
    transparencyType = 2 // 渐变透明
)
```

## 透明化类型说明

### TransparencyType 枚举

- **FULLY_TRANSPARENT** - 完全透明，背景完全透明
- **SEMI_TRANSPARENT** - 半透明，可以设置 alpha 值控制透明度
- **GRADIENT** - 渐变透明，从顶部到底部逐渐变透明，视觉效果更自然

## 注意事项

1. **状态栏处理**：组件已自动处理状态栏的内边距（`windowInsetsPadding(WindowInsets.statusBars)`），确保内容不会被状态栏遮挡。

2. **文字颜色**：使用透明化时，需要根据背景调整文字颜色以确保可读性：
   - 透明背景：使用 `MaterialTheme.colorScheme.onSurface`
   - 深色背景：使用 `Color.White`
   - 浅色背景：使用 `Color.Black` 或 `MaterialTheme.colorScheme.onSurface`

3. **性能考虑**：渐变透明模式使用了 `Brush.verticalGradient`，性能略低于其他模式，但视觉效果更好。

4. **主题适配**：建议使用 `MaterialTheme.colorScheme` 中的颜色，以确保在不同主题（亮色/暗色）下都能正常显示。

## 示例

参考 `AboutScreen.kt` 中的实现示例。

## 应用到其他屏幕

要将透明化应用到其他使用 TopAppBar 的屏幕，只需：

1. 导入 `TransparentTopAppBar` 和 `TransparencyType`
2. 将 `TopAppBar` 替换为 `TransparentTopAppBar`
3. 选择合适的 `transparencyType`
4. 调整文字颜色以确保可读性

例如，更新 `FeedbackScreen`：

```kotlin
import com.huaga.life_echo.ui.components.common.TransparentTopAppBar
import com.huaga.life_echo.ui.components.common.TransparencyType

// 在 Scaffold 中
topBar = {
    TransparentTopAppBar(
        title = { Text("反馈与客服") },
        navigationIcon = {
            IconButton(onClick = { navController?.popBackStack() }) {
                Icon(
                    imageVector = AppIcons.ArrowBack,
                    contentDescription = "返回",
                    tint = MaterialTheme.colorScheme.onSurface
                )
            }
        },
        transparencyType = TransparencyType.GRADIENT,
        gradientColors = listOf(
            MaterialTheme.colorScheme.surface.copy(alpha = 0.95f),
            MaterialTheme.colorScheme.surface.copy(alpha = 0.0f)
        )
    )
}
```