React Native如何实现全局键盘按键事件监听？

你说得没错，React Native内置的Keyboard API确实只处理键盘的显示和隐藏事件，而PanResponder也只能捕获触摸交互，对系统键盘的按键事件无能为力。要实现全局按键监听，得根据平台特性来，这里提供几个不同层级的方案：

1. 纯JS Hack方案（快速上手，跨平台） #

这个思路是利用「只有获得焦点的输入组件能接收按键事件」的特性，用一个全屏隐藏的TextInput来兜底捕获所有按键。虽然是hack，但胜在不需要写原生代码，快速可用：

import React, { useRef, useEffect } from 'react';
import { TextInput, StyleSheet } from 'react-native';

const GlobalKeyCapture = ({ onKeyPress }) => {
  const inputRef = useRef(null);

  useEffect(() => {
    // 组件挂载后立刻获取焦点
    inputRef.current?.focus();
  }, []);

  return (
    <TextInput
      ref={inputRef}
      style={styles.hiddenInput}
      onKeyPress={({ nativeEvent }) => onKeyPress(nativeEvent.key)}
      // 禁止弹出软键盘，避免干扰正常交互
      showSoftInputOnFocus={false}
      // 失去焦点时立刻重新获取，保证持续监听
      onBlur={() => inputRef.current?.focus()}
    />
  );
};

const styles = StyleSheet.create({
  hiddenInput: {
    position: 'absolute',
    top: 0,
    left: 0,
    width: '100%',
    height: '100%',
    opacity: 0,
    zIndex: -1, // 确保不会遮挡其他UI组件
  },
});

// 使用示例：
// <GlobalKeyCapture onKeyPress={(key) => console.log('按下了:', key)} />

⚠️ 注意：当其他输入框获取焦点时，这个隐藏输入框会暂时失去监听能力，你可以额外监听Keyboard的keyboardDidShow事件，在键盘弹出时强制让隐藏输入框重新获取焦点；另外Android上showSoftInputOnFocus可能需要配合原生配置才能完全禁用软键盘。

2. 原生模块方案（稳定可靠，平台定制） #

如果需要更稳定的全局监听，尤其是要处理系统按键（比如Android的返回键、音量键），最好的方式是分别为iOS和Android编写原生模块，直接对接系统的按键事件。

Android 端实现 #

Android可以通过在Activity的DecorView上设置OnKeyListener来捕获全局按键：

1. 创建原生模块类（GlobalKeyModule.java）：

package com.yourAppPackage;

import com.facebook.react.bridge.ReactApplicationContext;
import com.facebook.react.bridge.ReactContextBaseJavaModule;
import com.facebook.react.modules.core.DeviceEventManagerModule;
import android.view.KeyEvent;
import android.app.Activity;

public class GlobalKeyModule extends ReactContextBaseJavaModule {

    private final ReactApplicationContext reactContext;

    public GlobalKeyModule(ReactApplicationContext context) {
        super(context);
        reactContext = context;
    }

    @Override
    public String getName() {
        return "GlobalKeyModule";
    }

    @Override
    public void initialize() {
        super.initialize();
        Activity currentActivity = getCurrentActivity();
        if (currentActivity != null) {
            currentActivity.getWindow().getDecorView().setOnKeyListener((v, keyCode, event) -> {
                if (event.getAction() == KeyEvent.ACTION_DOWN) {
                    // 把按键码发送到JS层
                    reactContext.getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter.class)
                            .emit("globalKeyDown", keyCode);
                } else if (event.getAction() == KeyEvent.ACTION_UP) {
                    reactContext.getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter.class)
                            .emit("globalKeyUp", keyCode);
                }
                return false; // 返回false让其他组件也能处理该事件
            });
        }
    }
}

2. 注册模块到Package：

package com.yourAppPackage;

import com.facebook.react.ReactPackage;
import com.facebook.react.bridge.NativeModule;
import com.facebook.react.bridge.ReactApplicationContext;
import com.facebook.react.uimanager.ViewManager;
import java.util.ArrayList;
import java.util.List;

public class GlobalKeyPackage implements ReactPackage {
    @Override
    public List<NativeModule> createNativeModules(ReactApplicationContext reactContext) {
        List<NativeModule> modules = new ArrayList<>();
        modules.add(new GlobalKeyModule(reactContext));
        return modules;
    }

    @Override
    public List<ViewManager> createViewManagers(ReactApplicationContext reactContext) {
        return new ArrayList<>();
    }
}

3. 在JS层监听事件：

import { NativeEventEmitter, NativeModules, useEffect } from 'react-native';

const { GlobalKeyModule } = NativeModules;
const keyEmitter = new NativeEventEmitter(GlobalKeyModule);

useEffect(() => {
    const downListener = keyEmitter.addListener('globalKeyDown', (keyCode) => {
        console.log('Android按键按下:', keyCode);
        // 比如判断返回键：keyCode === 4
    });

    const upListener = keyEmitter.addListener('globalKeyUp', (keyCode) => {
        console.log('Android按键抬起:', keyCode);
    });

    return () => {
        downListener.remove();
        upListener.remove();
    };
}, []);

iOS 端实现 #

iOS可以通过重写AppDelegate的keyDown方法来捕获全局按键：

1. 修改AppDelegate.m：

#import "AppDelegate.h"
#import <React/RCTBridge.h>
#import <React/RCTDeviceEventEmitter.h>

@implementation AppDelegate

// ... 原有代码 ...

- (void)keyDown:(UIKeyEvent *)event {
    [super keyDown:event];
    NSString *key = event.keyCharacters;
    RCTBridge *bridge = self.window.rootViewController.bridge;
    if (bridge) {
        [[bridge moduleForClass:[RCTDeviceEventEmitter class]] sendEventWithName:@"globalKeyDown" body:key];
    }
}

@end

2. JS层监听：

import { NativeEventEmitter, NativeModules, useEffect } from 'react-native';

const eventEmitter = new NativeEventEmitter(NativeModules.DeviceEventEmitter);

useEffect(() => {
    const listener = eventEmitter.addListener('globalKeyDown', (key) => {
        console.log('iOS按键:', key);
    });

    return () => listener.remove();
}, []);

⚠️ iOS注意：当有文本输入框聚焦时，keyDown可能不会触发，此时可以结合UIKeyCommand注册全局按键，或者在输入框的代理方法中转发事件。

3. 第三方库（省力之选） #

如果你不想折腾原生代码，可以试试社区维护的第三方库，比如react-native-keyevent，它已经封装好了跨平台的全局按键监听逻辑，直接调用API即可，不过要注意和你当前React Native版本的兼容性。

内容的提问来源于stack exchange，提问作者Walter Shub