@react-native-ohos/react-native-keyboard-controller 1.12.8 → 1.12.9

package/README.md

@@ -1,19 +1,603 @@
-# @react-native-ohos/react-native-keyboard-controller
-
-本项目基于 [react-native-keyboard-controller@1.12.7-0.0.5](https://github.com/react-native-oh-library/react-native-keyboard-controller/tree/1.12.7-0.0.5)
-
-## 文档地址 / Documentation URL 
-
-[中文 / Chinese](https://gitee.com/react-native-oh-library/usage-docs/blob/master/zh-cn/react-native-keyboard-controller.md)
-
-[英文 / English](https://gitee.com/react-native-oh-library/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.12.8](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.72.* | 是 | API12+ | 1.12.7 | [br_rnoh0.72](https://gitcode.com/CPF-RN/rntpc_react-native-keyboard-controller/tree/br_rnoh0.72) |
+| @react-native-oh-tpl/react-native-keyboard-controller | [<=1.12.7-0.0.5@deprecated](https://www.npmjs.com/package/@react-native-oh-tpl/react-native-keyboard-controller) | [Github Releases(deprecated)](https://github.com/react-native-oh-library/react-native-keyboard-controller/releases) | 0.72.* | 否 | API12+ | 1.12.7 | [sig](https://github.com/react-native-oh-library/react-native-keyboard-controller/tree/sig) |
+
+## 简介
+
+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.12.8                       |  Yes             |  0.72     |
+| <= 1.12.7-0.0.5@deprecated    |  No              |  0.72     |
+
+使用AutoLink的工程需要根据该文档配置，Autolink框架指导文档：https://gitcode.com/CPF-RN/ohos_react_native/blob/master/docs/zh-cn/Autolinking.md
+
+如您使用的版本支持 Autolink，并且工程已接入 Autolink，可跳过ManualLink配置。
+<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.72.38" // 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
+
+> 若使用的是 <= 1.12.7-0.0.5 版本，请跳过本章
+
+打开 `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.72.130; SDK: HarmonyOS 6.0.0 Release SDK; IDE: DevEco Studio 6.0.0.858; ROM: 6.0.0.112;
+2. RNOH: 0.72.33; SDK: HarmonyOS NEXT B1; IDE: DevEco Studio: 5.0.3.900; ROM: Next.0.0.71;
+
+### 编译运行API要求
+
+> [!TIP] 当前分支版本支持在 `API12+` 工程编译，及 `API12+` ROM运行。
+
+> [!TIP] 以下功能依赖特定版本的API，使用 `低于指定API版本的工程编译` 或 `低于指定API版本的ROM运行` 均可能导致部分功能受限。
+1. 版本 >=1.12.8 for 0.72引入[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.12.9 for 0.72引入了[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  |  设置是否启动键盘监听事件的钩子函数   | `() => { enabled: boolean; setEnabled: React.Dispatch<React.SetStateAction<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 |
+|  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 |
+
+**KeyboardController**：键盘控制器
+
+| Name | Description | Type | Required | Platform | HarmonyOS Support  |
+| ---- | ----------- | ---- | -------- | -------- | ------------------ |
+|  setInputMode(mode: number): void  | 设置键盘显示默认模式   | function   | no | Android      | no |
+|  setDefaultMode(): void  | 设置键盘显示默认模式   | function   | no | Android      | no |
+| dismiss(): void | 设置键盘隐藏 | function   | no | iOS,Android      | yes |
+| setFocusTo(direction: "next" \| "prev" \| "current"): void | 将焦点移动到下一个、上一个或当前输入框   | function   | no | iOS,Android      | no |
+| addListener: (eventName: string) => void  | 添加键盘的监听事件   |  function  | no | iOS,Android      | yes |
+|   removeListeners: (count: number) => void | 删除键盘的监听事件   |  function  | no | iOS,Android      | yes |
+
+**AndroidSoftInputModes**：Android `windowSoftInputMode` 的公共枚举，用于向 `setInputMode` 传入输入法窗口调整模式。该枚举对应 Android `WindowManager.LayoutParams`，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 |
+
+**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**：为子组件提供键盘监听、动画状态及运行时控制上下文
+
+| Name | Description | Type | Required | Platform | HarmonyOS Support  |
+| ---- | ----------- | ---- | -------- | -------- | ------------------ |
+|  children  | Provider 包裹的子组件    | React.ReactNode   | yes | iOS,Android      | yes |
+|  enabled  | 是否在初始化时开启键盘监听    | boolean   | no | iOS,Android      | yes |
+|  statusBarTranslucent  | 是否使用透明状态栏，默认值为 `false`    | boolean   | no | Android      | no |
+|  navigationBarTranslucent  | 是否使用透明导航栏，默认值为 `false`    | boolean   | no | Android      | 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 |
+|  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 |
+
+**KeyboardAvoidingView**：键盘控制器的容器组件
+
+| Name | Description | Type | Required | Platform | HarmonyOS Support  |
+| ---- | ----------- | ---- | -------- | -------- | ------------------ |
+|  behavior  | 键盘弹起时视图样式变化的模式(HarmonyOS暂支持position)   | "height" / "position" / "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 |
+|  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 |
+|  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 |
+
+**KeyboardStickyView**：随键盘移动的粘性视图组件
+
+| Name | Description | Type | Required | Platform | HarmonyOS Support  |
+| ---- | ----------- | ---- | -------- | -------- | ------------------ |
+|  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 |
+|  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?: () => void | 当用户按下“下一步”按钮时调用的回调以及默认操作。 | function   | no | iOS,Android      | yes |
+|  onPrevCallback?: () => void | 用户按下“上一步”按钮时调用的回调以及默认操作。 | function   | no | iOS,Android      | yes |
+| onDoneCallback?: () => void | 当用户按下“完成”按钮时调用的回调以及默认操作。 | function   | no | iOS,Android      | yes |
+
+## 遗留问题
+
+- [ ] 暂不支持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)
+- [ ] KeyboardControllerView中onFocusedInputSelectionChanged事件部分支持，HarmonyOS暂支持选区的position，选区坐标默认为0：[issue#13](https://github.com/react-native-oh-library/react-native-keyboard-controller/issues/13)
+- [ ] 暂不支持KeyboardAwareScrollView组件属性disableScrollOnKeyboardHide、extraKeyboardSpace的设置[#issue#16](https://github.com/react-native-oh-library/react-native-keyboard-controller/issues/16)
+- [ ] KeyboardAvoidingView属性behavior支持position， 不支持高度height、padding的样式[#issue#13](https://github.com/react-native-oh-library/react-native-harmony-reanimated/issues/13)
+- [ ] 暂不支持 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) ，请自由地享受和参与开源。

package/harmony/keyboard_controller/BuildProfile.ets

@@ -1,17 +1,17 @@
-/**
- * Use these variables when you tailor your ArkTS code. They must be of the const type.
- */
-export const HAR_VERSION = '1.12.7-0.0.5';
-export const BUILD_MODE_NAME = 'debug';
-export const DEBUG = true;
-export const TARGET_NAME = 'default';
-
-/**
- * BuildProfile Class is used only for compatibility purposes.
- */
-export default class BuildProfile { 
-	static readonly HAR_VERSION = HAR_VERSION;
-	static readonly BUILD_MODE_NAME = BUILD_MODE_NAME;
-	static readonly DEBUG = DEBUG;
-	static readonly TARGET_NAME = TARGET_NAME;
+/**
+ * Use these variables when you tailor your ArkTS code. They must be of the const type.
+ */
+export const HAR_VERSION = '1.12.9';
+export const BUILD_MODE_NAME = 'debug';
+export const DEBUG = true;
+export const TARGET_NAME = 'default';
+
+/**
+ * BuildProfile Class is used only for compatibility purposes.
+ */
+export default class BuildProfile { 
+	static readonly HAR_VERSION = HAR_VERSION;
+	static readonly BUILD_MODE_NAME = BUILD_MODE_NAME;
+	static readonly DEBUG = DEBUG;
+	static readonly TARGET_NAME = TARGET_NAME;
 }