@react-native-ohos/react-native-keyboard-controller 1.17.0-beta.2 → 1.17.0

package/README.md

@@ -1,19 +1,686 @@
-# @react-native-ohos/react-native-keyboard-controller
-
-本项目基于 [react-native-keyboard-controller@v1.16.5](https://github.com/kirillzyusko/react-native-keyboard-controller/tree/1.16.5)
-
-## 文档地址 / Documentation URL 
-
-[中文 / Chinese](https://gitcode.com/OpenHarmony-RN/usage-docs/blob/master/zh-cn/react-native-keyboard-controller.md)
-
-[英文 / English](https://gitcode.com/OpenHarmony-RN/usage-docs/blob/master/en/react-native-keyboard-controller.md)
-
-## Codegen
-
-该库已接入 codegen，具体请查阅文档。
-
-The library has been integrated with codegen. Please refer to the documentation for details.
-
-## 请悉知 / Acknowledgements
-
-本项目基于 [The MIT License (MIT)](https://github.com/kirillzyusko/react-native-keyboard-controller/blob/main/LICENSE) ，请自由地享受和参与开源。
+> 文档模板：v0.4.2
+
+<p align="center">
+  <h1 align="center"> <code>react-native-keyboard-controller</code> </h1>
+</p>
+
+本项目基于 [react-native-keyboard-controller](https://github.com/kirillzyusko/react-native-keyboard-controller) 开发。
+
+该第三方库的仓库已迁移至 Gitcode，且支持直接从 npm 下载，新的包名为：`@react-native-ohos/react-native-keyboard-controller`。版本所属关系如下：
+
+| 三方库名称 | 三方库版本（npm地址） | 发布信息 | 支持RN版本 | Autolink | 编译API版本 | 社区基线版本 | 源码地址 |
+| ---------- | --------------------- | -------- | ---------- | -------- | ----------- | ------------ | -------- |
+| @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) |
+
+## 简介
+
+React Native 生态中用于精细控制键盘行为的增强库。<br/>
+核心功能是解决原生键盘交互的局限性，提供键盘弹出/收起的动画联动、高度监听、自定义工具栏及键盘避让等能力！<br/>
+帮助开发者轻松构建流畅、无缝的键盘联动输入体验。
+
+## 下载安装
+
+进入到工程目录并输入以下命令：
+
+<!-- tabs:start -->
+
+#### **npm**
+
+```bash
+npm install @react-native-ohos/react-native-keyboard-controller
+```
+
+#### **yarn**
+
+```bash
+yarn add @react-native-ohos/react-native-keyboard-controller
+```
+<!-- tabs:end -->
+
+另外本库依赖三方库[react-native-reanimated](https://gitcode.com/CPF-RN/rntpc_react-native-reanimated)，请按照[react-native-reanimated指导文档](https://gitcode.com/OpenHarmony-RN/usage-docs/blob/master/zh-cn/react-native-reanimated.md)引入此依赖库。
+
+## Link
+
+|                               | 是否支持autolink  | RN框架版本 |
+|-------------------------------|------------------|-----------|
+| ~ 1.17.0                   |  Yes           |  0.82  |
+
+<details>
+  <summary>ManualLink: 此步骤为手动配置原生依赖项的指导</summary>
+
+首先需要使用 DevEco Studio 打开项目里的 HarmonyOS 工程 `harmony`。
+
+### 在工程根目录的 `oh-package.json5` 添加 overrides 字段
+
+为了让工程依赖同一个版本的 RN SDK，需要在工程根目录的 `oh-package.json5` 添加 overrides 字段，指向工程需要使用的 RN SDK 版本。替换的版本既可以是一个具体的版本号，也可以是一个模糊版本，还可以是本地存在的 HAR 包或源码目录。
+
+关于该字段的作用请阅读[官方说明](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/ide-oh-package-json5-V5#zh-cn_topic_0000001792256137_overrides)
+
+```json
+{
+  "overrides": {
+    "@rnoh/react-native-openharmony": "^0.82.1" // ohpm 在线版本
+    // "@rnoh/react-native-openharmony" : "./react_native_openharmony.har" // 指向本地 har 包的路径
+    // "@rnoh/react-native-openharmony" : "./react_native_openharmony" // 指向源码路径
+  }
+}
+```
+
+### 引入原生端代码
+
+目前有两种方法：
+
+1. 通过 har 包引入（在 IDE 完善相关功能后该方法会被遗弃，目前首选此方法）；
+
+2. 直接链接源码。
+
+方法一：通过 har 包引入（推荐）
+
+> [!TIP] har 包位于三方库安装路径的 `harmony` 文件夹下。
+
+打开 `entry/oh-package.json5`，添加以下依赖
+
+```json
+
+"dependencies": {
+    "@rnoh/react-native-openharmony": "file:../react_native_openharmony",
+    "@react-native-ohos/react-native-keyboard-controller": "file:../../node_modules/@react-native-ohos/react-native-keyboard-controller/harmony/keyboard_controller.har"
+}
+
+```
+
+点击右上角的 `sync` 按钮
+
+或者在终端执行：
+
+```bash
+cd entry
+ohpm install
+```
+
+方法二：直接链接源码
+
+> [!TIP] 如需使用直接链接源码，请参考[直接链接源码说明](https://gitcode.com/CPF-RN/usage-docs/blob/master/zh-cn/link-source-code.md)
+
+### 配置 CMakeLists 和引入 RNKeyboardControllerPackage
+
+打开 `entry/src/main/cpp/CMakeLists.txt`，添加：
+
+```diff
+project(rnapp)
+cmake_minimum_required(VERSION 3.4.1)
+set(CMAKE_SKIP_BUILD_RPATH TRUE)
+set(RNOH_APP_DIR "${CMAKE_CURRENT_SOURCE_DIR}")
+set(NODE_MODULES "${CMAKE_CURRENT_SOURCE_DIR}/../../../../../node_modules")
++ set(OH_MODULES "${CMAKE_CURRENT_SOURCE_DIR}/../../../oh_modules")
+set(RNOH_CPP_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../../../../../../react-native-harmony/harmony/cpp")
+set(LOG_VERBOSITY_LEVEL 1)
+set(CMAKE_ASM_FLAGS "-Wno-error=unused-command-line-argument -Qunused-arguments")
+set(CMAKE_CXX_FLAGS "-fstack-protector-strong -Wl,-z,relro,-z,now,-z,noexecstack -s -fPIE -pie")
+set(WITH_HITRACE_SYSTRACE 1) # for other CMakeLists.txt files to use
+add_compile_definitions(WITH_HITRACE_SYSTRACE)
+
+add_subdirectory("${RNOH_CPP_DIR}" ./rn)
+
+# RNOH_BEGIN: manual_package_linking_1
+add_subdirectory("../../../../sample_package/src/main/cpp" ./sample-package)
+
++ add_subdirectory("${OH_MODULES}/@react-native-ohos/react-native-keyboard-controller/src/main/cpp" ./keyboard-controller)
+
+# RNOH_END: manual_package_linking_1
+
+file(GLOB GENERATED_CPP_FILES "./generated/*.cpp")
+
+add_library(rnoh_app SHARED
+    ${GENERATED_CPP_FILES}
+    "./PackageProvider.cpp"
+    "${RNOH_CPP_DIR}/RNOHAppNapiBridge.cpp"
+)
+target_link_libraries(rnoh_app PUBLIC rnoh)
+
+# RNOH_BEGIN: manual_package_linking_2
+target_link_libraries(rnoh_app PUBLIC rnoh_sample_package)
++ target_link_libraries(rnoh_app PUBLIC rnoh_keyboard_controller)
+# RNOH_END: manual_package_linking_2
+```
+
+打开 `entry/src/main/cpp/PackageProvider.cpp`，添加：
+
+```diff
+#include "RNOH/PackageProvider.h"
+#include "generated/RNOHGeneratedPackage.h"
+#include "SamplePackage.h"
++ #include "keyboardControllerPackage.h"
+
+using namespace rnoh;
+
+std::vector<std::shared_ptr<Package>> PackageProvider::getPackages(Package::Context ctx) {
+    return {
+        std::make_shared<RNOHGeneratedPackage>(ctx),
+        std::make_shared<SamplePackage>(ctx),
++       std::make_shared<KeyboardControllerPackage>(ctx),
+    };
+}
+```
+
+### 在 ArkTS 侧引入 RNKeyboardControllerPackage
+
+打开 `entry/src/main/ets/RNPackagesFactory.ts`，添加：
+
+```diff
++ import { RNKeyboardControllerPackage } from "@react-native-ohos/react-native-keyboard-controller/ts";
+
+export function createRNPackages(ctx: RNPackageContext): RNPackage[] {
+  return [
+    new SamplePackage(ctx),
++   new RNKeyboardControllerPackage(ctx)
+  ];
+}
+```
+</details>
+
+### 运行
+
+点击右上角的 `sync` 按钮
+
+或者在终端执行：
+
+```bash
+cd entry
+ohpm install
+```
+
+然后编译、运行即可。
+
+## 约束与限制
+
+### 兼容性
+
+要使用此库，需要使用正确的 React-Native 和 RNOH 版本。另外，还需要使用配套的 DevEco Studio 和 手机 ROM。
+
+在以下版本验证通过：
+
+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.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上运行，方可生效。
+
+## 使用示例
+
+下面的代码展示了这个库的基本使用场景：
+
+> [!WARNING] 使用时 import 的库名不变。
+
+```js
+import React from 'react';
+import { Text, View, TextInput, TouchableOpacity } from 'react-native';
+import { KeyboardAvoidingView, KeyboardProvider } from 'react-native-keyboard-controller';
+
+function App() {
+  return (
+    <KeyboardProvider>
+      <KeyboardAvoidingView
+        style={{
+          padding: 22,
+          flex: 1,
+          justifyContent: 'space-between',
+        }}>
+        <Text
+          style={{
+            color: 'black',
+            fontSize: 25,
+            marginTop: 100,
+            fontWeight: '500',
+          }}>
+          react-native-keyboard-controller
+        </Text>
+        <View>
+          <TextInput
+            placeholder="Username"
+            placeholderTextColor="#7C7C7C"
+            style={{
+              height: 45,
+              borderColor: '#000000',
+              borderWidth: 1,
+              borderRadius: 10,
+              marginBottom: 36,
+              paddingLeft: 10,
+            }}
+          />
+          <TextInput
+            placeholder="Password"
+            placeholderTextColor="#7C7C7C"
+            style={{
+              height: 45,
+              borderColor: '#000000',
+              borderWidth: 1,
+              borderRadius: 10,
+              marginBottom: 36,
+              paddingLeft: 10,
+            }}
+          />
+          <TouchableOpacity
+            style={{
+              marginTop: 40,
+              height: 45,
+              borderRadius: 10,
+              backgroundColor: 'rgb(40, 64, 147)',
+              justifyContent: 'center',
+              alignItems: 'center',
+            }}>
+            <Text style={{ fontWeight: '500', fontSize: 16, color: 'white' }}>
+              Submit
+            </Text>
+          </TouchableOpacity>
+        </View>
+      </KeyboardAvoidingView>
+    </KeyboardProvider>
+  );
+}
+
+export default App;
+```
+
+## API
+
+> [!TIP] "Platform"列表示该属性在原三方库上支持的平台。
+
+> [!TIP] "HarmonyOS Support"列为 yes 表示 HarmonyOS 平台支持该属性；no 则表示不支持；partially 表示部分支持。使用方法跨平台一致，效果对标 iOS 或 Android 的效果。
+
+**Hooks**:键盘控制器相关的钩子函数
+| Name | Description | Type | Required | Platform | HarmonyOS Support  |
+| ---- | ----------- | ---- | -------- | -------- | ------------------ |
+|  useKeyboardAnimation  |  获取键盘动画值的钩子函数   | `() => AnimatedContext` | no | iOS,Android      | yes |
+|  useReanimatedKeyboardAnimation  |  获取键盘动画值的钩子函数   | `() => ReanimatedContext` | no | iOS,Android      | yes |
+|  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  | 当前聚焦的输入控件文本变化事件回调的钩子函数，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  | 读取 `KeyboardProvider` 提供的键盘上下文，用于构建自定义 Hook；建议业务优先使用上层 Hooks | `() => KeyboardAnimationContext` | no | iOS,Android | yes |
+
+**KeyboardController**：键盘控制器
+
+| Name | Description | Type | Required | Platform | HarmonyOS Support  |
+| ---- | ----------- | ---- | -------- | -------- | ------------------ |
+|  setInputMode(mode: number): void  | 设置键盘显示默认模式   | function   | no | Android      | no |
+|  setDefaultMode(): void  | 设置键盘显示默认模式   | function   | no | 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 | 返回键盘最后的状态 | function | no       | iOS,Android | yes               |
+| preload(): void | 预加载键盘以减少首次聚焦时的延迟 | function | no | iOS | no |
+
+**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_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_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_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  |
+| ---- | ----------- | ---- | -------- | -------- | ------------------ |
+|   setHidden(hidden: boolean): void | 设置状态栏隐藏不可见   | function   | no | Android      | yes |
+|  setColor(color: number, animated: boolean): void  | 设置状态栏背景颜色   | function   | no | Android      | yes |
+|   setTranslucent(translucent: boolean): void | 设置状态栏是否透明   | function   | no | Android      | no |
+| setStyle(style: string): void | 设置状态栏的内容颜色  | function   | no | Android      | yes |
+
+ **KeyboardEvents**:监听键盘事件   
+
+| Name | Description | Type | Required | Platform | HarmonyOS Support  |
+| ---- | ----------- | ---- | -------- | -------- | ------------------ |
+|  keyboardWillShow  | 键盘将要显示事件    | string   | no | iOS,Android      | yes |
+|  keyboardDidShow  | 键盘已经显示事件    | string   | no | iOS,Android      | yes |
+|  keyboardWillHide  | 键盘将要隐藏事件    | string   | no | iOS,Android      | yes |
+|  keyboardDidHide  | 键盘已经隐藏事件    | string   | no | iOS,Android      | yes |
+
+ **FocusedInputEvents**:监听聚焦输入框事件
+
+| Name | Description | Type | Required | Platform | HarmonyOS Support  |
+| ---- | ----------- | ---- | -------- | -------- | ------------------ |
+|  focusDidSet  | 聚焦输入框事件类型    | string   | no | iOS,Android      | no |
+
+ **WindowDimensionsEvents**:监听窗口布局变化事件
+
+| Name | Description | Type | Required | Platform | HarmonyOS Support  |
+| ---- | ----------- | ---- | -------- | -------- | ------------------ |
+|  windowDidResize  | 监听窗口事件    | string   | no | Android      | no |
+
+
+
+
+### 组件
+
+**KeyboardProvider**：为子组件提供键盘监听、动画状态及运行时控制上下文。其 `KeyboardProviderProps` 类型包含以下属性。
+
+| Name | Description | Type | Required | Platform | HarmonyOS Support |
+| ---- | ----------- | ---- | -------- | -------- | ----------------- |
+| `children` | Provider 包裹的子组件 | `React.ReactNode` | yes | 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**：键盘控制器
+
+| Name | Description | Type | Required | Platform | HarmonyOS Support  |
+| ---- | ----------- | ---- | -------- | -------- | ------------------ |
+|  enabled  | 是否开启键盘监听事件    | boolean   | no | iOS,Android      | yes |
+|  statusBarTranslucent  | 状态栏是否透明    | boolean   | no | Android      | no |
+|  navigationBarTranslucent  | 导航栏是否透明    | boolean   | no | Android      | no |
+|  preserveEdgeToEdge  | 是否edge-to-edge模式    | boolean   | no | Android      | yes |
+|  onKeyboardMoveStart?: DirectEventHandler < KeyboardMoveEvent >  | 键盘开始移动的监听事件   | function   | no | iOS,Android       | no |
+|  onKeyboardMove?: DirectEventHandler< KeyboardMoveEvent >  | 键盘移动中的监听事件   | function   | no | iOS,Android      | no |
+|   onKeyboardMoveEnd?: DirectEventHandler< KeyboardMoveEvent > | 键盘移动结束的监听事件   | function   | no | iOS,Android      | yes |
+| onKeyboardMoveInteractive?: DirectEventHandler< KeyboardMoveEvent > | 键盘移动交互的监听事件  | function   | no | iOS,Android      | no |
+| onFocusedInputLayoutChanged?: DirectEventHandler < FocusedInputLayoutChangedEvent >  | 聚焦输入框位置坐标变化的监听事件   |  function  | no | iOS,Android      | yes |
+|   onFocusedInputTextChanged?: DirectEventHandler< FocusedInputTextChangedEvent> | 聚焦输入框文本变化的监听事件   |  function  | no | iOS,Android      | yes |
+|   onFocusedInputSelectionChanged?: DirectEventHandler< FocusedInputSelectionChangedEvent> | 聚焦输入框文本选择的监听事件(HarmonyOS暂支持选区的position，选区坐标默认为0) |  function  | no | iOS,Android      | partially |
+|  style  | `KeyboardControllerView`的CSS属性    | [ ViewStyle ](https://reactnative.dev/docs/view#props)   | no | iOS,Android      | yes |
+|  children  |  JSX element 子组件   | JSX.Element   | no | iOS,Android      | yes |
+
+**KeyboardGestureArea**：手势控制键盘组件
+
+| Name | Description | Type | Required | Platform | HarmonyOS Support  |
+| ---- | ----------- | ---- | -------- | -------- | ------------------ |
+|  showOnSwipeUp  | 键盘随手势向上滑动显示    | boolean   | no | Android      | no |
+|  enableSwipeToDismiss  | 键盘随手势向下滑动隐藏   | boolean   | no | Android      | no |
+|  interpolator  | 设置键盘随手势滑动的动画模式    | `"ios" \| "linear"` | no | Android      | no |
+|  offset  | 到键盘的额外距离    | number | no | iOS、Android      | no |
+|  textInputNativeID  | TextInput对应的nativeID    | string | no | iOS      | no |
+
+**KeyboardAvoidingView**：键盘控制器的容器组件
+
+| Name | Description | Type | Required | Platform | HarmonyOS Support  |
+| ---- | ----------- | ---- | -------- | -------- | ------------------ |
+| behavior | 键盘弹起时视图样式变化的模式(HarmonyOS暂支持position) | `"height" \| "position" \| "padding" \| "translate-with-padding"` | no | iOS,Android | partially |
+|  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 |
+
+**KeyboardAwareScrollView**：滚动键盘控制器的容器组件
+
+| Name | Description | Type | Required | Platform | HarmonyOS Support  |
+| ---- | ----------- | ---- | -------- | -------- | ------------------ |
+|  bottomOffset  | 显示键盘时，键盘与焦点`TextInput`之间的距离。默认值为“0”   | number   | no | iOS,Android      | yes |
+|  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 |
+
+**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**：随键盘移动的粘性视图组件
+
+| Name | Description | Type | Required | Platform | HarmonyOS Support  |
+| ---- | ----------- | ---- | -------- | -------- | ------------------ |
+|  enabled  | 是否激活组件   | boolean   | no | iOS,Android      | yes |
+|  offset  | 为给定的键盘状态指定视图的附加偏移   | {closed?: number;opened?: number;}   | no | iOS,Android      | yes |
+|  style  | `KeyboardStickyView`的CSS属性    | [ ViewStyle ](https://reactnative.dev/docs/view#props)   | no | iOS,Android      | yes |
+|  children  |  JSX element 子组件   | JSX.Element   | no | iOS,Android      | yes |
+
+**KeyboardToolbar**：显示在键盘上方的组件，带有 `Prev`/`Next` 和“完成”按钮。
+
+| Name | Description | Type | Required | Platform | HarmonyOS Support  |
+| ---- | ----------- | ---- | -------- | -------- | ------------------ |
+| `DefaultKeyboardToolbarTheme` | 可直接作为 `KeyboardToolbar` 的 `theme` 属性传入，也可以复制后修改颜色创建自定义主题。该常量为 JavaScript 主题配置。 | `constant` | no | iOS,Android | yes |
+|  enabled  | 是否激活组件   | boolean   | no | iOS,Android      | yes |
+|  offset  | 为给定的键盘状态指定视图的附加偏移   | {closed?: number;opened?: number;}   | no | iOS,Android      | yes |
+|  theme  | 工具栏组件使用的一组深色/浅色主题   | {light: Theme; dark: Theme;}   | no | iOS,Android      | yes |
+|  content  |显示在工具栏中间的元素  | JSX.Element   | no | iOS,Android      | yes |
+|  doneText  |  完成按钮的自定义文本   | React.ReactNode   | no | iOS,Android      | yes |
+|  button  |  工具栏的自定义可触摸组件（用于prev/next/done按钮）   | React.ReactNode   | no | iOS,Android      | yes |
+|  icon  |  用于显示next/prev按钮的自定义图标组件   | React.ReactNode   | no | iOS,Android      | yes |
+|  showArrows  |  是否显示下一个和上一个按钮  | boolean   | no | iOS,Android      | yes |
+|  blur  |  工具栏聚焦时标题组件   | JSX.Element    | no | iOS,Android      | yes |
+|  opacity  |  十六进制格式的容器不透明度值（例如`ff`）。默认值为`ff`   | HEX   | 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**：覆盖在键盘上的容器组件
+
+| Name | Description | Type | Required | Platform | HarmonyOS Support  |
+| ---- | ----------- | ---- | -------- | -------- | ------------------ |
+|  visible  | 是否显示组件   | boolean   | no | iOS,Android      | No |
+
+## 遗留问题
+
+- [ ] 暂不支持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)
+- [ ] 暂不支持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` 属性。
+## 其他
+
+无
+
+## 目录结构
+
+```text
+/rntpc_react-native-keyboard-controller          # 项目根目录
+│  LICENSE
+│  OAT.xml
+│  package.json                                  # NPM、Bob、Codegen 与 HarmonyOS Autolink 配置
+│  README.md
+│  README.OpenSource
+│  buildEnv.sh
+│  tsconfig.json
+│  tsconfig.build.json
+│
+├─example                                        # React Native / HarmonyOS 示例工程
+│  │  app.json
+│  │  index.js
+│  │  package.json
+│  │
+│  ├─src
+│  │      index.tsx                              # 示例业务入口
+│  │
+│  └─harmony                                     # HarmonyOS 示例宿主工程
+│      └─entry
+│          └─src
+│              └─main
+│                  │  module.json5
+│                  ├─cpp
+│                  │      CMakeLists.txt
+│                  │      PackageProvider.cpp    # C++ Package 注册入口
+│                  └─ets
+│                      │  RNPackagesFactory.ets  # ArkTS Package 注册入口
+│                      ├─entryability
+│                      │      EntryAbility.ets
+│                      └─pages
+│                             Index.ets
+│
+├─harmony
+│  │  keyboard_controller.har                   # 编译后的 HAR 包
+│  │
+│  └─keyboard_controller                        # HarmonyOS 适配核心代码
+│      │  build-profile.json5
+│      │  hvigorfile.ts
+│      │  Index.ets                              # HAR 对外导出入口
+│      │  obfuscation-rules.txt
+│      │  oh-package.json5
+│      │  ts.ets                                 # RNOH 代码生成配置入口
+│      │
+│      └─src
+│          └─main
+│              │  module.json
+│              │  module.json5
+│              │
+│              ├─cpp                            # RNOH C++ / Fabric 原生层
+│              │  │  CMakeLists.txt
+│              │  │  RNKeyboardControllerPackage.cpp
+│              │  │  RNKeyboardControllerPackage.h
+│              │  │  keyboardControllerPackage.cpp
+│              │  │  keyboardControllerPackage.h
+│              │  │  RNKeyboardController.cpp   # KeyboardController TurboModule 映射
+│              │  │  RNKeyboardController.h
+│              │  │  RNStatusBarManagerCompat.cpp
+│              │  │  RNStatusBarManagerCompat.h
+│              │  │  EventEmitters.cpp
+│              │  │  EventEmitters.h
+│              │  │  ViewHierarchyNavigator.cpp # 输入框层级遍历与焦点导航
+│              │  │  ViewHierarchyNavigator.h
+│              │  │
+│              │  ├─KeyboardControllerViewComponentInstance.cpp
+│              │  ├─KeyboardControllerViewComponentInstance.h
+│              │  ├─KeyboardControllerViewComponentDescriptor.h
+│              │  ├─KeyboardControllerViewJSIBinder.h
+│              │  ├─KeyboardGestureAreaComponentInstance.cpp
+│              │  ├─KeyboardGestureAreaComponentInstance.h
+│              │  ├─KeyboardGestureAreaComponentDescriptor.h
+│              │  └─KeyboardGestureAreaJSIBinder.h
+│              │
+│              ├─ets                            # ArkTS TurboModule 业务层
+│              │      Logger.ts
+│              │      Type.ts
+│              │      RNKeyboardControllerPackage.ets
+│              │      RNKeyboardControllerTurboModule.ts
+│              │      RNStatusBarManagerCompatTurboModule.ts
+│              │
+│              └─resources                      # 多语言字符串资源
+│
+└─src                                           # JavaScript / TypeScript 公共层
+    │  index.ts                                 # 库统一导出入口
+    │  bindings.ts
+    │  bindings.native.ts                       # 原生模块、事件与 Fabric 组件绑定
+    │  animated.tsx                             # 键盘动画值与事件处理
+    │  context.ts                               # KeyboardProvider 上下文
+    │  constants.ts
+    │  internal.ts
+    │  reanimated.ts
+    │  reanimated.native.ts
+    │  types.ts
+    │  utils.ts
+    │
+    ├─specs                                     # TurboModule / Fabric Codegen 规格
+    │      NativeKeyboardController.ts
+    │      NativeStatusBarManagerCompat.ts
+    │      KeyboardControllerViewNativeComponent.ts
+    │      KeyboardGestureAreaNativeComponent.ts
+    │
+    ├─hooks
+    │  └─useWindowDimensions
+    │         index.ts
+    │         index.android.ts
+    │
+    └─components
+        ├─KeyboardAvoidingView                   # 键盘避让容器
+        ├─KeyboardAwareScrollView                # 键盘感知滚动容器
+        ├─KeyboardStickyView                     # 随键盘移动的粘性视图
+        └─KeyboardToolbar                        # 键盘工具栏
+```
+
+## 贡献代码
+
+使用过程中发现任何问题都可以提交 [Issue](https://gitcode.com/CPF-RN/rntpc_react-native-keyboard-controller/issues)，也欢迎提交 [PR](https://gitcode.com/CPF-RN/rntpc_react-native-keyboard-controller/pulls)。
+
+## 开源协议
+
+本项目基于 [The MIT License (MIT)](https://github.com/kirillzyusko/react-native-keyboard-controller/blob/main/LICENSE) ，请自由地享受和参与开源。