@react-native-ohos/react-native-keyboard-controller

v1.16.8

Published

an hour ago

Keyboard manager which works in identical way on iOS and Android and harmony

文档模板：v0.4.2

本项目基于 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.16.7 | Gitcode Releases | 0.77.* | 否 | API12+ | 1.16.5 | br_rnoh0.77 |

简介

React Native 生态中用于精细控制键盘行为的增强库。核心功能是解决原生键盘交互的局限性，提供键盘弹出/收起的动画联动、高度监听、自定义工具栏及键盘避让等能力！帮助开发者轻松构建流畅、无缝的键盘联动输入体验。

下载安装

进入到工程目录并输入以下命令：

npm

npm install @react-native-ohos/react-native-keyboard-controller

yarn

yarn add @react-native-ohos/react-native-keyboard-controller

另外本库依赖三方库react-native-reanimated，请按照react-native-reanimated指导文档引入此依赖库。

Link

| | 是否支持autolink | RN框架版本 | |-------------------------------|------------------|-----------| | ~ 1.16.7 | No | 0.77 |

首先需要使用 DevEco Studio 打开项目里的 HarmonyOS 工程 harmony。

在工程根目录的 `oh-package.json5` 添加 overrides 字段

为了让工程依赖同一个版本的 RN SDK，需要在工程根目录的 oh-package.json5 添加 overrides 字段，指向工程需要使用的 RN SDK 版本。替换的版本既可以是一个具体的版本号，也可以是一个模糊版本，还可以是本地存在的 HAR 包或源码目录。

关于该字段的作用请阅读官方说明

{
  "overrides": {
    "@rnoh/react-native-openharmony": "^0.77.38" // ohpm 在线版本
    // "@rnoh/react-native-openharmony" : "./react_native_openharmony.har" // 指向本地 har 包的路径
    // "@rnoh/react-native-openharmony" : "./react_native_openharmony" // 指向源码路径
  }
}

引入原生端代码

目前有两种方法：

通过 har 包引入（在 IDE 完善相关功能后该方法会被遗弃，目前首选此方法）；
直接链接源码。

方法一：通过 har 包引入（推荐）

[!TIP] har 包位于三方库安装路径的 harmony 文件夹下。

打开 entry/oh-package.json5，添加以下依赖


"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 按钮

或者在终端执行：

cd entry
ohpm install

方法二：直接链接源码

[!TIP] 如需使用直接链接源码，请参考直接链接源码说明

配置 CMakeLists 和引入 RNKeyboardControllerPackage

打开 entry/src/main/cpp/CMakeLists.txt，添加：

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，添加：

#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，添加：

+ import { RNKeyboardControllerPackage } from "@react-native-ohos/react-native-keyboard-controller/ts";

export function createRNPackages(ctx: RNPackageContext): RNPackage[] {
  return [
    new SamplePackage(ctx),
+   new RNKeyboardControllerPackage(ctx)
  ];
}

运行

点击右上角的 sync 按钮

或者在终端执行：

cd entry
ohpm install

然后编译、运行即可。

约束与限制

兼容性

要使用此库，需要使用正确的 React-Native 和 RNOH 版本。另外，还需要使用配套的 DevEco Studio 和手机 ROM。

在以下版本验证通过：

RNOH: 0.77.61; SDK: HarmonyOS 6.0.0 Release SDK; IDE: DevEco Studio 6.0.0.858; ROM: 6.0.0.112;

编译运行API要求

[!TIP] 当前分支版本支持在 API12+ 工程编译，及 API12+ ROM运行。

[!TIP] 以下功能依赖特定版本的API，使用 低于指定API版本的工程编译 或 低于指定API版本的ROM运行 均可能导致部分功能受限。

版本 >=1.16.7 for 0.77引入OH_ArkUI_FocusRequest,实现了 onNextCallback?: () => void 和 onPrevCallback?: () => void 功能，此API需要在支持API15+的工程编译，并在支持API15+的ROM上运行，方可生效。
版本 >=1.16.8 for 0.77引入了on('keyboardWillShow')和on('keyboardWillHide')，实现了KeyboardEvents中的keyboardWillShow键盘将要显示事件和keyboardWillHide键盘将要隐藏事件功能，这些API需要在支持API20+的工程编译，并在支持API20+的ROM上运行，方可生效。

使用示例

下面的代码展示了这个库的基本使用场景：

[!WARNING] 使用时 import 的库名不变。

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 | 当前聚焦的输入控件文本变化事件回调的钩子函数 | () => { 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(options?: DismissOptions): Promise | 设置键盘隐藏。DismissOptions 为 { keepFocus: boolean }，用于指定隐藏键盘时是否保持输入框焦点。HarmonyOS 可以隐藏键盘；由于 HarmonyOS 缺少保持聚焦输入框的相关能力，keepFocus 参数暂不支持。 | Promise<void> | no | iOS,Android | partially | | 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 | | isVisible(): boolean | 返回键盘是否可见 | function | no | iOS,Android | yes | | state(): KeyboardEventData | null | 返回键盘最后的状态，如果键盘还没有显示过返回 null | 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：为子组件提供键盘监听、动画状态及运行时控制上下文。其 KeyboardProviderProps 类型包含以下属性。

| Name | Description | Type | Required | Platform | HarmonyOS Support | | ---- | ----------- | ---- | -------- | -------- | ------------------ | | children | Provider 包裹的子组件 | React.ReactNode | yes | iOS,Android | yes | | enabled | 是否在初始化时开启键盘监听，运行时切换请使用 useKeyboardController().setEnabled()，默认值为 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 |

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 | 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 | 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 | 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 | no | iOS,Android | yes | | children | JSX element 子组件 | JSX.Element | no | iOS,Android | yes | | ScrollViewComponent | ScrollView的自定义组件 | React.ComponentType | no | iOS,Android | yes |

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 | 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?: () => 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 |

OverKeyboardView：覆盖在键盘上的容器组件

| Name | Description | Type | Required | Platform | HarmonyOS Support | | ---- | ----------- | ---- | -------- | -------- | ------------------ | | visible | 是否显示组件 | boolean | no | iOS,Android | No |

遗留问题

[ ] 暂不支持KeyboardControllerView中onKeyboardMoveStart，onKeyboardMove，onKeyboardMoveInteractive事件的回调： issue#1
[ ] 暂不支持KeyboardGestureArea组件：issue#2
[ ] 暂不支持hook方法useReanimatedFocusedInput，KeyboardController中setFocusTo，FocusedInputEvents中focusDidSet：issue#3
[ ] 暂不支持KeyboardAwareScrollView组件属性disableScrollOnKeyboardHide、extraKeyboardSpace的设置#issue#16
[ ] KeyboardControllerView中onFocusedInputSelectionChanged事件部分支持，HarmonyOS暂支持选区的position，选区坐标默认为0：issue#13
[ ] KeyboardAvoidingView属性behavior支持position，不支持高度height、padding的样式#issue#13
[ ] 暂不支持OverKeyboardView接口：issue#27
[ ] 暂不支持 Hook 方法 useResizeMode。
[ ] Hook 方法 useGenericKeyboardHandler 部分支持：HarmonyOS 原生仅支持 onEnd，onStart、onMove 不是原生事件，onInteractive 不支持。
[ ] 暂不支持 KeyboardProvider 的 statusBarTranslucent 和 navigationBarTranslucent 属性。

其他

无

目录结构

/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，也欢迎提交 PR。

开源协议

本项目基于 The MIT License (MIT) ，请自由地享受和参与开源。