Circuit实战教程：10分钟构建你的第一个Compose应用

Circuit实战教程：10分钟构建你的第一个Compose应用

【免费下载链接】circuit ⚡️ A Compose-driven architecture for Kotlin and Android applications. 项目地址: https://gitcode.com/gh_mirrors/cir/circuit

Circuit是一个基于Compose驱动的Kotlin和Android应用架构，能帮助开发者快速构建现代化、跨平台的应用界面。本教程将带你在10分钟内完成一个简单的邮件应用，体验Circuit的核心功能和开发流程。

准备工作：环境搭建

首先确保你的开发环境已配置好Compose。如果从零开始，可以按照以下步骤添加Circuit依赖：

1. 克隆仓库：

git clone https://gitcode.com/gh_mirrors/cir/circuit

2. 在项目的build.gradle.kts中添加核心依赖：

dependencies {
  implementation("com.slack.circuit:circuit-foundation:<version>")
}

Circuit提供了多种模块化组件，包括circuit-runtime（核心运行时）、circuit-presenter（状态管理）和circuit-ui（界面渲染）等，完整的依赖说明可参考docs/setup.md。

第一步：创建Screen组件

在Circuit中，Screen是应用的导航基本单元，通常用数据类表示。我们先创建一个邮件列表界面的InboxScreen：

// 多平台版本
data object InboxScreen : Screen

Android平台还需添加@Parcelize注解以支持状态保存：

@Parcelize
data object InboxScreen : Screen

第二步：设计状态与UI

Circuit采用单向数据流架构，状态(State)由Presenter产生并传递给UI渲染。我们先定义邮件列表的状态结构：

data object InboxScreen : Screen {
  data class State(
    val emails: List<Email>,
    val eventSink: (Event) -> Unit
  ) : CircuitUiState
  
  sealed class Event : CircuitUiEvent {
    data class EmailClicked(val emailId: String) : Event()
  }
}

接着实现UI组件，使用Compose的LazyColumn展示邮件列表：

@Composable
fun Inbox(state: InboxScreen.State, modifier: Modifier = Modifier) {
  Scaffold(topBar = { TopAppBar(title = { Text("Inbox") }) }) { innerPadding ->
    LazyColumn(modifier = Modifier.padding(innerPadding)) {
      items(state.emails) { email ->
        EmailItem(
          email = email,
          onClick = { state.eventSink(InboxScreen.Event.EmailClicked(email.id)) }
        )
      }
    }
  }
}

邮件列表界面效果如下：

第三步：实现Presenter

Presenter负责业务逻辑和状态管理，我们创建一个简单的InboxPresenter来提供邮件数据：

class InboxPresenter(
  private val navigator: Navigator,
  private val emailRepository: EmailRepository
) : Presenter<InboxScreen.State> {
  @Composable
  override fun present(): InboxScreen.State {
    val emails by produceState(emptyList()) {
      value = emailRepository.getEmails()
    }
    
    return InboxScreen.State(emails) { event ->
      when (event) {
        is InboxScreen.Event.EmailClicked -> 
          navigator.goTo(DetailScreen(event.emailId))
      }
    }
  }
}

第四步：配置Circuit实例

将Screen、Presenter和UI组件通过Circuit实例关联起来：

val circuit = Circuit.Builder()
  .addPresenterFactory(InboxPresenter.Factory(emailRepository))
  .addUi<InboxScreen, InboxScreen.State> { state, modifier -> 
    Inbox(state, modifier) 
  }
  .build()

第五步：添加导航功能

Circuit提供了BackStack和Navigator实现页面导航。在应用入口处设置导航：

val backStack = rememberSaveableBackStack(root = InboxScreen)
val navigator = rememberCircuitNavigator(backStack) { finish() }

CircuitCompositionLocals(circuit) {
  NavigableCircuitContent(navigator = navigator, backStack = backStack)
}

添加邮件详情页后，点击列表项即可导航到详情界面：

完整代码结构

完成的项目结构应包含以下核心文件：

• InboxScreen.kt：定义列表界面的Screen、State和UI
• DetailScreen.kt：定义详情界面的Screen、State和UI
• InboxPresenter.kt：处理列表页业务逻辑
• DetailPresenter.kt：处理详情页业务逻辑
• MainActivity.kt：应用入口，配置Circuit和导航

运行应用

根据平台不同，使用相应的命令运行应用：

• Android：./gradlew :samples:tutorial:installDebug
• 桌面端：./gradlew :samples:tutorial:run

总结

通过本教程，你已掌握Circuit的核心概念：

• 使用Screen定义导航单元
• 通过State和Event实现单向数据流
• 用Presenter处理业务逻辑
• 配置Circuit连接各组件
• 使用Navigator实现页面导航

Circuit还提供了状态保留、共享元素过渡、测试工具等高级功能，更多内容可参考官方文档docs/index.md。现在就开始用Circuit构建你的下一个Compose应用吧！ 🚀

【免费下载链接】circuit ⚡️ A Compose-driven architecture for Kotlin and Android applications. 项目地址: https://gitcode.com/gh_mirrors/cir/circuit