@react-native-ohos/react-native-keyboard-controller 1.16.8 → 1.17.0

package/README.OpenSource

@@ -3,9 +3,9 @@
         "Name": "react-native-keyboard-controller",
         "License": "MIT License",
         "License File": "https://github.com/kirillzyusko/react-native-keyboard-controller/blob/main/LICENSE",
-        "Version Number": "1.16.5",
+        "Version Number": "1.21.8",
         "Owner" : "xiafeng@huawei.com",
         "Upstream URL": "https://github.com/kirillzyusko/react-native-keyboard-controller",
         "Description": "Keyboard manager which works in identical way on  iOS and Android and harmony"
     }
-]
+]

package/README.md

@@ -10,7 +10,7 @@
 
 | 三方库名称 | 三方库版本（npm地址） | 发布信息 | 支持RN版本 | Autolink | 编译API版本 | 社区基线版本 | 源码地址 |
 | ---------- | --------------------- | -------- | ---------- | -------- | ----------- | ------------ | -------- |
-| @react-native-ohos/react-native-keyboard-controller   | [~ 1.16.7](https://www.npmjs.com/package/@react-native-ohos/react-native-keyboard-controller) | [Gitcode Releases](https://gitcode.com/CPF-RN/rntpc_react-native-keyboard-controller/releases) | 0.77.*     | 否       | API12+      | 1.16.5       | [br_rnoh0.77](https://gitcode.com/CPF-RN/rntpc_react-native-keyboard-controller/tree/br_rnoh0.77) |
+| @react-native-ohos/react-native-keyboard-controller   | [~ 1.17.0(开发中)](https://www.npmjs.com/package/@react-native-ohos/react-native-keyboard-controller) | [GitCode Releases](https://gitcode.com/CPF-RN/rntpc_react-native-keyboard-controller/releases) | 0.82.*     | 是       | API12+      | 1.21.8       | [br_rnoh0.82](https://gitcode.com/CPF-RN/rntpc_react-native-keyboard-controller/tree/br_rnoh0.82) |
 
 ## 简介
 
@@ -43,8 +43,10 @@ yarn add @react-native-ohos/react-native-keyboard-controller
 
 |                               | 是否支持autolink  | RN框架版本 |
 |-------------------------------|------------------|-----------|
-| ~ 1.16.7                      |  No              |  0.77     |
+| ~ 1.17.0                   |  Yes           |  0.82  |
 
+<details>
+  <summary>ManualLink: 此步骤为手动配置原生依赖项的指导</summary>
 
 首先需要使用 DevEco Studio 打开项目里的 HarmonyOS 工程 `harmony`。
 
@@ -57,7 +59,7 @@ yarn add @react-native-ohos/react-native-keyboard-controller
 ```json
 {
   "overrides": {
-    "@rnoh/react-native-openharmony": "^0.77.38" // ohpm 在线版本
+    "@rnoh/react-native-openharmony": "^0.82.1" // ohpm 在线版本
     // "@rnoh/react-native-openharmony" : "./react_native_openharmony.har" // 指向本地 har 包的路径
     // "@rnoh/react-native-openharmony" : "./react_native_openharmony" // 指向源码路径
   }
@@ -175,8 +177,7 @@ export function createRNPackages(ctx: RNPackageContext): RNPackage[] {
   ];
 }
 ```
-
-
+</details>
 
 ### 运行
 
@@ -199,15 +200,15 @@ ohpm install
 
 在以下版本验证通过：
 
-1. RNOH: 0.77.61; SDK: HarmonyOS 6.0.0 Release SDK; IDE: DevEco Studio 6.0.0.858; ROM: 6.0.0.112;
+1. RNOH: 0.82.20; SDK: HarmonyOS 6.0.1 Release SDK; IDE: DevEco Studio 6.0.1 Release; ROM: 6.0.0.120 SP7;
 
 ### 编译运行API要求
 
 > [!TIP] 当前分支版本支持在 `API12+` 工程编译，及 `API12+` ROM运行。
 
 > [!TIP] 以下功能依赖特定版本的API，使用 `低于指定API版本的工程编译` 或 `低于指定API版本的ROM运行` 均可能导致部分功能受限。
-1. 版本 >=1.16.7 for 0.77引入[OH_ArkUI_FocusRequest](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-native-interface-focus-h#oh_arkui_focusrequest),实现了 `onNextCallback?: () => void` 和 `onPrevCallback?: () => void` 功能，此API需要在支持`API15+`的工程编译，并在支持`API15+`的ROM上运行，方可生效。
-2. 版本 >=1.16.8 for 0.77引入了[on('keyboardWillShow')](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-window-window#onkeyboardwillshow20)和[on('keyboardWillHide')](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-window-window#onkeyboardwillhide20)，实现了`KeyboardEvents`中的`keyboardWillShow`键盘将要显示事件和`keyboardWillHide`键盘将要隐藏事件功能，这些API需要在支持`API20+`的工程编译，并在支持`API20+`的ROM上运行，方可生效。
+1. 版本 >=1.17.0 for 0.82引入[OH_ArkUI_FocusRequest](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-native-interface-focus-h#oh_arkui_focusrequest),实现了 `onNextCallback?: (event: GestureResponderEvent) => void` 和 `onPrevCallback?: (event: GestureResponderEvent) => void` 功能，此API需要在支持`API15+`的工程编译，并在支持`API15+`的ROM上运行，方可生效。
+2. 版本 >=1.17.0 for 0.82引入了[on('keyboardWillShow')](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-window-window#onkeyboardwillshow20)和[on('keyboardWillHide')](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-window-window#onkeyboardwillhide20)，实现了`KeyboardEvents`中的`keyboardWillShow`键盘将要显示事件和`keyboardWillHide`键盘将要隐藏事件功能，这些API需要在支持`API20+`的工程编译，并在支持`API20+`的ROM上运行，方可生效。
 
 ## 使用示例
 
@@ -299,11 +300,13 @@ export default App;
 |  useKeyboardHandler  |  设置键盘回调事件的钩子函数   | `(handler: KeyboardHandler, deps?: DependencyList) => void` | no | iOS,Android      | yes |
 |  useKeyboardController  |  设置是否启动键盘监听事件的钩子函数   | `() => { setEnabled: React.Dispatch<React.SetStateAction<boolean>>; enabled: boolean }` | no | iOS,Android      | yes |
 |  useFocusedInputHandler  | 设置监听输入框回调事件的钩子函数(HarmonyOS暂支持文本变化的监听)   | `(handler?: FocusedInputHandler, deps?: DependencyList) => void` | no | iOS,Android      | partially |
-|  useReanimatedFocusedInput  | 当前聚焦的输入控件文本变化事件回调的钩子函数  | `() => { input: SharedValue<FocusedInputLayoutChangedEvent \| null> }` | no | iOS,Android      |no |
+|  useReanimatedFocusedInput  | 当前聚焦的输入控件文本变化事件回调的钩子函数，update()用于主动同步当前聚焦输入框布局 | `() => { input: SharedValue<FocusedInputLayoutChangedEvent \| null>; update: () => Promise<void> }` | no | iOS,Android      |yes |
+|  useKeyboardState(selector?)  | 响应式读取完整键盘状态；传入selector时仅订阅并返回所需字段  | `<T>(selector?: (state: IKeyboardState) => T) => T` | no | iOS,Android      | yes |
+|  useAnimatedKeyboard()  | 返回键盘高度和状态对应的SharedValue  | `() => { height: SharedValue<number>; state: SharedValue<number> }` | no | iOS,Android      | yes |
 |  useResizeMode  | 组件挂载时将 Android 输入模式设置为 `adjustResize`，卸载时恢复默认模式 | `() => void` | no | Android | no |
 |  useGenericKeyboardHandler  | 注册键盘生命周期回调，不修改 Android 输入模式；HarmonyOS 原生仅支持 `onEnd`，`onStart`、`onMove` 不是原生事件，`onInteractive` 不支持 | `(handler: KeyboardHandler, deps?: DependencyList) => void` | no | iOS,Android | partially |
-|  useWindowDimensions  | 读取并监听窗口宽高变化，使用 React Native 通用实现 | `() => ScaledSize` | no | iOS,Android | yes |
-|  useKeyboardContext  | 读取键盘动画上下文，用于构建自定义 Hook；必须在 `KeyboardProvider` 内调用 | `() => KeyboardAnimationContext` | no | iOS,Android | yes |
+|  useWindowDimensions  | 使用 React Native 通用实现读取并监听窗口宽高变化 | `() => ScaledSize` | no | iOS,Android | yes |
+|  useKeyboardContext  | 读取 `KeyboardProvider` 提供的键盘上下文，用于构建自定义 Hook；建议业务优先使用上层 Hooks | `() => KeyboardAnimationContext` | no | iOS,Android | yes |
 
 **KeyboardController**：键盘控制器
 
@@ -311,32 +314,49 @@ export default App;
 | ---- | ----------- | ---- | -------- | -------- | ------------------ |
 |  setInputMode(mode: number): void  | 设置键盘显示默认模式   | function   | no | Android      | no |
 |  setDefaultMode(): void  | 设置键盘显示默认模式   | function   | no | Android      | no |
-| dismiss(options?: DismissOptions): Promise<void> | 设置键盘隐藏。`DismissOptions` 为 `{ keepFocus: boolean }`，用于指定隐藏键盘时是否保持输入框焦点。HarmonyOS 可以隐藏键盘；由于 HarmonyOS 缺少保持聚焦输入框的相关能力，`keepFocus` 参数暂不支持。 | `Promise<void>` | no | iOS,Android | partially |
-| setFocusTo(direction: "next" \| "prev" \| "current"): void | 设置聚焦的方式   | function   | no | iOS,Android      | no |
+| dismiss(options?: Partial&lt;DismissOptions&gt;): Promise&lt;void&gt; | 设置键盘隐藏。`DismissOptions` 包含 `keepFocus` 和 `animated`。HarmonyOS 可以隐藏键盘；由于 HarmonyOS 缺少保持聚焦输入框的相关能力，`keepFocus` 参数暂不支持；同时不支持无动画关闭键盘。 | `Promise<void>` | no | iOS,Android | partially |
+| setFocusTo(direction: "next" \| "prev" \| "current"): void | 将焦点移动到下一个、上一个或当前输入框；HarmonyOS 支持 `next`/`prev`，`current` 尚不支持 | function | no | iOS,Android | no |
 | addListener: (eventName: string) => void  | 添加键盘的监听事件   |  function  | no | iOS,Android      | yes |
 |   removeListeners: (count: number) => void | 删除键盘的监听事件   |  function  | no | iOS,Android      | yes |
 | isVisible(): boolean | 返回键盘是否可见   |  function  | no | iOS,Android      | yes |
-| state(): KeyboardEventData \| null | 返回键盘最后的状态，如果键盘还没有显示过返回 `null` | function | no       | iOS,Android | yes               |
+| state(): KeyboardEventData | 返回键盘最后的状态 | function | no       | iOS,Android | yes               |
+| preload(): void | 预加载键盘以减少首次聚焦时的延迟 | function | no | iOS | no |
 
-**AndroidSoftInputModes**：Android `windowSoftInputMode` 的公共枚举，用于向 `setInputMode` 传入输入法窗口调整模式。该枚举对应 Android `WindowManager.LayoutParams`，HarmonyOS 不适用。
+**AndroidSoftInputModes**：Android `windowSoftInputMode` 的公共枚举，用于向 `setInputMode` 传入输入法窗口调整模式。HarmonyOS 不适用。
 
 | Name | Value | Description | Platform | HarmonyOS Support |
 | ---- | ----- | ----------- | -------- | ----------------- |
 | `SOFT_INPUT_ADJUST_NOTHING` | 48 | 键盘显示时不调整窗口 | Android | no |
-| `SOFT_INPUT_ADJUST_PAN` | 32 | 键盘显示时平移窗口，避免焦点输入框被遮挡 | Android | no |
+| `SOFT_INPUT_ADJUST_PAN` | 32 | 键盘显示时平移窗口 | Android | no |
 | `SOFT_INPUT_ADJUST_RESIZE` | 16 | 键盘显示时调整窗口可用区域大小 | Android | no |
 | `SOFT_INPUT_ADJUST_UNSPECIFIED` | 0 | 由系统自动选择窗口调整方式 | Android | no |
 | `SOFT_INPUT_IS_FORWARD_NAVIGATION` | 256 | 表示窗口由向前导航进入 | Android | no |
-| `SOFT_INPUT_MASK_ADJUST` | 240 | 获取窗口调整方式的位掩码 | Android | no |
-| `SOFT_INPUT_MASK_STATE` | 15 | 获取键盘初始显示状态的位掩码 | Android | no |
-| `SOFT_INPUT_MODE_CHANGED` | 512 | 表示输入模式已经发生变化 | Android | no |
+| `SOFT_INPUT_MASK_ADJUST` | 240 | 窗口调整方式的位掩码 | Android | no |
+| `SOFT_INPUT_MASK_STATE` | 15 | 键盘初始状态的位掩码 | Android | no |
+| `SOFT_INPUT_MODE_CHANGED` | 512 | 表示输入模式已经变化 | Android | no |
 | `SOFT_INPUT_STATE_ALWAYS_HIDDEN` | 3 | 窗口获得焦点时始终隐藏键盘 | Android | no |
 | `SOFT_INPUT_STATE_ALWAYS_VISIBLE` | 5 | 窗口获得焦点时始终显示键盘 | Android | no |
 | `SOFT_INPUT_STATE_HIDDEN` | 2 | 窗口获得焦点时隐藏键盘 | Android | no |
 | `SOFT_INPUT_STATE_UNCHANGED` | 1 | 保持键盘当前显示状态 | Android | no |
-| `SOFT_INPUT_STATE_UNSPECIFIED` | 0 | 未指定键盘初始显示状态，由系统决定 | Android | no |
+| `SOFT_INPUT_STATE_UNSPECIFIED` | 0 | 由系统决定键盘初始显示状态 | Android | no |
 | `SOFT_INPUT_STATE_VISIBLE` | 4 | 窗口获得焦点时显示键盘 | Android | no |
 
+**KeyboardState**：`useAnimatedKeyboard()` 使用的键盘状态常量。
+
+| Name | Value | Description | HarmonyOS Support |
+| ---- | ----- | ----------- | ----------------- |
+| `UNKNOWN` | 0 | 键盘状态未知 | yes |
+| `OPENING` | 1 | 键盘正在打开 | yes |
+| `OPEN` | 2 | 键盘已经打开 | yes |
+| `CLOSING` | 3 | 键盘正在关闭 | yes |
+| `CLOSED` | 4 | 键盘已经关闭 | yes |
+
+**公共常量**
+
+| Name | Description | Type | Platform | HarmonyOS Support |
+| ---- | ----------- | ---- | -------- | ----------------- |
+| `KEYBOARD_BORDER_RADIUS` | 键盘圆角半径；Android、iOS 26 以下及 iOS 26+ 兼容模式返回 `0`，iOS 26+ 新式键盘返回 `30`；HarmonyOS 与 Android 一致返回 `0` | number | iOS,Android | yes |
+
 **StatusBarManagerCompat**：状态栏控制器
 
 | Name | Description | Type | Required | Platform | HarmonyOS Support  |
@@ -374,13 +394,14 @@ export default App;
 
 **KeyboardProvider**：为子组件提供键盘监听、动画状态及运行时控制上下文。其 `KeyboardProviderProps` 类型包含以下属性。
 
-| Name | Description | Type | Required | Platform | HarmonyOS Support  |
-| ---- | ----------- | ---- | -------- | -------- | ------------------ |
+| Name | Description | Type | Required | Platform | HarmonyOS Support |
+| ---- | ----------- | ---- | -------- | -------- | ----------------- |
 | `children` | Provider 包裹的子组件 | `React.ReactNode` | yes | iOS,Android | yes |
-| `enabled` | 是否在初始化时开启键盘监听，运行时切换请使用 `useKeyboardController().setEnabled()`，默认值为 `true` | boolean | no | iOS,Android | yes |
+| `enabled` | 是否在初始化时开启键盘监听，默认值为 `true` | boolean | no | iOS,Android | yes |
 | `statusBarTranslucent` | 是否使用透明状态栏，默认值为 `false` | boolean | no | Android | no |
 | `navigationBarTranslucent` | 是否使用透明导航栏，默认值为 `false` | boolean | no | Android | no |
 | `preserveEdgeToEdge` | 是否始终保持 edge-to-edge 模式，默认值为 `false` | boolean | no | Android | yes |
+| `preload` | 是否预加载键盘以减少首次聚焦延迟，默认值为 `true`； | boolean | no | iOS | no |
 
 **KeyboardControllerView**：键盘控制器
 
@@ -406,7 +427,7 @@ export default App;
 | ---- | ----------- | ---- | -------- | -------- | ------------------ |
 |  showOnSwipeUp  | 键盘随手势向上滑动显示    | boolean   | no | Android      | no |
 |  enableSwipeToDismiss  | 键盘随手势向下滑动隐藏   | boolean   | no | Android      | no |
-|  interpolator  | 设置键盘随手势滑动的动画模式    | ios / linear | no | Android      | no |
+|  interpolator  | 设置键盘随手势滑动的动画模式    | `"ios" \| "linear"` | no | Android      | no |
 |  offset  | 到键盘的额外距离    | number | no | iOS、Android      | no |
 |  textInputNativeID  | TextInput对应的nativeID    | string | no | iOS      | no |
 
@@ -418,6 +439,7 @@ export default App;
 |  contentContainerStyle  | 当`behavior`为position时，内容容器的样式   | [ ViewStyle ](https://reactnative.dev/docs/view#props)   | no | iOS,Android       | yes |
 |  enabled  | 控制这个`KeyboardAvoidingView`实例是否应该生效,默认为true  | boolean   | no | iOS,Android       | yes |
 |  keyboardVerticalOffset  | 键盘与React Native视图之间的距离,默认为`0`   | number  | no | iOS,Android      | yes |
+|  automaticOffset  | 是否自动测量组件在窗口中的坐标并参与键盘避让，默认为`false`   | boolean  | no | iOS,Android      | yes |
 |  onLayout  |  在安装和布局更改时的回调函数(event: LayoutChangeEvent) => void   | function/undefined   | no | iOS,Android      | yes |
 |  style  | `KeyboardAvoidingView`的CSS属性    | [ ViewStyle ](https://reactnative.dev/docs/view#props)   | no | iOS,Android      | yes |
 |  children  |  JSX element 子组件   | JSX.Element   | no | iOS,Android      | yes |
@@ -430,10 +452,27 @@ export default App;
 |  enabled  | 控制此`KeyboardAwareScrollView`实例是否应生效。默认值为`true`  | boolean   | no | iOS,Android       | yes |
 |  disableScrollOnKeyboardHide  |防止键盘隐藏时`ScrollView`自动滚动，保持当前屏幕位置。默认值为`false`。  | boolean   | no | iOS,Android       | no |
 |  extraKeyboardSpace  | KeyboardAwareScrollView的底部间距,默认为0   | number  | no | iOS,Android      | no |
+|  mode  | 选择使用`insets`或`layout`方式创建键盘空间，默认为`insets`   | "insets" / "layout"  | no | iOS,Android      | no |
+|  assureFocusedInputVisible()  | 主动重新执行当前聚焦输入框的避让   | function  | no | iOS,Android      | no |
 |  onLayout  |  在安装和布局更改时的回调函数(event: LayoutChangeEvent) => void   | function/undefined   | no | iOS,Android      | yes |
 |  style  | `KeyboardAwareScrollView`的CSS属性    | [ ViewStyle ](https://reactnative.dev/docs/view#props)   | no | iOS,Android      | yes |
 |  children  |  JSX element 子组件   | JSX.Element  | no | iOS,Android      | yes |
-|  ScrollViewComponent  |  ScrollView的自定义组件   | React.ComponentType<ScrollViewProps>  | no | iOS,Android      | yes |
+|  ScrollViewComponent |  ScrollView的自定义组件   | React.ComponentType<ScrollViewProps>  | no | iOS,Android      | yes |
+
+**KeyboardChatScrollView**：面向聊天场景的键盘感知滚动容器组件，用于在键盘显示或隐藏时联动调整消息列表的底部空间和滚动位置
+
+| Name | Description | Type | Required | Platform | HarmonyOS Support  |
+| ---- | ----------- | ---- | -------- | -------- | ------------------ |
+|  ScrollViewComponent  | 注入自定义动画`ScrollView`实现，默认使用`Reanimated.ScrollView`   | AnimatedScrollViewComponent   | no | iOS,Android      | yes |
+|  inverted  | 是否使用反转列表方向，默认为`false`   | boolean   | no | iOS,Android      | yes |
+|  offset  | `ScrollView`底部与屏幕底部之间的距离；键盘弹起时按键盘高度减去该距离计算有效抬升量，默认为`0`   | number   | no | iOS,Android      | yes |
+|  keyboardLiftBehavior  | 设置键盘弹起时消息列表的抬升策略，默认为`always`。   | "always" / "whenAtEnd" / "persistent" / "never"   | no | iOS,Android      | yes |
+|  freeze  | 冻结键盘驱动的padding、offset和滚动更新，默认为`false`   | boolean / SharedValue&lt;boolean&gt;   | no | iOS,Android      | yes |
+|  extraContentPadding  | 外部元素产生的动态额外内容边距   | SharedValue&lt;number&gt;   | no | iOS,Android      | no |
+|  blankSpace  | 设置内容的最小inset空间，键盘空间和额外边距不会使总边距低于该值   | SharedValue&lt;number&gt;   | no | iOS,Android      | no |
+|  applyWorkaroundForContentInsetHitTestBug  | iOS `contentInset`触摸问题的兼容开关，默认为`false`   | boolean   | no | iOS      | no |
+|  onContentInsetChange  | 内容inset发生变化时的回调函数(insets) => void   | function   | no | iOS,Android      | no |
+|  onEndVisible  | 内容末端进入或离开可见区域时的回调函数(visible: boolean) => void   | function   | no | iOS,Android      | no |
 
 **KeyboardStickyView**：随键盘移动的粘性视图组件
 
@@ -459,9 +498,43 @@ export default App;
 |  showArrows  |  是否显示下一个和上一个按钮  | boolean   | no | iOS,Android      | yes |
 |  blur  |  工具栏聚焦时标题组件   | JSX.Element    | no | iOS,Android      | yes |
 |  opacity  |  十六进制格式的容器不透明度值（例如`ff`）。默认值为`ff`   | HEX   | no | iOS,Android      | yes |
-| onNextCallback?: () => void | 当用户按下“下一步”按钮时调用的回调以及默认操作；HarmonyOS 为无参回调，不支持 `event.preventDefault()`。 | function | no | iOS,Android | yes |
-| onPrevCallback?: () => void | 用户按下“上一步”按钮时调用的回调以及默认操作；HarmonyOS 为无参回调，不支持 `event.preventDefault()`。 | function | no | iOS,Android | yes |
-| onDoneCallback?: () => void | 当用户按下“完成”按钮时调用的回调以及默认操作；HarmonyOS 为无参回调，不支持 `event.preventDefault()`。 | function | no | iOS,Android | yes |
+| onNextCallback?: (event: GestureResponderEvent) => void | 当用户按下“下一步”按钮时调用的回调以及默认操作。  | `(event: GestureResponderEvent) => void` | no | iOS,Android      | yes |
+| onPrevCallback?: (event: GestureResponderEvent) => void | 用户按下“上一步”按钮时调用的回调以及默认操作。  | `(event: GestureResponderEvent) => void` | no | iOS,Android      | yes |
+| onDoneCallback?: (event: GestureResponderEvent) => void | 当用户按下“完成”按钮时调用的回调以及默认操作。  | `(event: GestureResponderEvent) => void` | no | iOS,Android      | yes |
+|  insets  | 工具栏左右两侧的安全区域边距   | {left: number;right: number;}   | no | iOS,Android      | yes |
+|  children  | 组合式Toolbar的JSX子组件入口   | React.ReactNode   | no | iOS,Android      | yes |
+
+**KeyboardToolbar Compound**：`KeyboardToolbar`的组合式API，通过静态子组件分别定义背景、中间内容和操作按钮。
+
+`KeyboardToolbar.Background`、`KeyboardToolbar.Content`、`KeyboardToolbar.Prev`、`KeyboardToolbar.Next`和`KeyboardToolbar.Done`需要作为`KeyboardToolbar`的直接子组件。
+
+| Name | Description | Type | Required | Platform | HarmonyOS Support  |
+| ---- | ----------- | ---- | -------- | -------- | ------------------ |
+|  KeyboardToolbar.Background  | 设置工具栏背景内容，`children`为必选   | React.FC&lt;{children: React.ReactNode;}&gt;   | no | iOS,Android      | yes |
+|  KeyboardToolbar.Content  | 设置工具栏中间的内容区域   | React.FC&lt;ViewProps &amp; {children?: React.ReactNode;}&gt;   | no | iOS,Android      | yes |
+|  KeyboardToolbar.Prev  | 上一个输入框按钮；   | React.FC&lt;ButtonSubProps&gt;   | no | iOS,Android      | yes |
+|  KeyboardToolbar.Next  | 下一个输入框按钮；   | React.FC&lt;ButtonSubProps&gt;   | no | iOS,Android      | yes |
+|  KeyboardToolbar.Done  | 隐藏键盘按钮；   | React.FC&lt;Omit&lt;ButtonSubProps, "icon"&gt; &amp; {text?: React.ReactNode;}&gt;   | no | iOS,Android      | yes |
+
+**KeyboardToolbar.Group**：输入框分组组件。该组件作为`KeyboardToolbar`的静态成员导出，但不属于Compound内容组件；应包裹需要分组的输入框，限定Prev/Next按钮仅在当前分组内遍历。
+
+| Name | Description | Type | Required | Platform | HarmonyOS Support  |
+| ---- | ----------- | ---- | -------- | -------- | ------------------ |
+|  KeyboardToolbar.Group  | 包裹一组需要限制焦点遍历范围的输入框   | React.FC&lt;KeyboardToolbarGroupViewProps&gt;   | no | iOS,Android      | yes |
+
+**KeyboardBackgroundView**：匹配键盘区域背景的视图组件
+
+| Name | Description | Type | Required | Platform | HarmonyOS Support  |
+| ---- | ----------- | ---- | -------- | -------- | ------------------ |
+|  KeyboardBackgroundView  | 匹配键盘区域的背景视图   | React.FC&lt;KeyboardBackgroundViewProps&gt;   | no | iOS,Android      | no |
+
+**KeyboardExtender**：将子内容附着到键盘区域，并显示在键盘系统按钮上方的容器组件
+
+| Name | Description | Type | Required | Platform | HarmonyOS Support  |
+| ---- | ----------- | ---- | -------- | -------- | ------------------ |
+|  KeyboardExtender  | 将子内容附着到键盘区域，并显示在键盘系统按钮上方   | React.FC&lt;KeyboardExtenderProps&gt;   | no | iOS,Android      | yes |
+|  enabled  | 控制扩展区域是否跟随键盘生效，默认为`true`   | boolean   | no | iOS,Android      | yes |
+|  children  | JSX element 子组件   | JSX.Element   | no | iOS,Android      | yes |
 
 **OverKeyboardView**：覆盖在键盘上的容器组件
 
@@ -473,11 +546,14 @@ export default App;
 
 - [ ] 暂不支持KeyboardControllerView中onKeyboardMoveStart，onKeyboardMove，onKeyboardMoveInteractive事件的回调：[ issue#1 ](https://github.com/react-native-oh-library/react-native-keyboard-controller/issues/1)
 - [ ] 暂不支持KeyboardGestureArea组件：[issue#2 ](https://github.com/react-native-oh-library/react-native-keyboard-controller/issues/2)
-- [ ] 暂不支持hook方法useReanimatedFocusedInput，KeyboardController中setFocusTo，FocusedInputEvents中focusDidSet：[issue#3 ](https://github.com/react-native-oh-library/react-native-keyboard-controller/issues/3)
+- [ ] 暂不支持KeyboardController中setFocusTo，FocusedInputEvents中focusDidSet：[issue#3 ](https://github.com/react-native-oh-library/react-native-keyboard-controller/issues/3)
 - [ ] 暂不支持KeyboardAwareScrollView组件属性disableScrollOnKeyboardHide、extraKeyboardSpace的设置[#issue#16](https://github.com/react-native-oh-library/react-native-keyboard-controller/issues/16)
 - [ ] KeyboardControllerView中onFocusedInputSelectionChanged事件部分支持，HarmonyOS暂支持选区的position，选区坐标默认为0：[issue#13](https://github.com/react-native-oh-library/react-native-keyboard-controller/issues/13)
 - [ ] KeyboardAvoidingView属性behavior支持position， 不支持高度height、padding的样式[#issue#13](https://github.com/react-native-oh-library/react-native-harmony-reanimated/issues/13)
 - [ ] 暂不支持OverKeyboardView接口：[issue#27](https://github.com/react-native-oh-library/react-native-keyboard-controller/issues/27)
+- [ ] 暂不支持KeyboardChatScrollView的onEndVisible、onContentInsetChange回调以及extraContentPadding、blankSpace属性
+- [ ] 暂不支持KeyboardAwareScrollView Ref的assureFocusedInputVisible()方法和mode属性
+- [ ] 暂不支持KeyboardBackgroundView组件
 - [ ] 暂不支持 Hook 方法 `useResizeMode`。
 - [ ] Hook 方法 `useGenericKeyboardHandler` 部分支持：HarmonyOS 原生仅支持 `onEnd`，`onStart`、`onMove` 不是原生事件，`onInteractive` 不支持。
 - [ ] 暂不支持 `KeyboardProvider` 的 `statusBarTranslucent` 和 `navigationBarTranslucent` 属性。

package/harmony/keyboard_controller/BuildProfile.ets

@@ -1,7 +1,7 @@
 /**
  * Use these variables when you tailor your ArkTS code. They must be of the const type.
  */
-export const HAR_VERSION = '1.16.8';
+export const HAR_VERSION = '1.17.0';
 export const BUILD_MODE_NAME = 'debug';
 export const DEBUG = true;
 export const TARGET_NAME = 'default';

package/harmony/keyboard_controller/Index.ets

@@ -26,3 +26,4 @@
  */
 
 export * from './ts';
+export { RNKeyboardControllerPackage as default } from './src/main/ets/RNKeyboardControllerPackage';

package/harmony/keyboard_controller/oh-package-lock.json5

@@ -5,24 +5,24 @@
   "lockfileVersion": 3,
   "ATTENTION": "THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.",
   "specifiers": {
-    "@ppd/ffrt@1.1.10": "@ppd/ffrt@1.1.10",
+    "@ppd/ffrt@1.1.5": "@ppd/ffrt@1.1.5",
     "@rnoh/react-native-openharmony@../../example/node_modules/react-native-harmony/react_native_openharmony.har": "@rnoh/react-native-openharmony@../../example/node_modules/react-native-harmony/react_native_openharmony.har"
   },
   "packages": {
-    "@ppd/ffrt@1.1.10": {
+    "@ppd/ffrt@1.1.5": {
       "name": "@ppd/ffrt",
-      "version": "1.1.10",
-      "integrity": "sha512-hRV0R2dKn9nqcOHhya5jRrTMoB51icGRNXem+WGJOKQdByXaEpI8NGT2BNjlR1Zf6zquQ2jxtsnSMzB88mbF7Q==",
-      "resolved": "https://ohpm.openharmony.cn/ohpm/@ppd/ffrt/-/ffrt-1.1.10.har",
+      "version": "1.1.5",
+      "integrity": "sha512-MbXdRqeNHQQv4ALTGdosvOCQI+xH8nt0+E2/aFLS4UuGJ5541MAeenRCDOrgIG05k7SnSJ4WngsCfjj3FbTCQg==",
+      "resolved": "https://ohpm.openharmony.cn/ohpm/@ppd/ffrt/-/ffrt-1.1.5.har",
       "registryType": "ohpm"
     },
     "@rnoh/react-native-openharmony@../../example/node_modules/react-native-harmony/react_native_openharmony.har": {
       "name": "@rnoh/react-native-openharmony",
-      "version": "0.77.74",
+      "version": "0.82.23",
       "resolved": "../../example/node_modules/react-native-harmony/react_native_openharmony.har",
       "registryType": "local",
       "dependencies": {
-        "@ppd/ffrt": "1.1.10"
+        "@ppd/ffrt": "1.1.5"
       }
     }
   }

package/harmony/keyboard_controller/oh-package.json5

@@ -1,6 +1,6 @@
 {
   "name": "@react-native-ohos/react-native-keyboard-controller",
-  "version": "1.16.8",
+  "version": "1.17.0",
   "description": " control keyboard show or hide",
   "main": "Index.ets",
   "author": "",

package/harmony/keyboard_controller/src/main/cpp/ClippingScrollViewComponentDescriptor.h

@@ -0,0 +1,86 @@
+/*
+ * Copyright (c) Huawei Technologies Co., Ltd. 2020-2020. All rights reserved.
+ */
+/**
+ * MIT License
+ *
+ * Copyright (C) 2026 Huawei Device Co., Ltd.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+#ifndef CLIPPINGSCROLLVIEWCOMPONENTDESCRIPTOR_H
+#define CLIPPINGSCROLLVIEWCOMPONENTDESCRIPTOR_H
+
+#pragma once
+
+#include <react/renderer/core/ConcreteComponentDescriptor.h>
+#include <react/renderer/components/view/ConcreteViewShadowNode.h>
+#include <react/renderer/components/view/ViewShadowNode.h>
+#include <react/renderer/core/propsConversions.h>
+
+namespace facebook {
+namespace react {
+
+inline const char ClippingScrollViewDecoratorViewComponentName[] =
+    "ClippingScrollViewDecoratorView";
+
+class ClippingScrollViewDecoratorViewProps : public ViewProps {
+public:
+    Float contentInsetBottom;
+    Float contentInsetTop;
+    bool applyWorkaroundForContentInsetHitTestBug;
+
+    ClippingScrollViewDecoratorViewProps() = default;
+
+    ClippingScrollViewDecoratorViewProps(
+        const PropsParserContext &context,
+        const ClippingScrollViewDecoratorViewProps &sourceProps,
+        const RawProps &rawProps)
+        : ViewProps(context, sourceProps, rawProps),
+          contentInsetBottom(convertRawProp(
+              context, rawProps, "contentInsetBottom",
+              sourceProps.contentInsetBottom, {0.0})),
+          contentInsetTop(convertRawProp(
+              context, rawProps, "contentInsetTop",
+              sourceProps.contentInsetTop, {0.0})),
+          applyWorkaroundForContentInsetHitTestBug(convertRawProp(
+              context, rawProps,
+              "applyWorkaroundForContentInsetHitTestBug",
+              sourceProps.applyWorkaroundForContentInsetHitTestBug, {false})) {}
+};
+
+using ClippingScrollViewDecoratorViewShadowNode =
+    ConcreteViewShadowNode<ClippingScrollViewDecoratorViewComponentName,
+                           ClippingScrollViewDecoratorViewProps,
+                           ViewEventEmitter>;
+
+class ClippingScrollViewDecoratorViewComponentDescriptor final
+    : public ConcreteComponentDescriptor<
+          ClippingScrollViewDecoratorViewShadowNode> {
+public:
+    ClippingScrollViewDecoratorViewComponentDescriptor(
+        ComponentDescriptorParameters const &parameters)
+        : ConcreteComponentDescriptor(parameters) {}
+};
+
+} // namespace react
+} // namespace facebook
+
+#endif

package/harmony/keyboard_controller/src/main/cpp/ClippingScrollViewComponentInstance.cpp

@@ -0,0 +1,104 @@
+/*
+ * Copyright (c) Huawei Technologies Co., Ltd. 2020-2020. All rights reserved.
+ */
+/**
+ * MIT License
+ *
+ * Copyright (C) 2026 Huawei Device Co., Ltd.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+#include "ClippingScrollViewComponentInstance.h"
+#include "RNOHCorePackage/ComponentInstances/ScrollViewComponentInstance.h"
+#include "glog/logging.h"
+
+namespace rnoh {
+
+ClippingScrollViewComponentInstance::ClippingScrollViewComponentInstance(
+    Context context)
+    : CppComponentInstance(std::move(context)) {
+    DLOG(INFO) << "[ClippingScrollView] constructed tag=" << this->getTag();
+    m_stackNode.setClip(true);
+    m_stackNode.setHitTestMode(ARKUI_HIT_TEST_MODE_DEFAULT);
+}
+
+void ClippingScrollViewComponentInstance::onChildInserted(
+    ComponentInstance::Shared const &childComponentInstance,
+    std::size_t index) {
+    DLOG(INFO) << "[ClippingScrollView] onChildInserted index=" << index
+               << " child=" << childComponentInstance->getComponentName();
+    CppComponentInstance::onChildInserted(childComponentInstance, index);
+    m_stackNode.insertChild(childComponentInstance->getLocalRootArkUINode(), index);
+    
+    if (childComponentInstance->getComponentName() == "ScrollView") {
+        m_scrollViewChild =
+            std::dynamic_pointer_cast<ScrollViewComponentInstance>(childComponentInstance);
+        DLOG(INFO) << "[ClippingScrollView] captured ScrollView child tag="
+                   << childComponentInstance->getTag();
+        applyInsets();
+    }
+}
+
+void ClippingScrollViewComponentInstance::onChildRemoved(
+    ComponentInstance::Shared const &childComponentInstance) {
+    CppComponentInstance::onChildRemoved(childComponentInstance);
+    m_stackNode.removeChild(childComponentInstance->getLocalRootArkUINode());
+}
+
+void ClippingScrollViewComponentInstance::onPropsChanged(
+    SharedConcreteProps const &props) {
+    CppComponentInstance::onPropsChanged(props);
+    m_contentInsetTop = props->contentInsetTop;
+    m_contentInsetBottom = props->contentInsetBottom;
+    m_applyHitTestWorkaround = props->applyWorkaroundForContentInsetHitTestBug;
+    DLOG(INFO) << "[ClippingScrollView] onPropsChanged tag=" << this->getTag()
+               << " insetTop=" << m_contentInsetTop
+               << " insetBottom=" << m_contentInsetBottom
+               << " workaround=" << m_applyHitTestWorkaround;
+    applyInsets();
+}
+
+void ClippingScrollViewComponentInstance::applyInsets() {
+    auto scrollView = m_scrollViewChild.lock();
+    if (scrollView) {
+        auto &scrollNode = scrollView->getLocalRootArkUINode();
+        scrollNode.setEdgeEffect(false, false);
+        scrollNode.setScrollOverScrollMode("never");
+        DLOG(INFO) << "[ClippingScrollView] applied insets to ScrollView tag="
+                   << scrollView->getTag()
+                   << " top=" << m_contentInsetTop
+                   << " bottom=" << (m_contentInsetBottom + m_contentInsetTop);
+    } else {
+        m_stackNode.setPadding(
+            0.0f,
+            static_cast<float>(m_contentInsetTop),
+            0.0f,
+            static_cast<float>(m_contentInsetBottom));
+    }
+
+    m_stackNode.setClip(true);
+    m_stackNode.setHitTestMode(ARKUI_HIT_TEST_MODE_DEFAULT);
+}
+
+ArkUINode &ClippingScrollViewComponentInstance::getLocalRootArkUINode() {
+    return m_stackNode;
+}
+
+} // namespace rnoh

package/harmony/keyboard_controller/src/main/cpp/ClippingScrollViewComponentInstance.h

@@ -0,0 +1,64 @@
+/*
+ * Copyright (c) Huawei Technologies Co., Ltd. 2020-2020. All rights reserved.
+ */
+/**
+ * MIT License
+ *
+ * Copyright (C) 2026 Huawei Device Co., Ltd.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+#ifndef CLIPPINGSCROLLVIEWCOMPONENTINSTANCE_H
+#define CLIPPINGSCROLLVIEWCOMPONENTINSTANCE_H
+
+#pragma once
+
+#include "ClippingScrollViewComponentDescriptor.h"
+#include "RNOH/CppComponentInstance.h"
+#include "RNOH/arkui/StackNode.h"
+
+namespace rnoh {
+
+class ScrollViewComponentInstance;
+
+class ClippingScrollViewComponentInstance
+    : public CppComponentInstance<
+          facebook::react::ClippingScrollViewDecoratorViewShadowNode> {
+public:
+    explicit ClippingScrollViewComponentInstance(Context context);
+
+    void onChildInserted(ComponentInstance::Shared const &childComponentInstance,
+                         std::size_t index) override;
+    void onChildRemoved(ComponentInstance::Shared const &childComponentInstance) override;
+    void onPropsChanged(SharedConcreteProps const &props) override;
+    ArkUINode &getLocalRootArkUINode() override;
+
+private:
+    void applyInsets();
+
+    StackNode m_stackNode;
+    std::weak_ptr<ScrollViewComponentInstance> m_scrollViewChild;
+    facebook::react::Float m_contentInsetTop = 0.0;
+    facebook::react::Float m_contentInsetBottom = 0.0;
+    bool m_applyHitTestWorkaround = false;
+};
+
+} // namespace rnoh
+
+#endif