native-module-helper

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Native Module Helper

Native Module 开发助手

Build custom native modules to bridge JavaScript and native code in React Native.

在React Native中构建自定义原生模块，实现JavaScript与原生代码的桥接。

Quick Start

快速开始

Native modules expose native functionality to JavaScript. Choose based on React Native version:

Legacy Bridge: RN < 0.68 (stable, widely supported)
Turbo Modules: RN >= 0.68 (better performance, type-safe)

原生模块可将原生功能暴露给JavaScript。请根据React Native版本选择：

Legacy Bridge：RN < 0.68（稳定版，支持广泛）
Turbo Modules：RN >= 0.68（性能更优，类型安全）

Instructions

操作步骤

Step 1: Plan Module Interface

步骤1：规划模块接口

Design JavaScript API:

javascript

// What you want to call from JS
import { NativeModules } from 'react-native';
const { MyModule } = NativeModules;

// Synchronous
const result = MyModule.getValue();

// Asynchronous (Promise)
const data = await MyModule.fetchData();

// With callback
MyModule.processData(input, (error, result) => {
  if (error) console.error(error);
  else console.log(result);
});

// Event emitter
MyModule.addListener('onUpdate', (event) => {
  console.log(event);
});

Keep bridge calls minimal:

Batch operations when possible
Avoid frequent small calls
Use events for continuous updates

设计JavaScript API：

javascript

// What you want to call from JS
import { NativeModules } from 'react-native';
const { MyModule } = NativeModules;

// Synchronous
const result = MyModule.getValue();

// Asynchronous (Promise)
const data = await MyModule.fetchData();

// With callback
MyModule.processData(input, (error, result) => {
  if (error) console.error(error);
  else console.log(result);
});

// Event emitter
MyModule.addListener('onUpdate', (event) => {
  console.log(event);
});

尽量减少桥接调用：

尽可能批量处理操作
避免频繁的小型调用
使用事件进行持续更新

Step 2: Create Module Structure

步骤2：创建模块结构

File structure:

MyModule/
├── ios/
│   ├── MyModule.h
│   ├── MyModule.m (or .swift)
│   └── MyModule-Bridging-Header.h (if Swift)
├── android/
│   └── src/main/java/com/mymodule/
│       ├── MyModulePackage.java
│       └── MyModule.java (or .kt)
├── js/
│   └── NativeMyModule.ts
└── package.json

文件结构：

MyModule/
├── ios/
│   ├── MyModule.h
│   ├── MyModule.m (or .swift)
│   └── MyModule-Bridging-Header.h (if Swift)
├── android/
│   └── src/main/java/com/mymodule/
│       ├── MyModulePackage.java
│       └── MyModule.java (or .kt)
├── js/
│   └── NativeMyModule.ts
└── package.json

Step 3: Implement iOS Module

步骤3：实现iOS模块

Objective-C (.h file):

objc

#import <React/RCTBridgeModule.h>
#import <React/RCTEventEmitter.h>

@interface MyModule : RCTEventEmitter <RCTBridgeModule>
@end

Objective-C (.m file):

objc

#import "MyModule.h"

@implementation MyModule

RCT_EXPORT_MODULE();

// Synchronous method
RCT_EXPORT_BLOCKING_SYNCHRONOUS_METHOD(getValue)
{
  return @"value";
}

// Async with Promise
RCT_EXPORT_METHOD(fetchData:(RCTPromiseResolveBlock)resolve
                  rejecter:(RCTPromiseRejectBlock)reject)
{
  // Perform operation
  if (success) {
    resolve(@{@"data": result});
  } else {
    reject(@"ERROR_CODE", @"Error message", error);
  }
}

// Async with callback
RCT_EXPORT_METHOD(processData:(NSString *)input
                  callback:(RCTResponseSenderBlock)callback)
{
  // Process data
  callback(@[[NSNull null], result]); // [error, result]
}

// Event emitter
- (NSArray<NSString *> *)supportedEvents
{
  return @[@"onUpdate"];
}

- (void)sendUpdate:(NSDictionary *)data
{
  [self sendEventWithName:@"onUpdate" body:data];
}

@end

Objective-C（.h文件）：

objc

#import <React/RCTBridgeModule.h>
#import <React/RCTEventEmitter.h>

@interface MyModule : RCTEventEmitter <RCTBridgeModule>
@end

Objective-C（.m文件）：

objc

#import "MyModule.h"

@implementation MyModule

RCT_EXPORT_MODULE();

// Synchronous method
RCT_EXPORT_BLOCKING_SYNCHRONOUS_METHOD(getValue)
{
  return @"value";
}

// Async with Promise
RCT_EXPORT_METHOD(fetchData:(RCTPromiseResolveBlock)resolve
                  rejecter:(RCTPromiseRejectBlock)reject)
{
  // Perform operation
  if (success) {
    resolve(@{@"data": result});
  } else {
    reject(@"ERROR_CODE", @"Error message", error);
  }
}

// Async with callback
RCT_EXPORT_METHOD(processData:(NSString *)input
                  callback:(RCTResponseSenderBlock)callback)
{
  // Process data
  callback(@[[NSNull null], result]); // [error, result]
}

// Event emitter
- (NSArray<NSString *> *)supportedEvents
{
  return @[@"onUpdate"];
}

- (void)sendUpdate:(NSDictionary *)data
{
  [self sendEventWithName:@"onUpdate" body:data];
}

@end

Step 4: Implement Android Module

步骤4：实现Android模块

Java module:

java

package com.mymodule;

import com.facebook.react.bridge.ReactApplicationContext;
import com.facebook.react.bridge.ReactContextBaseJavaModule;
import com.facebook.react.bridge.ReactMethod;
import com.facebook.react.bridge.Promise;
import com.facebook.react.bridge.Callback;
import com.facebook.react.bridge.WritableMap;
import com.facebook.react.bridge.Arguments;
import com.facebook.react.modules.core.DeviceEventManagerModule;

public class MyModule extends ReactContextBaseJavaModule {
    private ReactApplicationContext reactContext;

    public MyModule(ReactApplicationContext context) {
        super(context);
        this.reactContext = context;
    }

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

    // Synchronous method
    @ReactMethod(isBlockingSynchronousMethod = true)
    public String getValue() {
        return "value";
    }

    // Async with Promise
    @ReactMethod
    public void fetchData(Promise promise) {
        try {
            WritableMap result = Arguments.createMap();
            result.putString("data", "value");
            promise.resolve(result);
        } catch (Exception e) {
            promise.reject("ERROR_CODE", "Error message", e);
        }
    }

    // Async with callback
    @ReactMethod
    public void processData(String input, Callback callback) {
        try {
            String result = process(input);
            callback.invoke(null, result); // error, result
        } catch (Exception e) {
            callback.invoke(e.getMessage(), null);
        }
    }

    // Event emitter
    private void sendEvent(String eventName, WritableMap params) {
        reactContext
            .getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter.class)
            .emit(eventName, params);
    }
}

Package registration:

java

package com.mymodule;

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;

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

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

Java模块：

java

package com.mymodule;

import com.facebook.react.bridge.ReactApplicationContext;
import com.facebook.react.bridge.ReactContextBaseJavaModule;
import com.facebook.react.bridge.ReactMethod;
import com.facebook.react.bridge.Promise;
import com.facebook.react.bridge.Callback;
import com.facebook.react.bridge.WritableMap;
import com.facebook.react.bridge.Arguments;
import com.facebook.react.modules.core.DeviceEventManagerModule;

public class MyModule extends ReactContextBaseJavaModule {
    private ReactApplicationContext reactContext;

    public MyModule(ReactApplicationContext context) {
        super(context);
        this.reactContext = context;
    }

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

    // Synchronous method
    @ReactMethod(isBlockingSynchronousMethod = true)
    public String getValue() {
        return "value";
    }

    // Async with Promise
    @ReactMethod
    public void fetchData(Promise promise) {
        try {
            WritableMap result = Arguments.createMap();
            result.putString("data", "value");
            promise.resolve(result);
        } catch (Exception e) {
            promise.reject("ERROR_CODE", "Error message", e);
        }
    }

    // Async with callback
    @ReactMethod
    public void processData(String input, Callback callback) {
        try {
            String result = process(input);
            callback.invoke(null, result); // error, result
        } catch (Exception e) {
            callback.invoke(e.getMessage(), null);
        }
    }

    // Event emitter
    private void sendEvent(String eventName, WritableMap params) {
        reactContext
            .getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter.class)
            .emit(eventName, params);
    }
}

包注册：

java

package com.mymodule;

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;

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

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

Step 5: Link Module

步骤5：链接模块

Auto-linking (RN >= 0.60):

Create

package.json

in module root:

json

{
  "name": "react-native-my-module",
  "version": "1.0.0",
  "main": "js/index.js",
  "react-native": "js/index.js"
}

Manual linking (if needed):

iOS: Add to Podfile

ruby

pod 'MyModule', :path => '../node_modules/react-native-my-module'

Android: Add to

settings.gradle

gradle

include ':react-native-my-module'
project(':react-native-my-module').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-my-module/android')

自动链接（RN >= 0.60）：

在模块根目录创建

package.json

：

json

{
  "name": "react-native-my-module",
  "version": "1.0.0",
  "main": "js/index.js",
  "react-native": "js/index.js"
}

手动链接（如有需要）：

iOS：添加到Podfile

ruby

pod 'MyModule', :path => '../node_modules/react-native-my-module'

Android：添加到

settings.gradle

gradle

include ':react-native-my-module'
project(':react-native-my-module').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-my-module/android')

Step 6: Create TypeScript Interface

步骤6：创建TypeScript接口

typescript

// js/NativeMyModule.ts
import { NativeModules, NativeEventEmitter } from 'react-native';

interface MyModuleInterface {
  getValue(): string;
  fetchData(): Promise<{ data: string }>;
  processData(input: string, callback: (error: string | null, result: string | null) => void): void;
  addListener(eventName: string, listener: (event: any) => void): void;
  removeListeners(count: number): void;
}

const { MyModule } = NativeModules;
const eventEmitter = new NativeEventEmitter(MyModule);

export default MyModule as MyModuleInterface;
export { eventEmitter };

typescript

// js/NativeMyModule.ts
import { NativeModules, NativeEventEmitter } from 'react-native';

interface MyModuleInterface {
  getValue(): string;
  fetchData(): Promise<{ data: string }>;
  processData(input: string, callback: (error: string | null, result: string | null) => void): void;
  addListener(eventName: string, listener: (event: any) => void): void;
  removeListeners(count: number): void;
}

const { MyModule } = NativeModules;
const eventEmitter = new NativeEventEmitter(MyModule);

export default MyModule as MyModuleInterface;
export { eventEmitter };

Common Patterns

常见模式

Threading

线程处理

iOS (run on background thread):

objc

RCT_EXPORT_METHOD(heavyTask:(RCTPromiseResolveBlock)resolve
                  rejecter:(RCTPromiseRejectBlock)reject)
{
  dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{
    // Heavy operation
    NSString *result = [self performHeavyOperation];
    
    dispatch_async(dispatch_get_main_queue(), ^{
      resolve(result);
    });
  });
}

Android (run on background thread):

java

@ReactMethod
public void heavyTask(Promise promise) {
    new Thread(() -> {
        try {
            String result = performHeavyOperation();
            promise.resolve(result);
        } catch (Exception e) {
            promise.reject("ERROR", e);
        }
    }).start();
}

iOS（在后台线程运行）：

objc

RCT_EXPORT_METHOD(heavyTask:(RCTPromiseResolveBlock)resolve
                  rejecter:(RCTPromiseRejectBlock)reject)
{
  dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{
    // Heavy operation
    NSString *result = [self performHeavyOperation];
    
    dispatch_async(dispatch_get_main_queue(), ^{
      resolve(result);
    });
  });
}

Android（在后台线程运行）：

java

@ReactMethod
public void heavyTask(Promise promise) {
    new Thread(() -> {
        try {
            String result = performHeavyOperation();
            promise.resolve(result);
        } catch (Exception e) {
            promise.reject("ERROR", e);
        }
    }).start();
}

Data Type Conversion

数据类型转换

iOS:

objc

// JS -> Native
NSString *string = [RCTConvert NSString:value];
NSNumber *number = [RCTConvert NSNumber:value];
NSArray *array = [RCTConvert NSArray:value];
NSDictionary *dict = [RCTConvert NSDictionary:value];

// Native -> JS
return @{
  @"string": @"value",
  @"number": @(42),
  @"array": @[@"a", @"b"],
  @"dict": @{@"key": @"value"}
};

Android:

java

// JS -> Native (automatic)
String string = input;
int number = input;
ReadableArray array = input;
ReadableMap map = input;

// Native -> JS
WritableMap result = Arguments.createMap();
result.putString("string", "value");
result.putInt("number", 42);

WritableArray array = Arguments.createArray();
array.pushString("a");
array.pushString("b");
result.putArray("array", array);

iOS：

objc

// JS -> Native
NSString *string = [RCTConvert NSString:value];
NSNumber *number = [RCTConvert NSNumber:value];
NSArray *array = [RCTConvert NSArray:value];
NSDictionary *dict = [RCTConvert NSDictionary:value];

// Native -> JS
return @{
  @"string": @"value",
  @"number": @(42),
  @"array": @[@"a", @"b"],
  @"dict": @{@"key": @"value"}
};

Android：

java

// JS -> Native (automatic)
String string = input;
int number = input;
ReadableArray array = input;
ReadableMap map = input;

// Native -> JS
WritableMap result = Arguments.createMap();
result.putString("string", "value");
result.putInt("number", 42);

WritableArray array = Arguments.createArray();
array.pushString("a");
array.pushString("b");
result.putArray("array", array);

Error Handling

错误处理

iOS:

objc

RCT_EXPORT_METHOD(riskyOperation:(RCTPromiseResolveBlock)resolve
                  rejecter:(RCTPromiseRejectBlock)reject)
{
  NSError *error = nil;
  id result = [self performOperation:&error];
  
  if (error) {
    reject(@"OPERATION_FAILED", error.localizedDescription, error);
  } else {
    resolve(result);
  }
}

Android:

java

@ReactMethod
public void riskyOperation(Promise promise) {
    try {
        Object result = performOperation();
        promise.resolve(result);
    } catch (Exception e) {
        promise.reject("OPERATION_FAILED", e.getMessage(), e);
    }
}

iOS：

objc

RCT_EXPORT_METHOD(riskyOperation:(RCTPromiseResolveBlock)resolve
                  rejecter:(RCTPromiseRejectBlock)reject)
{
  NSError *error = nil;
  id result = [self performOperation:&error];
  
  if (error) {
    reject(@"OPERATION_FAILED", error.localizedDescription, error);
  } else {
    resolve(result);
  }
}

Android：

java

@ReactMethod
public void riskyOperation(Promise promise) {
    try {
        Object result = performOperation();
        promise.resolve(result);
    } catch (Exception e) {
        promise.reject("OPERATION_FAILED", e.getMessage(), e);
    }
}

Advanced

进阶内容

For detailed platform-specific guides:

iOS Bridge - Objective-C and Swift implementation
Android Bridge - Java and Kotlin implementation
Turbo Modules - New architecture modules

如需查看详细的平台专属指南：

iOS Bridge - Objective-C和Swift实现
Android Bridge - Java和Kotlin实现
Turbo Modules - 新架构模块

Troubleshooting

故障排查

Module not found:

Verify package.json configuration
Run
```
pod install
```
(iOS) or rebuild (Android)
Check module name matches in native code

Methods not available:

Ensure RCT_EXPORT_METHOD is used
Check method signature matches
Rebuild native code

Crashes on method call:

Check thread safety
Verify data type conversions
Add null checks
Review error handling

Events not received:

Verify supportedEvents (iOS)
Check event emitter setup
Ensure listeners are added before events fire

模块未找到：

验证package.json配置
运行
```
pod install
```
（iOS）或重新构建（Android）
检查原生代码中的模块名称是否匹配

方法不可用：

确保使用了RCT_EXPORT_METHOD
检查方法签名是否匹配
重新构建原生代码

调用方法时崩溃：

检查线程安全性
验证数据类型转换
添加空值检查
复查错误处理

未接收到事件：

验证supportedEvents（iOS）
检查事件发射器设置
确保在事件触发前已添加监听器

Best Practices

最佳实践

Minimize bridge calls: Batch operations, use events for updates
Type safety: Use TypeScript interfaces
Error handling: Always handle errors gracefully
Threading: Move heavy operations off main thread
Memory management: Clean up resources, remove listeners
Testing: Test on both iOS and Android
Documentation: Document API clearly
Versioning: Use semantic versioning

减少桥接调用：批量处理操作，使用事件进行更新
类型安全：使用TypeScript接口
错误处理：始终优雅地处理错误
线程处理：将繁重操作移出主线程
内存管理：清理资源，移除监听器
测试：在iOS和Android平台都进行测试
文档：清晰地记录API
版本控制：使用语义化版本控制