Accompanist的使用：

一、基础概述

1. 是什么

Google 官方维护的 Compose 扩展工具合集，模块化拆分，按需引入依赖，每个模块独立，不强制引入全部。解决 Compose 原生痛点：

• 无原生运行时权限 API
• 无原生下拉刷新
• 无原生流式布局
• 导航无页面切换动画、底部 Sheet 路由不完善
• 系统状态栏 / 导航栏适配、XML 主题兼容、Drawable 兼容
• 各种原生缺失工具方法

2. 版本适配（2026 最新，必看）

最新稳定版：0.37.3

• 适配 Compose 1.7.x / 1.8.x（当前 AS Hedgehog/ Iguana 默认版本）
• 版本严格绑定 Compose 版本，版本不匹配会编译报错
• 官方文档：google.github.io/accompanist…Google

3. 模块化依赖（Kotlin DSL，build.gradle.kts 直接复制）

全部模块按需引入，不要一次性全引，只引入你用到的。

kotlin

// 统一版本
val accompanistVersion = "0.37.3"

// 1. 运行时权限（最常用）
implementation("com.google.accompanist:accompanist-permissions:$accompanistVersion")


// 2. 下拉刷新 SwipeRefresh
implementation("com.google.accompanist:accompanist-swiperefresh:$accompanistVersion")

// 3. 流式布局 FlowLayout（自动换行标签流）
implementation("com.google.accompanist:accompanist-flowlayout:$accompanistVersion")

// 4. 系统栏适配（状态栏、导航栏、沉浸式）
implementation("com.google.accompanist:accompanist-insets:$accompanistVersion")
implementation("com.google.accompanist:accompanist-systemuicontroller:$accompanistVersion")

二、各模块详细使用（完整可运行代码，日常开发全覆盖）

1. Permissions 运行时权限（Compose 最强权限库，完全替代 Activity Result API）

Compose 原生无任何权限 API，全靠 Accompanist 实现，Compose 页面权限申请唯一官方方案。

核心 API

• rememberPermissionState()：单个权限状态
• rememberMultiplePermissionsState()：多个权限状态
• 自带生命周期安全、状态自动恢复、无需 Launcher、无需 Activity 转发

单个权限（相机权限示例）

kotlin

import com.google.accompanist.permissions.ExperimentalPermissionsApi
import com.google.accompanist.permissions.rememberPermissionState
import android.Manifest

@OptIn(ExperimentalPermissionsApi::class)
@Composable
fun CameraPermissionDemo() {
    // 1. 注册权限状态（Composable 内声明）
    val cameraPermission = rememberPermissionState(Manifest.permission.CAMERA)

    Column(modifier = Modifier.fillMaxSize()) {
        Button(onClick = {
            // 2. 发起申请
            cameraPermission.launchRequest()
        }) {
            Text("申请相机权限")
        }

        // 3. 权限状态判断
        when {
            cameraPermission.status.isGranted -> {
                Text("✅ 相机权限已授予")
            }
            cameraPermission.status.shouldShowRationale -> {
                // 拒绝过、未永久拒绝：解释权限用途
                Text("需要相机权限用于拍照")
                Button(onClick = { cameraPermission.launchRequest() }) {
                    Text("重新申请")
                }
            }
            cameraPermission.status.isPermanentlyDenied -> {
                // 永久拒绝（勾选不再询问）：引导跳转系统设置
                Text("❌ 权限已永久拒绝，请去设置开启")
                Button(onClick = { cameraPermission.openAppSettings() }) {
                    Text("前往设置")
                }
            }
        }
    }
}

多个权限同时申请（相机 + 存储）

kotlin

@OptIn(ExperimentalPermissionsApi::class)
@Composable
fun MultiPermissionDemo() {
    val multiplePermissions = rememberMultiplePermissionsState(
        permissions = listOf(
            Manifest.permission.CAMERA,
            Manifest.permission.READ_EXTERNAL_STORAGE
        )
    )

    Button(onClick = { multiplePermissions.launchRequest() }) {
        Text("申请相机+存储权限")
    }

    // 遍历所有权限结果
    multiplePermissions.permissions.forEach { (permission, state) ->
        Text("${permission}: ${state.isGranted}")
    }

    // 全部权限通过判断
    if (multiplePermissions.allPermissionsGranted) {
        Text("全部权限已授权")
    }
}

优势总结

• 纯 Compose 写法，不需要 Activity、不需要 Activity Result Launcher
• 状态可观察、Compose 状态驱动、自动生命周期管理
• 内置永久拒绝、引导设置、权限理由提示全套逻辑
• 全 Android 版本兼容，无需版本判断

2. SwipeRefresh 下拉刷新（Compose 下拉刷新）

对应原生 SwipeRefreshLayout，Compose 原生无官方下拉刷新，Accompanist 实现标准下拉刷新。

kotlin

import com.google.accompanist.swiperefresh.SwipeRefresh
import com.google.accompanist.swiperefresh.rememberSwipeRefreshState
import androidx.compose.runtime.collectAsStateWithLifecycle

@Composable
fun SwipeRefreshDemo(viewModel: MainViewModel) {
    // 监听加载状态
    val isRefreshing by viewModel.isLoading.collectAsStateWithLifecycle()

    SwipeRefresh(
        state = rememberSwipeRefreshState(isRefreshing),
        onRefresh = { viewModel.refreshData() }, // 下拉刷新回调
    ) {
        // 你的列表内容（LazyColumn）
        LazyColumn(modifier = Modifier.fillMaxSize()) {
            items(20) {
                Text("列表条目 $it", Modifier.padding(16.dp))
            }
        }
    }
}

注：该模块未废弃，日常开发依旧广泛使用。

3. FlowLayout 流式布局（标签自动换行，高频刚需）

Compose 原生只有 Row/Column，无流式布局（标签、标签流自动换行），这是项目最高频需求。

kotlin

import com.google.accompanist.flowlayout.FlowRow

@Composable
fun FlowLayoutDemo() {
    FlowRow(
        modifier = Modifier.fillMaxWidth(),
        mainAxisSpacing = 10.dp, // 水平间距
        crossAxisSpacing = 10.dp, // 垂直行间距
    ) {
        // 任意子组件，自动换行
        listOf("Android", "Compose", "Kotlin", "Jetpack", "Accompanist", "MVVM", "Hilt").forEach { tag ->
            Chip(text = tag)
        }
    }
}

// 简易标签组件
@Composable
fun Chip(text: String) {
    Surface(
        color = Color(0xFFE3F2FD),
        shape = RoundedCornerShape(20.dp)
    ) {
        Text(text, Modifier.padding(horizontal = 12.dp, vertical = 4.dp), color = Color(0xFF2196F3))
    }
}

4. Insets + SystemUiController 系统栏适配（沉浸式、状态栏变色）

Compose 原生系统栏适配极其难用，Accompanist 一键适配状态栏、导航栏、刘海屏、底部安全区、沉浸式。

依赖

kotlin

implementation("com.google.accompanist:accompanist-insets:$accompanistVersion")
implementation("com.google.accompanist:accompanist-systemuicontroller:$accompanistVersion")

完整沉浸式 + 状态栏变色代码

kotlin

import com.google.accompanist.systemuicontroller.rememberSystemUiController
import com.google.accompanist.insets.ProvideWindowInsets
import com.google.accompanist.insets.navigationBarsPadding
import com.google.accompanist.insets.statusBarsPadding

@Composable
fun SystemUiDemo() {
    // 包裹全局Compose，提供WindowInsets
    ProvideWindowInsets {
        val systemUiController = rememberSystemUiController()

        SideEffect {
            // 设置状态栏：透明 + 深色字体（安卓浅色状态栏）
            systemUiController.setStatusBarColor(
                color = Color.Transparent,
                darkIcons = true
            )
            // 设置底部导航栏透明
            systemUiController.setNavigationBarColor(Color.Transparent)
        }

        Column(
            modifier = Modifier
                .fillMaxSize()
                .statusBarsPadding() // 顶部避开状态栏
                .navigationBarsPadding() // 底部避开导航栏安全区
        ) {
            Text("沉浸式页面内容", Modifier.padding(20.dp))
        }
    }
}

核心能力

• 一键状态栏透明、修改颜色、切换黑白字体
• 底部导航栏适配、安全区 Padding 自动添加
• 适配刘海屏、挖孔屏、全面屏所有机型
• 全局统一控制，无需修改 Activity 主题