您现在的位置: IOS教程網 >> IOS系統 >  >> iOS 程式開發 >> iOS 開發基礎

React Native 原生模塊開發與發佈 npm 全流程

編輯:iOS 開發基礎

前陣子做了一個 React Native 專案,過程中發現不少需要的組件 RN 並沒有提供,只能自己動手寫原生模塊給 JS 呼叫。折騰下來踩了不少坑,也感覺官方文件有些地方交代得不清不楚,於是乾脆寫成一篇實踐教學。

全文以「打造一個原生模塊」為主線,把編寫過程需要的知識串起來,並附上完整可運行的程式碼,方便對照除錯。除了實作本身,文章也講了如何把自己寫的原生模塊發佈到 npm 給其他人使用。希望大家都能把自己寫的模塊分享出來。

示例程式碼 GitHub:https://github.com/liuchungui/react-native-BGNativeModuleExample

準備工作

建立 React Native 專案

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 連結的過程,把環境先搭好,避免發佈之後別人裝上卻找不到靜態庫。

一、編寫原生模塊

1、建立原生模塊

選中 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 來確認。

2、為原生模塊添加方法

要導給 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' });

3、參數類型

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 類型。想深入了解可參考「原生模塊」相關文件。

4、回調函數

官方文件對回調函數標了警告,說這部分還在實驗階段、實踐經驗不多。我實際使用下暫時沒遇到問題。這裡我們加一個 getNativeClass,把當前模塊的類名回傳給 JS:

RCT_EXPORT_METHOD(getNativeClass:(RCTResponseSenderBlock)callback) {   callback(@[NSStringFromClass([self class])]); }

JS 端接收:

BGNativeModuleExample.getNativeClass(name => {   console.log("nativeClass: ", name); });

原生模塊通常只該呼叫回調一次,但也可以把 callback 存起來留待日後呼叫——这在封裝那些透過 delegate 回傳結果的 iOS API 時最常見。

5、Promises

原生模塊也能用 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 下面再加行,且行之間不需要逗號。

6、多執行緒

我們這個模塊不涉及 UI,所以另外開一條串行隊列給它:

return dispatch_queue_create("com.liuchungui.demo", DISPATCH_QUEUE_SERIAL);

注意:模塊之間共享分發隊列。

methodQueue 會在模塊初始化時執行一次,之後由 RN 的橋接機制保存,所以你不需要自己保留隊列引用,除非想在模塊其他地方使用。但若想在多個模塊間共用同一條隊列,就得自己保存並回傳同一個隊列實例——單純回傳相同名稱的隊列是不夠的。

更多細節可參考:https://reactnative.cn/docs/0.24/native-modules-ios.html#content

7、導出常量

原生模塊可以導出常量,讓 JS 端隨時存取。用這種方式傳靜態資料,可以避免多走一趟 bridge 往返。

- (NSDictionary *)constantsToExport {   return @{ @"BGModuleName" : @"BGNativeModuleExample",                TestEventName: TestEventName             }; }

JS 端印出來看看:

console.log("BGModuleName value is ", BGNativeModuleExample.BGModuleName);

但要注意,這些常量只在初始化時導出一次,所以執行期間即使改變了 constantsToExport 的回傳值,也不會反映到 JS 環境。

8、給 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"}]; } @end

JS 端監聽:

NativeAppEventEmitter.addListener(BGNativeModuleExample.TestEventName, info => {       console.log(info);     });

注意:OC 程式碼裡必須加上 @synthesize bridge = _bridge;,否則收事件時會拋出 -[BGNativeModuleExample bridge]: unrecognized selector sent to instance 的錯誤。

原生代碼寫到這裡就完成了,重點是以實作補足官方文件的空白。想進一步了解封裝細節,可以去看原生模塊相關文件或直接讀官方源碼。

二、發佈上線

1、建立 GitHub 倉庫

在 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

2、建立模塊入口檔案

在 react-native-BGNativeModuleExample 下建立 index.js 作為整個模塊的入口,這裡只負責把原生模塊導出去。

//index.js import React, { NativeModules } from 'react-native'; module.exports = NativeModules.BGNativeModuleExample;

3、發佈到 npm

發佈前需要一份 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 包進去。

4、補上 Example 並驗證、撰寫 README

在 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' });

5、別忘了寫 README

README 非常重要。少了它,別人看到你的組件根本無從判斷用途。至少要交代這個組件做什麼、怎麼安裝、有哪些 API、使用方式為何。

6、升級並發佈新版本

新增功能或修完 bug 要發新版時,只要改 package.json 裡的 version,再執行一次 npm publish 即可。

總結

全文分成兩塊:一是原生模塊的編寫要點,二是把它發佈到 npm 的完整流程。

參考資料:如何發佈 Node 模塊到 NPM 社區、原生模塊官方文件。

  1. 上一篇文章:
  2. 下一篇文章:
蘋果刷機越獄教程| IOS教程問題解答| IOS技巧綜合| IOS7技巧| IOS8教程
Copyright © IOS教程網 All Rights Reserved