Jetpack Compose中ComposeViewAdapter用途、预览问题及与ComposeView的区别

核心用途 #

ComposeViewAdapter 属于 Jetpack Compose 的 ui-tooling 工具库组件，仅用于 Android Studio 布局预览场景，作用是在传统 XML 布局的设计预览面板中直接渲染指定的 Compose 可组合函数，方便 XML 与 Compose 混合开发时，统一预览整个页面的结构效果，无需单独跳转至 Kotlin 文件查看可组合项预览。

预览不显示的修复方案 #

你当前配置错误点为 tools:composableName 属性值填写不完整，该属性需要指定到可组合函数的全限定名，而非仅 Kotlin 文件名。Kotlin 顶层可组合函数编译后，会生成以「文件名+Kt」为类名的静态方法，因此你需要补充函数名后缀。

同时需要确认如下前提条件是否满足：

• 模块已引入 Compose 工具库依赖：debugImplementation "androidx.compose.ui:ui-tooling:你的Compose版本号"
• 目标可组合函数已添加 @Preview 注解（你的代码已满足该要求）
• Android Studio 版本与当前使用的 Compose 版本兼容，建议使用 Hedgehog 及以上版本

修复后的 XML 配置如下：

<androidx.compose.ui.tooling.ComposeViewAdapter
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:composableName="com.example.ExampleKt.ExampleComposable" />

和 ComposeView 的核心区别 #

• 适用场景不同
  • androidx.compose.ui.platform.ComposeView 是运行时正式组件，归属 ui-platform 库，是 View 体系嵌入 Compose 内容的核心载体，会被打包进正式 APK，线上运行时生效，可用于生产环境。
  • ComposeViewAdapter 是预览专用工具类，归属 ui-tooling 库，仅在 Debug 构建和 Android Studio 预览时生效，不会打包进正式 APK，不可用于生产环境。
• 使用方式不同
  • 使用 ComposeView 时，需要在 Activity/Fragment 代码中调用 setContent 方法传入可组合函数，完成运行时绑定。
  • 使用 ComposeViewAdapter 仅需在 XML 中通过 tools:composableName 指定目标可组合函数即可，无需额外编写 Kotlin/Java 代码。
• 能力范围不同
  • ComposeView 支持 Compose 全部运行时能力，包括状态管理、用户交互、生命周期绑定等。
  • ComposeViewAdapter 仅支持预览可组合函数的静态 UI 效果，不支持交互操作，也不会绑定实际页面生命周期。

内容的提问来源于stack exchange，提问作者Mahozad