React Native 集成原生Android功能

React Native 集成原生功能完整指南

前言

在 React Native 开发中，我们经常需要使用设备的原生功能，比如蓝牙、打印机等。本文将以集成打印机功能为例，详细介绍如何在 React Native 项目中集成 Android 原生功能。

集成步骤概述

1. 创建原生模块（Native Module）
2. 创建包装类（Package）
3. 在 Android 项目中注册 Package
4. 在 JavaScript/TypeScript 端创建接口 (非必须)
5. 在 React Native 代码中调用原生功能

详细实现

1. 创建原生模块

首先需要创建一个继承自 ReactContextBaseJavaModule 的类。

这个类的主要作用是：

• 建立 RN 和原生代码之间的通信桥接
• 提供原生功能的具体实现
• 通过注解暴露方法给 JS 调用

public class ZICOXModule extends ReactContextBaseJavaModule {
    @Override
    public String getName() {
        return "ZICOXPrint"; // 在JS中通过 NativeModules.ZICOXPrint 调用
    }

    @ReactMethod
    public void print(String text, Promise promise) {
        // 打印功能实现
        try {
            // 打印逻辑
            promise.resolve(true);
        } catch (Exception e) {
            promise.reject("PRINT_ERROR", e.getMessage());
        }
    }
}

其中getName() 返回值是暴露给js调用的模块名称

@ReactMethod 是暴露给js调用的方法

2. 创建包装类

包装类作为模块的容器，负责：

• 管理和注册原生模块
• 控制模块的生命周期
• 提供模块列表给 RN 系统

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

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

3. 注册 Package

在 Android 项目的 MainApplication.java 中注册包装类，使 RN 能够识别和加载这些原生模块：

public class MainApplication extends Application implements ReactApplication {
    @Override
    protected List<ReactPackage> getPackages() {
        List<ReactPackage> packages = new PackageList(this).getPackages();
        packages.add(new ZICOXPackage()); // 添加自定义Package
        return packages;
    }
}

4. 创建 TypeScript 接口

为了更好地使用原生功能，我们需要在 JS 端创建对应的接口和包装器：

// 定义接口
interface ZICOXPrinterInterface {
  print(text: string): Promise<boolean>;
  connect(address: string): Promise<void>;
}

// 声明模块
declare module 'react-native' {
  interface NativeModulesStatic {
    ZICOXPrint: ZICOXPrinterInterface;
  }
}

// 创建包装器
import { NativeModules } from 'react-native';

const { ZICOXPrint } = NativeModules;

export const ZICOXPrinter = {
  async print(text: string): Promise<boolean> {
    try {
      return await ZICOXPrint.print(text);
    } catch (error) {
      console.error('打印失败:', error);
      throw error;
    }
  },
  // ... 其他方法
};

5. 在 React 组件中使用

最后，我们可以在 React 组件中方便地调用这些原生功能：

import React from 'react';
import { Button } from 'react-native';
import { ZICOXPrinter } from '../native/ZICOXPrinter';

export const PrintButton: React.FC = () => {
  const handlePrint = async () => {
    try {
      await ZICOXPrinter.connect('printer_address');
      const result = await ZICOXPrinter.print('要打印的内容');
      if (result) {
        console.log('打印成功');
      }
    } catch (error) {
      console.error('操作失败:', error);
    }
  };

  return <Button title="打印" onPress={handlePrint} />;
};

注意事项

1. 模块名称要保持一致

   • Java 端的 getName() 返回值
   • TypeScript 接口声明中的模块名

2. 错误处理

   • 原生端使用 Promise 处理异步操作
   • JS 端做好错误捕获和提示

3. 类型安全

   • 使用 TypeScript 接口确保类型安全
   • 明确定义参数和返回值类型

总结

通过以上步骤，我们就完成了 React Native 项目中原生功能的完整集成。这种方式不仅保证了类型安全，还提供了良好的代码组织结构和错误处理机制。虽然初次集成可能略显复杂，但这种模式可以在后续开发中复用，大大提高开发效率。