compose-hooks

ComposeHooks 使用指南

ComposeHooks 是一个为 Jetpack Compose/Compose Multiplatform 设计的 Hooks 库，灵感来自 React Hooks 和 ahooks。

核心概念

公开的 useXxx Hook 均提供对应的 rememberXxx 别名，选择你喜欢的命名风格。少数历史 API（如 Table.useTableInstance）仅为兼容保留，优先使用顶层 useXxx/rememberXxx。

平台支持

库以 Kotlin Multiplatform 形式发布（artifact id hooks2），覆盖四个目标：

wasmJs 注意事项：

• commonMain 中的 hooks 全部可用；平台强相关 hooks（Android 专属、usePersistent 的存储后端等）需在各 target 的 actual 实现中处理或降级。
• useRequest/useForm/useRedux 使用的 KClass 仅作 Map 键，wasmJs 下可用；真正的反射调用（.call/.callSuspend/.createType）已隔离在 commonJvmAndroid，不影响 wasmJs 编译。
• usePersistent 采用注入式设计（SaveToPersistent<T> 函数类型），wasmJs 下可注入基于 localStorage 的实现。

快速参考

状态管理 Hooks

集合 Hooks

数值 Hooks

副作用 Hooks

防抖与节流

定时器与延迟

时间与日期

数学运算

异步

组件通信

网络请求

全局状态管理

撤销/重做

UI 相关

表单 Hooks

表格 Hooks

平台专属 Hooks

Android

Desktop

详细参考

• 状态管理 Hooks: 见 references/state-hooks.md
• 副作用 Hooks: 见 references/effect-hooks.md
• 工具 Hooks: 见 references/utility-hooks.md
• 网络请求 Hooks: 见 references/request-hooks.md
• Table 相关 Hooks: 见 references/table-hooks.md
• 表单 Hooks: 见 references/form-hooks.md
• SSE 流式连接: 见 references/sse-hooks.md
• 平台专属 Hooks: 见 references/platform-hooks.md
• remember 别名索引: 见 references/remember-aliases.md

常见模式

1. 受控组件

// 推荐：使用 useGetState 解构
val (text, setText) = useGetState("")
OutlinedTextField(
    value = text.value,
    onValueChange = setText,
    label = { Text("输入") }
)

// 或使用 by 委托
var text by useState("")
OutlinedTextField(
    value = text,
    onValueChange = { text = it },
    label = { Text("输入") }
)

2. 解决闭包问题（来自 UseStateExample.kt）

// 方式1: 使用 useGetState 函数式更新
val (state, setState) = useGetState("initial")
LaunchedEffect(Unit) {
    repeat(10) {
        delay(1.seconds)
        setState { "$it." }  // 函数式更新，避免闭包问题
    }
}

// 方式2: 使用 by 委托
var byState by useState("initial")
LaunchedEffect(Unit) {
    repeat(10) {
        delay(1.seconds)
        byState += "."  // 直接修改，无闭包问题
    }
}

// 方式3: 使用 useLatestRef
val (state, setState) = useState("initial")
val stateRef = useLatestRef(state)
LaunchedEffect(Unit) {
    repeat(10) {
        delay(1.seconds)
        setState("${stateRef.current}.")  // 通过 ref 获取最新值
    }
}

3. 网络请求（来自 Auto&Manual.kt）

// 自动请求
val (userInfoState, loadingState, errorState) = useRequest(
    requestFn = { NetApi.userInfo(it) },
    optionsOf = {
        defaultParams = "junerver"  // 自动请求必须设置默认参数
    }
)
val userInfo by userInfoState
val loading by loadingState

if (loading) {
    Text(text = "loading ...")
}
userInfo?.let { Text(text = it.toString()) }

// 手动请求
val (repoInfoState, loadingState, errorState, request) = useRequest(
    requestFn = { it: Tuple2<String, String> ->
        NetApi.repoInfo(it.first, it.second)
    },
    optionsOf = {
        manual = true
        defaultParams = tuple("junerver", "ComposeHooks")
    }
)
TButton(text = "request") { request() }

4. Redux 风格状态管理（来自 UseReducerExample.kt）

// 定义 State 和 Action
data class SimpleData(val name: String, val age: Int)

sealed interface SimpleAction {
    data class ChangeName(val newName: String) : SimpleAction
    data object AgeIncrease : SimpleAction
}

// 定义 Reducer
val simpleReducer: Reducer<SimpleData, SimpleAction> = { prevState, action ->
    when (action) {
        is SimpleAction.ChangeName -> prevState.copy(name = action.newName)
        is SimpleAction.AgeIncrease -> prevState.copy(age = prevState.age + 1)
    }
}

// 使用
val (state, dispatch) = useReducer(
    simpleReducer,
    initialState = SimpleData("default", 18),
    middlewares = arrayOf(logMiddleware())
)

TButton(text = "Change Name") { dispatch(SimpleAction.ChangeName("Alice")) }
TButton(text = "Increase Age") { dispatch(SimpleAction.AgeIncrease) }
Text(text = "State: ${state.value}")

5. 列表操作（来自 UseListExample.kt）

val listState = useList(1, 2, 3)

// 操作方法
listState.add(4)              // 添加
listState.add(0, 0)           // 插入
listState.removeAt(0)         // 删除
listState.removeLast()        // 删除最后一个
listState[0] = 10             // 修改
listState.clear()             // 清空
listState.shuffle()           // 打乱

// 配合 useListReduce
val sum by useListReduce(listState) { a, b -> a + b }

6. 防抖输入（来自 UseDebounceExample.kt）

var inputValue by useState("")
val debouncedValue by useDebounce(
    value = inputValue,
    optionsOf = {
        wait = 500.milliseconds
    }
)

OutlinedTextField(
    value = inputValue,
    onValueChange = { inputValue = it },
    label = { Text("Type something...") }
)

Text(text = "Debounced: $debouncedValue")

7. SSE 流式连接

// 自动连接
val (lastEvent, isStreaming, error) = useSse(
    streamFn = { params: String -> sseService.subscribe(params) },
    optionsOf = {
        defaultParams = "topic-1"
        onEvent = { event -> println("收到: $event") }
    }
)

// 手动连接
val (lastEvent, isStreaming, error, params, send, cancel) = useSse(
    streamFn = { url: String -> sseClient.connect(url) },
    optionsOf = { manual = true }
)
Button(onClick = { send("https://api.example.com/events") }) {
    Text("开始监听")
}