CompositionLocal 详解

CompositionLocal 是 Jetpack Compose 中用于隐式传递数据的强大工具，它允许在组件树中跨层级共享数据，而无需显式地通过参数传递。

1. 基本概念

什么是 CompositionLocal？

CompositionLocal 是一种上下文机制，可以让你在组件树的某个节点提供值，然后在该节点的所有子组件中都能访问到这个值，无论层级有多深。

工作原理

// 提供值
CompositionLocalProvider(LocalExample provides "Hello") {
    // 所有子组件都能访问这个值
    ChildComponent()
}

// 在深层子组件中获取值
@Composable
fun DeepChild() {
    val value = LocalExample.current // 获取 "Hello"
}

2. 创建 CompositionLocal

两种创建方式

1. staticCompositionLocalOf

// 当值很少改变时使用（性能更好）
val LocalNavController = staticCompositionLocalOf<NavHostController> { 
    error("No NavController provided!") 
}

val LocalCoroutineScope = staticCompositionLocalOf<CoroutineScope> {
    error("No CoroutineScope provided!")
}

特点：

• 值改变时，所有读取该值的组件都会重组
• 适合很少变化的值（如主题、配置、导航控制器等）

2. compositionLocalOf

// 当值可能频繁改变时使用
val LocalUserPreferences = compositionLocalOf<UserPreferences> {
    error("No UserPreferences provided!")
}

val LocalUiState = compositionLocalOf<UiState> {
    UserPreferences.getDefault()
}

特点：

• 值改变时，只有真正读取该值的组件会重组
• 适合可能频繁变化的值

3. 实际使用示例

完整案例：主题系统

// 定义主题相关的 CompositionLocal
data class AppColors(
    val primary: Color,
    val secondary: Color,
    val background: Color
)

val LocalColors = compositionLocalOf<AppColors> { 
    error("No colors provided!") 
}

val LocalTypography = compositionLocalOf<Typography> { 
    error("No typography provided!") 
}

// 提供主题
@Composable
fun AppTheme(
    colors: AppColors = lightColors(),
    typography: Typography = defaultTypography,
    content: @Composable () -> Unit
) {
    CompositionLocalProvider(
        LocalColors provides colors,
        LocalTypography provides typography
    ) {
        content()
    }
}

// 在任何子组件中使用
@Composable
fun MyButton(text: String) {
    val colors = LocalColors.current
    val typography = LocalTypography.current
    
    Button(
        onClick = { /* ... */ },
        colors = ButtonDefaults.buttonColors(backgroundColor = colors.primary)
    ) {
        Text(
            text = text,
            style = typography.button,
            color = colors.secondary
        )
    }
}

导航控制器案例

// 定义
val LocalNavController = staticCompositionLocalOf<NavHostController> {
    error("No NavController provided!")
}

// 在根组件提供
@Composable
fun MyApp() {
    val navController = rememberNavController()
    
    CompositionLocalProvider(LocalNavController provides navController) {
        AppTheme {
            NavHost(navController, "home") {
                composable("home") { HomeScreen() }
                composable("profile") { ProfileScreen() }
                composable("settings") { SettingsScreen() }
            }
        }
    }
}

// 在深层子组件中使用
@Composable
fun HomeScreen() {
    val navController = LocalNavController.current
    
    Column {
        Button(onClick = { navController.navigate("profile") }) {
            Text("Go to Profile")
        }
        Button(onClick = { navController.navigate("settings") }) {
            Text("Go to Settings")
        }
    }
}

@Composable
fun ProfileScreen() {
    val navController = LocalNavController.current
    
    Button(onClick = { navController.popBackStack() }) {
        Text("Back to Home")
    }
}

4. 高级用法

嵌套和覆盖值

@Composable
fun ParentComponent() {
    CompositionLocalProvider(LocalTheme provides LightTheme) {
        Child1() // 使用 LightTheme
        
        CompositionLocalProvider(LocalTheme provides DarkTheme) {
            Child2() // 使用 DarkTheme（覆盖父级的值）
        }
        
        Child3() // 使用 LightTheme（回到父级的值）
    }
}

提供多个值

@Composable
fun AppProviders(
    navController: NavHostController,
    coroutineScope: CoroutineScope,
    preferences: UserPreferences,
    content: @Composable () -> Unit
) {
    CompositionLocalProvider(
        LocalNavController provides navController,
        LocalCoroutineScope provides coroutineScope,
        LocalPreferences provides preferences
    ) {
        content()
    }
}

条件性提供值

@Composable
fun AdaptiveTheme(
    isDarkMode: Boolean,
    content: @Composable () -> Unit
) {
    val theme = if (isDarkMode) DarkTheme else LightTheme
    
    CompositionLocalProvider(LocalTheme provides theme) {
        content()
    }
}

5. 最佳实践

什么时候使用 CompositionLocal？

适合使用的情况：

• ✅ 主题、配置等全局设置
• ✅ 导航控制器
• ✅ 依赖注入（如 Repository、DataSource）
• ✅ 当前用户信息、权限等上下文

不适合使用的情况：

• ❌ 组件特定的状态（应该通过参数传递）
• ❌ 频繁变化的数据（考虑使用 State Hoisting）
• ❌ 简单的父子组件通信

命名规范

// 好的命名
val LocalNavigationController
val LocalCurrentUser
val LocalAppPreferences

// 避免的命名
val navControllerLocal  // 不以 Local 开头
val LOCAL_THEME         // 全大写（不符合 Kotlin 惯例）

错误处理

// 提供默认值而不是抛出错误
val LocalUserPreferences = compositionLocalOf<UserPreferences> {
    UserPreferences.getDefault()  // 提供合理的默认值
}

// 或者提供空安全版本
val LocalNullableNavController = compositionLocalOf<NavHostController?> { 
    null 
}

@Composable
fun SafeNavigationComponent() {
    val navController = LocalNullableNavController.current
    
    if (navController != null) {
        // 安全使用
        Button(onClick = { navController.navigate("next") }) {
            Text("Navigate")
        }
    } else {
        Text("Navigation not available")
    }
}

6. 与其他方案的对比

方案	优点	缺点	适用场景
参数传递	明确、类型安全	深层嵌套时繁琐	简单组件通信
CompositionLocal	跨层级访问、简洁	隐式依赖、调试稍难	全局上下文、主题、配置
ViewModel	状态管理、生命周期感知	需要架构支持	复杂业务逻辑、数据持久化

7. 调试和测试

调试技巧

// 检查是否提供了值
@Composable
fun DebugComponent() {
    val navController = LocalNavController.current
    println("Current route: ${navController.currentDestination?.route}")
}

测试方案

@Test
fun testComponentWithCompositionLocal() {
    composeTestRule.setContent {
        CompositionLocalProvider(LocalNavController provides testNavController) {
            MyComponent()
        }
    }
    
    // 进行测试断言
}

总结

CompositionLocal 是 Compose 中非常强大的工具，但需要谨慎使用。记住以下关键点：

1. 明确使用场景：只在真正需要跨层级共享数据时使用
2. 选择合适的类型 ：根据值的变化频率选择 staticCompositionLocalOf 或 compositionLocalOf
3. 遵循命名规范 ：以 Local 开头，使用驼峰命名法
4. 提供合理的错误处理：考虑提供默认值而不是直接抛出错误
5. 避免滥用：过度使用会让组件依赖关系变得不清晰

正确使用 CompositionLocal 可以大大简化代码结构，提高开发效率！