RingAppKMP/SystemBars_README.md

iOS 透明状态栏和导航栏实现

概述

本项目成功实现了iOS应用的透明状态栏和导航栏效果，让应用背景图片能够延伸到状态栏和导航栏区域，同时提供了动态获取系统栏高度的功能，确保内容不被遮挡。

实现的功能

1. 透明状态栏和导航栏

• ✅ iOS状态栏完全透明
• ✅ 内容延伸到状态栏区域
• ✅ 状态栏文字为白色（适合深色背景）
• ✅ 底部安全区域处理

2. 动态高度获取

• ✅ Android平台：动态获取真实的状态栏和导航栏高度
• ✅ iOS平台：根据设备类型返回合适的高度值
• ✅ 跨平台统一API

3. Compose组件支持

• ✅ systemBarsPadding() - 添加状态栏和导航栏内边距
• ✅ statusBarsPadding() - 只添加状态栏内边距
• ✅ navigationBarsPadding() - 只添加导航栏内边距
• ✅ StatusBarSpacer - 状态栏空白组件
• ✅ NavigationBarSpacer - 导航栏空白组件

使用方法

1. 基本用法

@Composable
fun MyScreen() {
    Box(modifier = Modifier.fillMaxSize()) {
        // 背景图片，延伸到整个屏幕
        Image(
            painter = painterResource(Res.drawable.background),
            contentDescription = null,
            modifier = Modifier.fillMaxSize(),
            contentScale = ContentScale.Crop
        )
        
        // 内容区域，添加系统栏内边距
        Column(
            modifier = Modifier
                .fillMaxSize()
                .systemBarsPadding() // 关键：添加系统栏内边距
        ) {
            // 您的内容
            Text("这里的内容不会被状态栏遮挡")
        }
    }
}

2. 只处理状态栏

@Composable
fun MyTopBar() {
    Row(
        modifier = Modifier
            .fillMaxWidth()
            .statusBarsPadding() // 只添加状态栏内边距
            .padding(horizontal = 16.dp)
    ) {
        // 顶部栏内容
    }
}

3. 使用空白组件

@Composable
fun MyContent() {
    Column {
        StatusBarSpacer() // 状态栏高度的空白
        
        // 您的内容
        Text("内容从这里开始")
        
        Spacer(modifier = Modifier.weight(1f))
        
        NavigationBarSpacer() // 导航栏高度的空白
    }
}

4. 获取高度值

@Composable
fun MyComponent() {
    val statusBarHeight = getStatusBarHeight()
    val navigationBarHeight = getNavigationBarHeight()
    
    Text("状态栏高度: $statusBarHeight")
    Text("导航栏高度: $navigationBarHeight")
}

平台特定实现

Android

• 使用系统资源获取真实的状态栏和导航栏高度
• 支持不同屏幕密度的自动适配
• 兼容现有的ImmersionBar透明状态栏设置

iOS

• 状态栏高度：iPhone 44dp，iPad 24dp
• 导航栏高度：iPhone 34dp（有Home指示器），iPad 0dp
• 在Swift层实现透明状态栏效果

文件结构

composeApp/src/
├── commonMain/kotlin/com/whitefish/app/
│   ├── Platform.kt                    # 平台接口定义
│   └── ui/components/
│       └── SystemBarsPadding.kt       # 系统栏内边距组件
├── androidMain/kotlin/com/whitefish/app/
│   └── Platform.android.kt            # Android平台实现
└── iosMain/kotlin/com/whitefish/app/
    └── Platform.ios.kt                # iOS平台实现

iosApp/iosApp/
├── ContentView.swift                  # iOS主视图
├── StatusBarConfig.swift              # 状态栏配置
├── iOSApp.swift                      # iOS应用入口
└── Info.plist                       # iOS配置文件

技术要点

1. iOS透明状态栏实现

• 使用自定义UIViewController控制状态栏外观
• 设置preferredStatusBarStyle = .lightContent
• 配置视图背景为透明
• 内容延伸到所有边缘

2. 高度获取策略

• Android：使用系统资源动态获取
• iOS：基于设备类型的预设值
• 提供fallback机制确保稳定性

3. Compose集成

• 使用expect/actual机制实现跨平台API
• 提供Modifier扩展函数简化使用
• 支持组合式和声明式两种使用方式

注意事项

1. iOS设备适配：当前iOS实现使用预设值，未来可以考虑使用更精确的动态获取方式
2. Android兼容性：与现有的StatusBarView组件兼容，可以逐步迁移
3. 性能考虑：高度获取在Compose中会被缓存，不会重复计算

示例效果

使用这些组件后，您的应用将实现：

• 背景图片延伸到状态栏，营造沉浸式体验
• 内容区域正确避开系统栏，不被遮挡
• iOS和Android平台效果一致
• 代码简洁，易于维护