文档模板：v0.4.2

react-native-keyboard-controller

本项目基于 react-native-keyboard-controller 开发。

该第三方库的仓库已迁移至 Gitcode，且支持直接从 npm 下载，新的包名为：@react-native-ohos/react-native-keyboard-controller。版本所属关系如下：

简介

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

{
  "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" // 指向源码路径
  }
}

"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"
}

cd entry
ohpm install

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

#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),
    };
}

+ 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。

在以下版本验证通过：

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要求

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

使用示例

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

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

Hooks:键盘控制器相关的钩子函数

KeyboardController：键盘控制器

AndroidSoftInputModes：Android windowSoftInputMode 的公共枚举，用于向 setInputMode 传入输入法窗口调整模式。HarmonyOS 不适用。

KeyboardState：useAnimatedKeyboard() 使用的键盘状态常量。

公共常量

StatusBarManagerCompat：状态栏控制器

KeyboardEvents:监听键盘事件

FocusedInputEvents:监听聚焦输入框事件

WindowDimensionsEvents:监听窗口布局变化事件

组件

KeyboardProvider：为子组件提供键盘监听、动画状态及运行时控制上下文。其 KeyboardProviderProps 类型包含以下属性。

KeyboardControllerView：键盘控制器

KeyboardGestureArea：手势控制键盘组件

KeyboardAvoidingView：键盘控制器的容器组件

KeyboardAwareScrollView：滚动键盘控制器的容器组件

KeyboardChatScrollView：面向聊天场景的键盘感知滚动容器组件，用于在键盘显示或隐藏时联动调整消息列表的底部空间和滚动位置

KeyboardStickyView：随键盘移动的粘性视图组件

KeyboardToolbar：显示在键盘上方的组件，带有 Prev/Next 和“完成”按钮。

KeyboardToolbar Compound：KeyboardToolbar的组合式API，通过静态子组件分别定义背景、中间内容和操作按钮。

KeyboardToolbar.Background、KeyboardToolbar.Content、KeyboardToolbar.Prev、KeyboardToolbar.Next和KeyboardToolbar.Done需要作为KeyboardToolbar的直接子组件。

KeyboardToolbar.Group：输入框分组组件。该组件作为KeyboardToolbar的静态成员导出，但不属于Compound内容组件；应包裹需要分组的输入框，限定Prev/Next按钮仅在当前分组内遍历。

KeyboardBackgroundView：匹配键盘区域背景的视图组件

KeyboardExtender：将子内容附着到键盘区域，并显示在键盘系统按钮上方的容器组件

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

遗留问题

• 暂不支持KeyboardControllerView中onKeyboardMoveStart，onKeyboardMove，onKeyboardMoveInteractive事件的回调： issue#1
• 暂不支持KeyboardGestureArea组件：issue#2
• 暂不支持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
• 暂不支持KeyboardChatScrollView的onEndVisible、onContentInsetChange回调以及extraContentPadding、blankSpace属性
• 暂不支持KeyboardAwareScrollView Ref的assureFocusedInputVisible()方法和mode属性
• 暂不支持KeyboardBackgroundView组件
• 暂不支持 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) ，请自由地享受和参与开源。