|
| 1 | +--- |
| 2 | +name: compose-hooks |
| 3 | +description: | |
| 4 | + ComposeHooks 项目使用指南 - 为 Jetpack Compose/Compose Multiplatform 提供 React Hooks 风格的状态管理和副作用处理。 |
| 5 | + 使用此技能当需要：(1) 在 Compose 中管理组件状态 (useState, useGetState, useReducer)， |
| 6 | + (2) 处理副作用和生命周期 (useEffect, useMount, useUnmount)， |
| 7 | + (3) 管理网络请求 (useRequest)，(4) 使用防抖/节流 (useDebounce, useThrottle)， |
| 8 | + (5) 管理列表/Map状态 (useList, useMap)，(6) 使用定时器 (useInterval, useTimeout)， |
| 9 | + (7) 全局状态管理 (useSelector, useDispatch)。 |
| 10 | + 关键词: Compose, Hooks, 状态管理, useRequest, useReducer, useState, useEffect |
| 11 | +--- |
| 12 | + |
| 13 | +# ComposeHooks 使用指南 |
| 14 | + |
| 15 | +ComposeHooks 是一个为 Jetpack Compose/Compose Multiplatform 设计的 Hooks 库，灵感来自 React Hooks 和 ahooks。 |
| 16 | + |
| 17 | +## 核心概念 |
| 18 | + |
| 19 | +所有 `useXxx` 函数都有对应的 `rememberXxx` 别名，选择你喜欢的命名风格。 |
| 20 | + |
| 21 | +## 快速参考 |
| 22 | + |
| 23 | +### 状态管理 Hooks |
| 24 | + |
| 25 | +| Hook | 用途 | 示例 | |
| 26 | +|------|------|------| |
| 27 | +| `useState` | 基础状态管理（推荐用 by 委托） | `var state by useState("")` | |
| 28 | +| `useGetState` | 解构使用的状态管理（推荐） | `val (state, setState, getState) = useGetState(0)` | |
| 29 | +| `useBoolean` | 布尔状态管理 | `val (state, toggle, setValue, setTrue, setFalse) = useBoolean(false)` | |
| 30 | +| `useReducer` | Redux 风格状态管理 | `val (state, dispatch) = useReducer(reducer, initialState)` | |
| 31 | +| `useRef` | 不触发重组的引用 | `val ref = useRef(0)` | |
| 32 | +| `useList` | 列表状态管理 | `val list = useList(1, 2, 3)` | |
| 33 | +| `useMap` | Map 状态管理 | `val map = useMap("key" to "value")` | |
| 34 | + |
| 35 | +### 副作用 Hooks |
| 36 | + |
| 37 | +| Hook | 用途 | 示例 | |
| 38 | +|------|------|------| |
| 39 | +| `useEffect` | 副作用处理 | `useEffect(dep) { /* effect */ }` | |
| 40 | +| `useMount` | 组件挂载时执行 | `useMount { loadData() }` | |
| 41 | +| `useUnmount` | 组件卸载时执行 | `useUnmount { cleanup() }` | |
| 42 | +| `useUpdateEffect` | 跳过首次执行的 Effect | `useUpdateEffect(dep) { /* effect */ }` | |
| 43 | + |
| 44 | +### 网络请求 |
| 45 | + |
| 46 | +| Hook | 用途 | 示例 | |
| 47 | +|------|------|------| |
| 48 | +| `useRequest` | 网络请求管理 | `val (data, loading, error, request) = useRequest(requestFn)` | |
| 49 | + |
| 50 | +### 工具 Hooks |
| 51 | + |
| 52 | +| Hook | 用途 | 示例 | |
| 53 | +|------|------|------| |
| 54 | +| `useDebounce` | 防抖值 | `val debouncedValue = useDebounce(value)` | |
| 55 | +| `useThrottle` | 节流值 | `val throttledValue = useThrottle(value)` | |
| 56 | +| `useInterval` | 定时器 | `useInterval { tick() }` | |
| 57 | +| `useTimeout` | 延时执行 | `useTimeoutFn(fn, 1.seconds)` | |
| 58 | +| `useUndo` | 撤销/重做 | `val (state, set, reset, undo, redo) = useUndo(initial)` | |
| 59 | + |
| 60 | +## 详细参考 |
| 61 | + |
| 62 | +- **状态管理 Hooks**: 见 [references/state-hooks.md](references/state-hooks.md) |
| 63 | +- **副作用 Hooks**: 见 [references/effect-hooks.md](references/effect-hooks.md) |
| 64 | +- **工具 Hooks**: 见 [references/utility-hooks.md](references/utility-hooks.md) |
| 65 | +- **网络请求 Hooks**: 见 [references/request-hooks.md](references/request-hooks.md) |
| 66 | + |
| 67 | +## 常见模式 |
| 68 | + |
| 69 | +### 1. 受控组件 |
| 70 | + |
| 71 | +```kotlin |
| 72 | +// 推荐：使用 useGetState 解构 |
| 73 | +val (text, setText) = useGetState("") |
| 74 | +OutlinedTextField( |
| 75 | + value = text.value, |
| 76 | + onValueChange = setText, |
| 77 | + label = { Text("输入") } |
| 78 | +) |
| 79 | + |
| 80 | +// 或使用 by 委托 |
| 81 | +var text by useState("") |
| 82 | +OutlinedTextField( |
| 83 | + value = text, |
| 84 | + onValueChange = { text = it }, |
| 85 | + label = { Text("输入") } |
| 86 | +) |
| 87 | +``` |
| 88 | + |
| 89 | +### 2. 解决闭包问题（来自 UseStateExample.kt） |
| 90 | + |
| 91 | +```kotlin |
| 92 | +// 方式1: 使用 useGetState 函数式更新 |
| 93 | +val (state, setState) = useGetState("initial") |
| 94 | +LaunchedEffect(Unit) { |
| 95 | + repeat(10) { |
| 96 | + delay(1.seconds) |
| 97 | + setState { "$it." } // 函数式更新，避免闭包问题 |
| 98 | + } |
| 99 | +} |
| 100 | + |
| 101 | +// 方式2: 使用 by 委托 |
| 102 | +var byState by useState("initial") |
| 103 | +LaunchedEffect(Unit) { |
| 104 | + repeat(10) { |
| 105 | + delay(1.seconds) |
| 106 | + byState += "." // 直接修改，无闭包问题 |
| 107 | + } |
| 108 | +} |
| 109 | + |
| 110 | +// 方式3: 使用 useLatestRef |
| 111 | +val (state, setState) = useState("initial") |
| 112 | +val stateRef = useLatestRef(state) |
| 113 | +LaunchedEffect(Unit) { |
| 114 | + repeat(10) { |
| 115 | + delay(1.seconds) |
| 116 | + setState("${stateRef.current}.") // 通过 ref 获取最新值 |
| 117 | + } |
| 118 | +} |
| 119 | +``` |
| 120 | + |
| 121 | +### 3. 网络请求（来自 Auto&Manual.kt） |
| 122 | + |
| 123 | +```kotlin |
| 124 | +// 自动请求 |
| 125 | +val (userInfoState, loadingState, errorState) = useRequest( |
| 126 | + requestFn = { NetApi.userInfo(it) }, |
| 127 | + optionsOf = { |
| 128 | + defaultParams = "junerver" // 自动请求必须设置默认参数 |
| 129 | + } |
| 130 | +) |
| 131 | +val userInfo by userInfoState |
| 132 | +val loading by loadingState |
| 133 | + |
| 134 | +if (loading) { |
| 135 | + Text(text = "loading ...") |
| 136 | +} |
| 137 | +userInfo?.let { Text(text = it.toString()) } |
| 138 | + |
| 139 | +// 手动请求 |
| 140 | +val (repoInfoState, loadingState, errorState, request) = useRequest( |
| 141 | + requestFn = { it: Tuple2<String, String> -> |
| 142 | + NetApi.repoInfo(it.first, it.second) |
| 143 | + }, |
| 144 | + optionsOf = { |
| 145 | + manual = true |
| 146 | + defaultParams = tuple("junerver", "ComposeHooks") |
| 147 | + } |
| 148 | +) |
| 149 | +TButton(text = "request") { request() } |
| 150 | +``` |
| 151 | + |
| 152 | +### 4. Redux 风格状态管理（来自 UseReducerExample.kt） |
| 153 | + |
| 154 | +```kotlin |
| 155 | +// 定义 State 和 Action |
| 156 | +data class SimpleData(val name: String, val age: Int) |
| 157 | + |
| 158 | +sealed interface SimpleAction { |
| 159 | + data class ChangeName(val newName: String) : SimpleAction |
| 160 | + data object AgeIncrease : SimpleAction |
| 161 | +} |
| 162 | + |
| 163 | +// 定义 Reducer |
| 164 | +val simpleReducer: Reducer<SimpleData, SimpleAction> = { prevState, action -> |
| 165 | + when (action) { |
| 166 | + is SimpleAction.ChangeName -> prevState.copy(name = action.newName) |
| 167 | + is SimpleAction.AgeIncrease -> prevState.copy(age = prevState.age + 1) |
| 168 | + } |
| 169 | +} |
| 170 | + |
| 171 | +// 使用 |
| 172 | +val (state, dispatch) = useReducer( |
| 173 | + simpleReducer, |
| 174 | + initialState = SimpleData("default", 18), |
| 175 | + middlewares = arrayOf(logMiddleware()) |
| 176 | +) |
| 177 | + |
| 178 | +TButton(text = "Change Name") { dispatch(SimpleAction.ChangeName("Alice")) } |
| 179 | +TButton(text = "Increase Age") { dispatch(SimpleAction.AgeIncrease) } |
| 180 | +Text(text = "State: ${state.value}") |
| 181 | +``` |
| 182 | + |
| 183 | +### 5. 列表操作（来自 UseListExample.kt） |
| 184 | + |
| 185 | +```kotlin |
| 186 | +val listState = useList(1, 2, 3) |
| 187 | + |
| 188 | +// 操作方法 |
| 189 | +listState.add(4) // 添加 |
| 190 | +listState.add(0, 0) // 插入 |
| 191 | +listState.removeAt(0) // 删除 |
| 192 | +listState.removeLast() // 删除最后一个 |
| 193 | +listState[0] = 10 // 修改 |
| 194 | +listState.clear() // 清空 |
| 195 | +listState.shuffle() // 打乱 |
| 196 | + |
| 197 | +// 配合 useListReduce |
| 198 | +val sum by useListReduce(listState) { a, b -> a + b } |
| 199 | +``` |
| 200 | + |
| 201 | +### 6. 防抖输入（来自 UseDebounceExample.kt） |
| 202 | + |
| 203 | +```kotlin |
| 204 | +var inputValue by useState("") |
| 205 | +val debouncedValue by useDebounce( |
| 206 | + value = inputValue, |
| 207 | + optionsOf = { |
| 208 | + wait = 500.milliseconds |
| 209 | + } |
| 210 | +) |
| 211 | + |
| 212 | +OutlinedTextField( |
| 213 | + value = inputValue, |
| 214 | + onValueChange = { inputValue = it }, |
| 215 | + label = { Text("Type something...") } |
| 216 | +) |
| 217 | + |
| 218 | +Text(text = "Debounced: $debouncedValue") |
| 219 | +``` |
0 commit comments