React Native中如何在屏幕未激活时监听音量按键按下事件？

React Native本身没有提供后台监听音量按键的原生API，必须通过自定义原生模块桥接来实现——因为iOS和Android原生平台都支持后台监听硬件按键事件，我们只需要把原生的事件通知传递到RN层即可。

iOS 实现方案 #

iOS要在后台监听音量键，需要依赖音频会话和系统通知，同时配置后台权限：

步骤1：配置Xcode后台权限 #

打开你的RN项目的iOS工程，在Signing & Capabilities中添加Background Modes，勾选Audio, AirPlay, and Picture in Picture，确保APP在后台能保持音频会话活跃。

步骤2：编写原生事件模块 #

创建一个继承自RCTEventEmitter的原生模块，监听系统音量变化通知，并将事件传递给RN：

// VolumeKeyListenerModule.h
#import <React/RCTEventEmitter.h>
#import <AVFoundation/AVFoundation.h>

@interface VolumeKeyListenerModule : RCTEventEmitter <RCTBridgeModule>
@end

// VolumeKeyListenerModule.m
#import "VolumeKeyListenerModule.h"

@implementation VolumeKeyListenerModule

// 注册模块名称，RN端通过这个名称调用
RCT_EXPORT_MODULE();

// 声明支持的事件名
- (NSArray<NSString *> *)supportedEvents {
  return @[@"onVolumeKeyPressed"];
}

// 模块开始监听时激活音频会话并注册通知
- (void)startObserving {
  NSError *error;
  [[AVAudioSession sharedInstance] setCategory:AVAudioSessionCategoryPlayback error:&error];
  [[AVAudioSession sharedInstance] setActive:YES error:&error];
  
  [[NSNotificationCenter defaultCenter] addObserver:self
                                           selector:@selector(handleVolumeChange:)
                                               name:@"AVSystemController_SystemVolumeDidChangeNotification"
                                             object:nil];
}

// 模块停止监听时移除通知并关闭音频会话
- (void)stopObserving {
  [[NSNotificationCenter defaultCenter] removeObserver:self];
  NSError *error;
  [[AVAudioSession sharedInstance] setActive:NO withOptions:AVAudioSessionSetActiveOptionNotifyOthersOnDeactivation error:&error];
}

// 处理音量变化事件，判断是加还是减并发送到RN
- (void)handleVolumeChange:(NSNotification *)notification {
  NSString *changeReason = notification.userInfo[@"AVSystemController_AudioVolumeChangeReasonNotificationParameter"];
  // 只处理用户手动按下音量键的情况
  if ([changeReason isEqualToString:@"ExplicitVolumeChange"]) {
    float currentVolume = [[AVAudioSession sharedInstance] outputVolume];
    float previousVolume = [[notification.userInfo objectForKey:@"AVSystemController_PreviousVolumeNotificationParameter"] floatValue];
    NSString *keyType = currentVolume > previousVolume ? @"up" : @"down";
    
    [self sendEventWithName:@"onVolumeKeyPressed" body:@{
      @"type": keyType,
      @"volume": @(currentVolume)
    }];
  }
}

@end

步骤3：RN端监听事件 #

使用NativeEventEmitter接收原生模块发送的事件：

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

const { VolumeKeyListenerModule } = NativeModules;
const volumeEmitter = new NativeEventEmitter(VolumeKeyListenerModule);

export default function YourComponent() {
  useEffect(() => {
    const subscription = volumeEmitter.addListener(
      'onVolumeKeyPressed',
      (data) => {
        console.log(`音量${data.type}键按下，当前音量：${data.volume}`);
        // 在这里处理你的业务逻辑
      }
    );

    // 组件卸载时取消监听
    return () => subscription.remove();
  }, []);

  // ... 你的组件代码
}

Android 实现方案 #

Android后台监听音量键的最佳方案是使用AccessibilityService（普通广播在后台可能被系统限制），但需要用户手动开启辅助功能权限。

步骤1：创建Accessibility服务 #

编写一个监听按键事件的辅助服务，将音量键事件传递给RN：

// VolumeAccessibilityService.java
package com.yourapppackage; // 替换成你的APP包名

import android.accessibilityservice.AccessibilityService;
import android.view.KeyEvent;
import android.view.accessibility.AccessibilityEvent;
import com.facebook.react.bridge.ReactApplicationContext;
import com.facebook.react.bridge.WritableMap;
import com.facebook.react.bridge.Arguments;
import com.facebook.react.modules.core.DeviceEventManagerModule;

public class VolumeAccessibilityService extends AccessibilityService {
    private ReactApplicationContext reactContext;

    public VolumeAccessibilityService(ReactApplicationContext context) {
        reactContext = context;
    }

    @Override
    public void onAccessibilityEvent(AccessibilityEvent event) {}

    @Override
    public void onInterrupt() {}

    @Override
    protected boolean onKeyEvent(KeyEvent event) {
        // 只处理按下事件
        if (event.getAction() == KeyEvent.ACTION_DOWN) {
            String keyType = "";
            if (event.getKeyCode() == KeyEvent.KEYCODE_VOLUME_UP) {
                keyType = "up";
            } else if (event.getKeyCode() == KeyEvent.KEYCODE_VOLUME_DOWN) {
                keyType = "down";
            }

            if (!keyType.isEmpty()) {
                // 获取当前媒体音量
                android.media.AudioManager audioManager = (android.media.AudioManager) getApplicationContext().getSystemService(AUDIO_SERVICE);
                int currentVolume = audioManager.getStreamVolume(android.media.AudioManager.STREAM_MUSIC);

                // 发送事件到RN
                WritableMap params = Arguments.createMap();
                params.putString("type", keyType);
                params.putInt("volume", currentVolume);
                reactContext.getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter.class).emit("onVolumeKeyPressed", params);
            }
        }
        return super.onKeyEvent(event);
    }
}

步骤2：配置服务权限 #

在AndroidManifest.xml中注册辅助服务，并创建配置文件：

<!-- 在<application>标签内添加 -->
<service
    android:name=".VolumeAccessibilityService"
    android:permission="android.permission.BIND_ACCESSIBILITY_SERVICE">
    <intent-filter>
        <action android:name="android.accessibilityservice.AccessibilityService" />
    </intent-filter>
    <meta-data
        android:name="android.accessibilityservice"
        android:resource="@xml/accessibility_service_config" />
</service>

在res/xml目录下创建accessibility_service_config.xml（如果没有xml目录则新建）：

<?xml version="1.0" encoding="utf-8"?>
<accessibility-service xmlns:android="http://schemas.android.com/apk/res/android"
    android:accessibilityEventTypes="typeAllMask"
    android:accessibilityFeedbackType="feedbackGeneric"
    android:accessibilityFlags="flagDefault"
    android:canRequestFilterKeyEvents="true" />

步骤3：编写RN桥接模块 #

创建一个原生模块，提供打开辅助功能设置的方法（因为无法自动开启权限）：

// VolumeKeyListenerModule.java
package com.yourapppackage;

import android.content.Intent;
import android.provider.Settings;
import com.facebook.react.bridge.ReactApplicationContext;
import com.facebook.react.bridge.ReactContextBaseJavaModule;
import com.facebook.react.bridge.ReactMethod;

public class VolumeKeyListenerModule extends ReactContextBaseJavaModule {
    private ReactApplicationContext reactContext;

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

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

    // RN端调用此方法打开辅助功能设置
    @ReactMethod
    public void openAccessibilitySettings() {
        Intent intent = new Intent(Settings.ACTION_ACCESSIBILITY_SETTINGS);
        intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
        reactContext.startActivity(intent);
    }
}

步骤4：注册模块并在RN端使用 #

在MainApplication.java中注册两个模块：

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.Collections;
import java.util.List;

// ... 其他代码

@Override
protected List<ReactPackage> getPackages() {
  List<ReactPackage> packages = new PackageList(this).getPackages();
  packages.add(new ReactPackage() {
    @Override
    public List<NativeModule> createNativeModules(ReactApplicationContext reactContext) {
      List<NativeModule> modules = new ArrayList<>();
      modules.add(new VolumeKeyListenerModule(reactContext));
      modules.add(new VolumeAccessibilityService(reactContext));
      return modules;
    }

    @Override
    public List<ViewManager> createViewManagers(ReactApplicationContext reactContext) {
      return Collections.emptyList();
    }
  });
  return packages;
}

RN端代码：

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

const { VolumeKeyListenerModule } = NativeModules;
const volumeEmitter = new NativeEventEmitter(VolumeKeyListenerModule);

export default function YourComponent() {
  useEffect(() => {
    const subscription = volumeEmitter.addListener(
      'onVolumeKeyPressed',
      (data) => {
        console.log(`音量${data.type}键按下，当前音量：${data.volume}`);
        // 处理业务逻辑
      }
    );

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

  return (
    <View>
      <Button 
        title="开启辅助功能以监听后台音量键" 
        onPress={() => VolumeKeyListenerModule.openAccessibilitySettings()} 
      />
    </View>
  );
}

注意事项 #

• iOS：后台监听依赖音频会话激活，可能会影响其他音频类APP，测试时需注意；另外，系统音量条会默认显示，若要隐藏需要额外处理（比如通过播放静音音频）。
• Android：辅助功能权限需要用户手动开启，无法自动授予；部分国产ROM可能会限制辅助功能的后台运行权限，需测试适配。
• 测试时务必将APP切换到后台（锁定屏幕或打开其他APP），再按下音量键验证事件是否触发。

内容的提问来源于stack exchange，提问作者Harsh Patel