
前陣子做了一個 React Native 專案,過程中發現不少需要的組件 RN 並沒有提供,只能自己動手寫原生模塊給 JS 呼叫。折騰下來踩了不少坑,也感覺官方文件有些地方交代得不清不楚,於是乾脆寫成一篇實踐教學。
全文以「打造一個原生模塊」為主線,把編寫過程需要的知識串起來,並附上完整可運行的程式碼,方便對照除錯。除了實作本身,文章也講了如何把自己寫的原生模塊發佈到 npm 給其他人使用。希望大家都能把自己寫的模塊分享出來。
示例程式碼 GitHub:https://github.com/liuchungui/react-native-BGNativeModuleExample
react native init TestProject
建立完成後,用 Xcode 打開 TestProject/ios/ 下的 iOS 工程。
先在 React Native 專案的 node_modules 下開一個資料夾 react-native-BGNativeModuleExample,並在其中再開一個 ios 資料夾。
$ cd TestProject/node_modules $ mkdir react-native-BGNativeModuleExample $ cd react-native-BGNativeModuleExample $ mkdir ios
由於 RN 的組件都是一個個靜態庫,要發佈給別人用也必須做成靜態庫。用 Xcode 建立名為 BGNativeModuleExample 的靜態庫,再把裡面的檔案全部複製到 node_modules/react-native-BGNativeModuleExample/ios 下。
iOS 目錄結構:
|____BGNativeModuleExample | |____BGNativeModuleExample.h | |____BGNativeModuleExample.m |____BGNativeModuleExample.xcodeproj
接著手動把這個靜態庫連結進工程。
1、用 Xcode 打開靜態庫,加一條 Header Search Paths,值為 $(SRCROOT)/../../react-native/React,並設為 recursive。

2、把 BGNativeModuleExample 靜態庫工程拖進工程的 Library 中。

3、選中 TARGETS => TestProject => Build Settings => Link Binary With Libraries,加入 libBGNativeModuleExample.a。

這樣準備工作就完成了。之所以要先手工做一遍,是為了模擬 npm 連結的過程,把環境先搭好,避免發佈之後別人裝上卻找不到靜態庫。
選中 BGNativeModuleExample 靜態庫,在 .h 中引入 RCTBridgeModule.h,讓類遵循 RCTBridgeModule 協議。
//BGNativeModuleExample.h文件的內容如下 #import #import "RCTBridgeModule.h" @interface BGNativeModuleExample : NSObject @end
在 .m 中實作 RCTBridgeModule 協議時,類裡必須包含 RCT_EXPORT_MODULE() 宏。這個宏可以帶一個參數來指定 JS 端看到的模塊名稱,不指定則預設用類名。這裡我們指定為 BGNativeModuleExample。
RCT_EXPORT_MODULE(BGNativeModuleExample);
完成後就能在 JS 中取得這個模塊:
import { NativeModules } from 'react-native'; var BGNativeModuleExample = NativeModules.BGNativeModuleExample;要留意的是,RCT_EXPORT_MODULE 傳的參數不能是 OC 字串。若寫成 @"BGNativeModuleExample",那麼導出給 JS 的名字就會帶上引號,用 BGNativeModuleExample 自然找不到。遇到這種情況可以直接印出 NativeModules 來確認。
要導給 JS 的方法必須明確宣告,否則 RN 不會導出任何方法。宣告靠 RCT_EXPORT_METHOD() 宏:
RCT_EXPORT_METHOD(testPrint:(NSString *)name info:(NSDictionary *)info) { RCTLogInfo(@"%@: %@", name, info); }JS 端這樣呼叫:
BGNativeModuleExample.testPrint("Jack", { height: '1.78m', weight: '7kg' });RCT_EXPORT_METHOD() 支援所有標準 JSON 類型:
string(NSString)
number(NSInteger、float、double、CGFloat、NSNumber)
boolean(BOOL、NSNumber)
array(NSArray),元素為上述任一類型
map(NSDictionary),key 為 string,value 為上述任一類型
function(RCTResponseSenderBlock)
此外,凡是 RCTConvert 支援的類型也都能用。RCTConvert 還提供了一系列輔助函數,可把 JSON 值轉成對應的 Objective-C 類型。想深入了解可參考「原生模塊」相關文件。
官方文件對回調函數標了警告,說這部分還在實驗階段、實踐經驗不多。我實際使用下暫時沒遇到問題。這裡我們加一個 getNativeClass,把當前模塊的類名回傳給 JS:
RCT_EXPORT_METHOD(getNativeClass:(RCTResponseSenderBlock)callback) { callback(@[NSStringFromClass([self class])]); }JS 端接收:
BGNativeModuleExample.getNativeClass(name => { console.log("nativeClass: ", name); });原生模塊通常只該呼叫回調一次,但也可以把 callback 存起來留待日後呼叫——这在封裝那些透過 delegate 回傳結果的 iOS API 時最常見。
原生模塊也能用 Promise 來精簡程式碼,搭配 ES2016(ES7)的 async/await 效果更好。若橋接方法的最後兩個參數是 RCTPromiseResolveBlock 與 RCTPromiseRejectBlock,對應的 JS 方法就會回傳一個 Promise 物件。
下面用 Promise 判斷原生模塊是否回應某方法,有則 resolve YES,沒有則 reject 一個錯誤:
RCT_REMAP_METHOD(testRespondMethod, name:(NSString *)name resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject) { if([self respondsToSelector:NSSelectorFromString(name)]) { resolve(@YES); } else { reject(@"-1001", @"not respond this method", nil); } }JS 端有兩種呼叫方式。第一種是 then...catch:
BGNativeModuleExample.testRespondMethod("dealloc") .then(result => { console.log("result is ", result); }) .catch(error => { console.log(error); });第二種是 try...catch,但它會出現「Possible Unhandled Promise Rejection (id:0)」的警告。
async testRespond() { try { var result = BGNativeModuleExample.testRespondMethod("hell"); if(result) { console.log("respond this method"); } } catch (e) { console.log(e); } }注意:若用 Promise 不需要參數,OC 端把 name 那行去掉即可;需要多個參數時在 name 下面再加行,且行之間不需要逗號。
我們這個模塊不涉及 UI,所以另外開一條串行隊列給它:
return dispatch_queue_create("com.liuchungui.demo", DISPATCH_QUEUE_SERIAL);注意:模塊之間共享分發隊列。
methodQueue 會在模塊初始化時執行一次,之後由 RN 的橋接機制保存,所以你不需要自己保留隊列引用,除非想在模塊其他地方使用。但若想在多個模塊間共用同一條隊列,就得自己保存並回傳同一個隊列實例——單純回傳相同名稱的隊列是不夠的。
更多細節可參考:https://reactnative.cn/docs/0.24/native-modules-ios.html#content
原生模塊可以導出常量,讓 JS 端隨時存取。用這種方式傳靜態資料,可以避免多走一趟 bridge 往返。
- (NSDictionary *)constantsToExport { return @{ @"BGModuleName" : @"BGNativeModuleExample", TestEventName: TestEventName }; }JS 端印出來看看:
console.log("BGModuleName value is ", BGNativeModuleExample.BGModuleName);但要注意,這些常量只在初始化時導出一次,所以執行期間即使改變了 constantsToExport 的回傳值,也不會反映到 JS 環境。
即使 JS 沒有主動呼叫,原生模塊也能主動推事件給 JS,最直接的方式是透過 eventDispatcher。這裡我們開一個每秒觸發一次的計時器:
#import "BGNativeModuleExample.h" #import "RCTEventDispatcher.h" @implementation BGNativeModuleExample @synthesize bridge = _bridge; - (instancetype)init { if(self = [super init]) { [NSTimer scheduledTimerWithTimeInterval:1.0 target:self selector:@selector(sendEventToJS) userInfo:nil repeats:YES]; } return self; } - (void)receiveNotification:(NSNotification *)notification { [self.bridge.eventDispatcher sendAppEventWithName:TestEventName body:@{@"name": @"Jack"}]; } @endJS 端監聽:
NativeAppEventEmitter.addListener(BGNativeModuleExample.TestEventName, info => { console.log(info); });注意:OC 程式碼裡必須加上 @synthesize bridge = _bridge;,否則收事件時會拋出 -[BGNativeModuleExample bridge]: unrecognized selector sent to instance 的錯誤。
原生代碼寫到這裡就完成了,重點是以實作補足官方文件的空白。想進一步了解封裝細節,可以去看原生模塊相關文件或直接讀官方源碼。
在 GitHub 建立 react-native-BGNativeModuleExample 倉庫,並關聯到前面建立的同名目錄。
$ cd TestProject/node_modules/react-native-BGNativeModuleExample $ git init . $ git remote add origin https://github.com/liuchungui/react-native-BGNativeModuleExample.git
在 react-native-BGNativeModuleExample 下建立 index.js 作為整個模塊的入口,這裡只負責把原生模塊導出去。
//index.js import React, { NativeModules } from 'react-native'; module.exports = NativeModules.BGNativeModuleExample;發佈前需要一份 package.json,裡頭記錄名稱、版本、描述、依賴、作者、license 等資訊。在根目錄執行 npm init 即可產生,系統會逐項詢問,不想填的直接按 Enter 跳過。
$ npm init This utility will walk you through creating a package.json file. It only covers the most common items, and tries to guess sensible defaults. See `npm help json` for definitive documentation on these fields and exactly what they do. Use `npm install --save` afterwards to install a package and save it as a dependency in the package.json file. Press ^C at any time to quit. name: (react-native-BGNativeModuleExample)
填完系統會讓你確認內容,沒問題就輸入 yes。我產出的 package.json 如下:
{ "name": "react-native-nativemodule-example", "version": "1.0.0", "description": "", "main": "index.js", "scripts": { "test": "echo \"Error: no test specified\" && exit 1" }, "repository": { "type": "git", "url": "git+https://github.com/liuchungui/react-native-BGNativeModuleExample.git" }, "author": "", "license": "ISC", "bugs": { "url": "https://github.com/liuchungui/react-native-BGNativeModuleExample/issues" }, "homepage": "https://github.com/liuchungui/react-native-BGNativeModuleExample#readme" }如果你的原生模塊依賴其他原生模塊,需要在 package.json 補上依賴;這裡沒有相關依賴所以留空:
"dependencies": { }package.json 初始化好,就能發佈了。若還沒有 npm 帳號,需要先註冊一個,這個帳號會被寫入 npm 的本地設定,用於日後發佈。
$ npm adduser Username: your name Password: your password Email: yourmail@gmail.com
成功後認證資訊會存在 ~/.npmrc,可以用下面的指令確認目前登入的使用者:
$ npm whoami
接著正式發佈:
$npm publish + react-native-nativemodule-example@1.0.0
這樣模塊就上線到 npmjs.org 了。當然也別忘了把程式碼推到 GitHub:
$ git pull origin master $ git add . $ git commit -m 'add Project' $ git push origin master
有些檔案沒必要一起發佈,例如 Example 目錄,可以用 .npmignore 排除。我的內容如下:
Example/ .git .gitignore .idea
這樣 npm 發佈時就不會把 Example 包進去。
在 react-native-BGNativeModuleExample 下建一個 Example 用的 RN 工程,用 rnpm install react-native-nativemodule-example 安裝我們剛發佈的模塊。
$ rnpm install react-native-nativemodule-example TestProject@0.0.1 /Users/user/github/TestProject └── react-native-nativemodule-example@1.0.0 rnpm-link info Linking react-native-nativemodule-example ios dependency rnpm-link info iOS module react-native-nativemodule-example has been successfully linked rnpm-link info Module react-native-nativemodule-example has been successfully installed & linked
看到安裝與 link 都成功,就能在 JS 裡使用:
import BGNativeModuleExample from 'react-native-nativemodule-example'; BGNativeModuleExample.testPrint("Jack", { height: '1.78m', weight: '7kg' });README 非常重要。少了它,別人看到你的組件根本無從判斷用途。至少要交代這個組件做什麼、怎麼安裝、有哪些 API、使用方式為何。
新增功能或修完 bug 要發新版時,只要改 package.json 裡的 version,再執行一次 npm publish 即可。
全文分成兩塊:一是原生模塊的編寫要點,二是把它發佈到 npm 的完整流程。
參考資料:如何發佈 Node 模塊到 NPM 社區、原生模塊官方文件。