1. 項(xiàng)目緣起為什么要在uni-app里折騰iOS原生插件如果你用uni-app做過(guò)跨端開(kāi)發(fā)尤其是涉及到一些需要深度調(diào)用iOS原生能力的場(chǎng)景比如藍(lán)牙連接、消息推送、音視頻處理或者想用一些App Store里沒(méi)有的私有API那你大概率會(huì)遇到一個(gè)瓶頸uni-app官方提供的API不夠用了。這時(shí)候你可能會(huì)聽(tīng)到一個(gè)詞——UTS插件。我第一次接觸UTS是在一個(gè)智能硬件的項(xiàng)目里。我們需要在uni-app開(kāi)發(fā)的微信小程序和App端實(shí)現(xiàn)一套穩(wěn)定、低延遲的藍(lán)牙通信協(xié)議。小程序端還好uniapp的API基本夠用。但一到iOS App這邊問(wèn)題就來(lái)了官方的uni.connectBluetoothDevice在連接某些特定芯片的設(shè)備時(shí)握手成功率低得感人更別提那些復(fù)雜的自定義數(shù)據(jù)分包、校驗(yàn)和重傳邏輯了。HBuilderX的控制臺(tái)里飄紅的錯(cuò)誤日志和測(cè)試同事那邊“iOS又連不上了”的反饋成了那段時(shí)間的日常。當(dāng)時(shí)擺在我面前的路有幾條一是用uni-app的renderjs或wxs去硬寫(xiě)但性能和數(shù)據(jù)交互是硬傷二是用老辦法寫(xiě)一個(gè)uni_modules的Native.js插件但這東西對(duì)iOS原生開(kāi)發(fā)者的要求不低而且調(diào)試起來(lái)像在走鋼絲三是干脆放棄跨端原生iOS和Android各寫(xiě)一套——這顯然違背了用uni-app的初衷。直到團(tuán)隊(duì)里的架構(gòu)師提到了DCloud新推的UTSUni-TypeScript。他說(shuō)這玩意兒能讓你用TypeScript的語(yǔ)法直接調(diào)用iOS的Swift/Objective-C和Android的Kotlin/Java。聽(tīng)起來(lái)有點(diǎn)像“魔法”將跨端開(kāi)發(fā)的便利性和原生代碼的性能、能力結(jié)合在了一起。我們的藍(lán)牙難題似乎看到了用一套代碼主要是UTS層邏輯解決兩端原生適配問(wèn)題的曙光。這就是我決定深入研究并親手打造一個(gè)UTS iOS插件的開(kāi)始。簡(jiǎn)單來(lái)說(shuō)UTS插件就是uni-app生態(tài)中用于擴(kuò)展原生能力的“橋梁”。它不像uni_modules那樣只是封裝網(wǎng)頁(yè)組件或純JS邏輯而是真的能編譯成iOS的.framework或Android的.aar讓你的TypeScript代碼擁有直接操作設(shè)備硬件、調(diào)用系統(tǒng)私有API的能力。對(duì)于那些追求極致性能、或需要實(shí)現(xiàn)uni-app官方API尚未覆蓋功能的開(kāi)發(fā)者來(lái)說(shuō)UTS幾乎是目前的最優(yōu)解。2. UTS iOS插件開(kāi)發(fā)環(huán)境搭建與踩坑實(shí)錄理論很美好但第一步搭建環(huán)境就給了我一個(gè)下馬威。UTS插件的開(kāi)發(fā)和普通的uni-app項(xiàng)目差別很大它更接近于一個(gè)原生庫(kù)的開(kāi)發(fā)流程。2.1 核心工具鏈選擇Xcode與HBuilderX的版本之痛首先明確開(kāi)發(fā)UTS iOS插件你離不開(kāi)兩個(gè)核心工具HBuilderX和Xcode。但它們的版本兼容性是第一個(gè)大坑。HBuilderX必須使用3.6.5及以上的Alpha版本。正式版是不支持UTS插件開(kāi)發(fā)和真機(jī)調(diào)試的。我一開(kāi)始用了3.5的正式版創(chuàng)建UTS插件項(xiàng)目后根本找不到編譯和運(yùn)行的按鈕。切換到Alpha版后插件項(xiàng)目目錄下才會(huì)出現(xiàn)正確的運(yùn)行和調(diào)試菜單。Xcode推薦使用14.x或15.x的穩(wěn)定版本。這里有個(gè)血淚教訓(xùn)我電腦上之前為了兼容一個(gè)老項(xiàng)目裝了Xcode 10對(duì)應(yīng)iOS 12 SDK。當(dāng)我嘗試編譯UTS插件時(shí)控制臺(tái)報(bào)了一個(gè)詭異的錯(cuò)誤xcode 10 (ios 12) does not contain libstdc6.0.9。這個(gè)錯(cuò)誤信息極具誤導(dǎo)性它讓你以為是缺少某個(gè)C庫(kù)。實(shí)際上根本原因是Xcode版本太低其內(nèi)置的編譯器和SDK無(wú)法兼容UTS插件編譯所需的新特性。UTS插件在編譯時(shí)會(huì)依賴較新的Swift Module穩(wěn)定性和Clang編譯器特性老版本Xcode無(wú)法滿足。解決方案就是老老實(shí)實(shí)從官網(wǎng)下載安裝最新穩(wěn)定版的Xcode并確保命令行工具xcode-select --install也指向新版本。注意在Mac上可以通過(guò)sudo xcode-select -s /Applications/Xcode.app/Contents/Developer來(lái)切換當(dāng)前生效的Xcode路徑確保HBuilderX調(diào)用的是正確的版本。2.2 項(xiàng)目結(jié)構(gòu)初窺從零創(chuàng)建一個(gè)UTS插件在HBuilderX Alpha版中新建項(xiàng)目時(shí)選擇“UTS插件”模板。生成的項(xiàng)目結(jié)構(gòu)是理解UTS如何工作的關(guān)鍵my-uts-plugin/ ├── uni_modules/ # 插件存放目錄 │ └── my-uts-plugin/ # 你的插件目錄 │ ├── uts/ │ │ ├── index.uts # UTS層主入口用TypeScript編寫(xiě)跨平臺(tái)邏輯 │ │ ├── ios/ │ │ │ ├── index.uts # iOS平臺(tái)特有的UTS實(shí)現(xiàn) │ │ │ └── Swift/ │ │ │ └── MyUtsPlugin.swift # 真正的Swift原生代碼 │ │ └── android/ │ │ └── index.uts # Android平臺(tái)特有的UTS實(shí)現(xiàn) │ ├── package.json # 插件配置文件聲明名稱、依賴、權(quán)限等 │ └── ... (其他資源文件) └── ... (其他項(xiàng)目文件)這個(gè)結(jié)構(gòu)清晰地展示了UTS的分層思想頂層index.uts這里寫(xiě)公共的TypeScript接口和邏輯。如果某個(gè)功能iOS和Android實(shí)現(xiàn)完全一樣可以寫(xiě)在這里。平臺(tái)層ios/index.uts和android/index.uts在這里寫(xiě)平臺(tái)特定的TypeScript邏輯。更重要的是在這里你可以通過(guò)UTSiOS或UTSAndroid命名空間直接調(diào)用下一層的原生代碼。原生層Swift/或Kotlin/目錄這里就是純正的Swift或Kotlin代碼了。你在平臺(tái)層UTS文件中調(diào)用的方法最終會(huì)在這里被實(shí)現(xiàn)。2.3 第一個(gè)“Hello World”插件與調(diào)試技巧讓我們實(shí)現(xiàn)一個(gè)最簡(jiǎn)單的功能在iOS端彈出一個(gè)原生Alert對(duì)話框。這能幫你打通整個(gè)調(diào)用鏈路。第一步在uni_modules/my-uts-plugin/uts/ios/index.uts中編寫(xiě)平臺(tái)層代碼。// uni_modules/my-uts-plugin/uts/ios/index.uts import { UTSiOS } from uts-ios; // 聲明一個(gè)平臺(tái)特有的函數(shù) export function showNativeAlert(title: string, message: string): void { // 關(guān)鍵這里調(diào)用原生Swift類(lèi)的方法 UTSiOS.invoke(MyUtsPlugin, showAlertWithTitle:message:, [title, message]); }第二步在uni_modules/my-uts-plugin/uts/ios/Swift/MyUtsPlugin.swift中編寫(xiě)原生Swift代碼。// uni_modules/my-uts-plugin/uts/ios/Swift/MyUtsPlugin.swift import Foundation import UIKit objc(MyUtsPlugin) public class MyUtsPlugin: NSObject { // 這個(gè)方法必須使用objc暴露且參數(shù)類(lèi)型要與UTS調(diào)用匹配 objc public static func showAlertWithTitle(_ title: String, message: String) - Void { // 注意原生代碼運(yùn)行在主線程但UTS調(diào)用可能來(lái)自JS線程。UI操作必須切回主線程。 DispatchQueue.main.async { let alert UIAlertController(title: title, message: message, preferredStyle: .alert) alert.addAction(UIAlertAction(title: OK, style: .default)) // 獲取當(dāng)前活動(dòng)的UIViewController是關(guān)鍵難點(diǎn) if let rootVC UIApplication.shared.keyWindow?.rootViewController { // 處理可能存在的presentedViewController var topVC rootVC while let presentedVC topVC.presentedViewController { topVC presentedVC } topVC.present(alert, animated: true) } } } }第三步在公共入口uni_modules/my-uts-plugin/uts/index.uts中統(tǒng)一暴露接口。// uni_modules/my-uts-plugin/uts/index.uts // 導(dǎo)出公共接口如果各平臺(tái)實(shí)現(xiàn)不同可以在這里做兼容判斷 export * from ./ios/index.uts // 如果有android實(shí)現(xiàn)也可以在這里導(dǎo)出 // export * from ./android/index.uts第四步在uni-app的Vue頁(yè)面中調(diào)用。template view button clickshowAlert點(diǎn)擊彈出原生Alert/button /view /template script // 引入U(xiǎn)TS插件 import { showNativeAlert } from /uni_modules/my-uts-plugin/uts/index.uts export default { methods: { showAlert() { // 像調(diào)用普通JS函數(shù)一樣調(diào)用 showNativeAlert(UTS提示, 你好這是來(lái)自Swift的原生彈窗); } } } /script調(diào)試過(guò)程中的核心技巧日志輸出在Swift代碼中使用print(...)或os_log(...)。輸出會(huì)顯示在HBuilderX的“運(yùn)行”-“運(yùn)行到iOS設(shè)備”的控制臺(tái)里而不是瀏覽器的Console。真機(jī)調(diào)試UTS插件必須運(yùn)行到真機(jī)或模擬器才能測(cè)試。選擇“運(yùn)行”-“運(yùn)行到iOS App基座”。首次運(yùn)行會(huì)編譯較久因?yàn)樗枰獙TS和Swift代碼編譯成原生框架。錯(cuò)誤定位如果插件調(diào)用失敗HBuilderX控制臺(tái)通常會(huì)給出比較清晰的錯(cuò)誤棧指出是UTS編譯錯(cuò)誤還是Swift運(yùn)行時(shí)錯(cuò)誤。仔細(xì)閱讀錯(cuò)誤信息大部分是語(yǔ)法或類(lèi)型不匹配問(wèn)題。3. 實(shí)戰(zhàn)封裝一個(gè)iOS藍(lán)牙低功耗BLE通信插件回到最初的問(wèn)題我們?nèi)绾斡肬TS封裝一個(gè)更穩(wěn)定、功能更強(qiáng)的BLE插件這里分享核心部分的實(shí)現(xiàn)思路和代碼這比簡(jiǎn)單的Alert要復(fù)雜得多涉及狀態(tài)管理、回調(diào)處理和原生API的深度使用。3.1 設(shè)計(jì)插件接口從JS到原生的協(xié)議映射首先我們要設(shè)計(jì)一個(gè)給Vue頁(yè)面使用的、友好的JavaScript API。我們希望它是這樣的// 在Vue組件中理想的使用方式 import { BLEManager } from /uni_modules/my-ble-plugin const ble new BLEManager(); ble.onDeviceFound(device console.log(發(fā)現(xiàn)設(shè)備:, device)); ble.onConnected(() console.log(連接成功)); ble.onDataReceived(data console.log(收到數(shù)據(jù):, data)); ble.startScan([FFE0, FFE1]); // 掃描指定服務(wù)的設(shè)備 ble.connectToDevice(deviceId); ble.writeDataToCharacteristic(serviceUUID, charUUID, dataArray);為了實(shí)現(xiàn)這個(gè)我們需要在UTS層定義好類(lèi)型和接口。在uts/index.uts中定義公共類(lèi)型和接口// uni_modules/my-ble-plugin/uts/index.uts // 定義設(shè)備信息結(jié)構(gòu) export interface BLEDevice { deviceId: string; name: string; rssi: number; advertisementData?: Recordstring, any; } // 定義特征值信息結(jié)構(gòu) export interface BLECharacteristic { serviceUUID: string; characteristicUUID: string; properties: string[]; // e.g., [read, write, notify] } // 定義插件主類(lèi) export class BLEManager { private static instance: BLEManager; private constructor() {} static getInstance(): BLEManager { if (!BLEManager.instance) { BLEManager.instance new BLEManager(); } return BLEManager.instance; } // 平臺(tái)特定的實(shí)現(xiàn)會(huì)在ios/index.uts中 public startScan(serviceUUIDs?: string[]): void { /* 由平臺(tái)實(shí)現(xiàn) */ } public stopScan(): void { /* 由平臺(tái)實(shí)現(xiàn) */ } public connect(deviceId: string): void { /* 由平臺(tái)實(shí)現(xiàn) */ } public disconnect(): void { /* 由平臺(tái)實(shí)現(xiàn) */ } public write(serviceUUID: string, characteristicUUID: string, data: ArrayBuffer): Promiseboolean { /* 由平臺(tái)實(shí)現(xiàn) */ } // 事件回調(diào) public onDeviceFound(callback: (device: BLEDevice) void): void { /* 由平臺(tái)實(shí)現(xiàn) */ } public onConnected(callback: () void): void { /* 由平臺(tái)實(shí)現(xiàn) */ } // ... 其他事件 }3.2 iOS平臺(tái)層實(shí)現(xiàn)橋接Swift核心邏輯接下來(lái)在iOS平臺(tái)層我們需要實(shí)現(xiàn)上述接口并調(diào)用Swift代碼。這里的關(guān)鍵是處理異步回調(diào)。iOS的CoreBluetooth框架是高度異步的我們需要把CBCentralManager的回調(diào)Delegate轉(zhuǎn)換成UTS/JS能理解的Promise或Callback。在uts/ios/index.uts中實(shí)現(xiàn)平臺(tái)層// uni_modules/my-ble-plugin/uts/ios/index.uts import { UTSiOS } from uts-ios; import { BLEDevice, BLEManager } from ../index.uts; // 單例模式實(shí)現(xiàn) class BLEManageriOS extends BLEManager { private deviceFoundCallback: ((device: BLEDevice) void) | null null; private connectedCallback: (() void) | null null; // ... 其他回調(diào)存儲(chǔ) constructor() { super(); // 初始化原生管理器 UTSiOS.invoke(MyBLEManager, shared); } public startScan(serviceUUIDs?: string[]): void { const args serviceUUIDs ? [serviceUUIDs] : []; UTSiOS.invoke(MyBLEManager, startScanWithServiceUUIDs:, args); } public stopScan(): void { UTSiOS.invoke(MyBLEManager, stopScan); } public connect(deviceId: string): void { UTSiOS.invoke(MyBLEManager, connectToDevice:, [deviceId]); } // 關(guān)鍵注冊(cè)回調(diào)函數(shù)給原生層調(diào)用 public onDeviceFound(callback: (device: BLEDevice) void): void { this.deviceFoundCallback callback; // 告訴原生層當(dāng)發(fā)現(xiàn)設(shè)備時(shí)調(diào)用一個(gè)名為 _onDeviceFoundFromNative 的全局函數(shù) UTSiOS.invoke(MyBLEManager, setDeviceFoundHandler, []); } // 這個(gè)函數(shù)將被Swift代碼直接調(diào)用通過(guò)UTS的機(jī)制 public _onDeviceFoundFromNative(deviceInfo: any): void { if (this.deviceFoundCallback) { const device: BLEDevice { deviceId: deviceInfo.identifier, name: deviceInfo.name || Unknown, rssi: deviceInfo.rssi }; this.deviceFoundCallback(device); } } // ... 實(shí)現(xiàn)其他方法 } // 導(dǎo)出平臺(tái)特定的單例 export const bleManager: BLEManager new BLEManageriOS();3.3 Swift原生層核心封裝CoreBluetooth這是最核心的部分我們需要用Swift完整地封裝CBCentralManager。在uts/ios/Swift/MyBLEManager.swift中// uni_modules/my-ble-plugin/uts/ios/Swift/MyBLEManager.swift import CoreBluetooth import Foundation // 定義一個(gè)協(xié)議用于將Swift事件傳遞回UTS/JS層 objc protocol MyBLEManagerJSExport { func _onDeviceFoundFromNative(deviceInfo: [String: Any]) func _onConnectedFromNative() func _onDisconnectedFromNative() func _onDataReceivedFromNative(data: [UInt8], serviceUUID: String, charUUID: String) } objc(MyBLEManager) public class MyBLEManager: NSObject { objc public static let shared MyBLEManager() private var centralManager: CBCentralManager! private var connectedPeripheral: CBPeripheral? private var discoveredPeripherals: [UUID: CBPeripheral] [:] // 持有對(duì)JS導(dǎo)出對(duì)象的弱引用UTS運(yùn)行時(shí)提供 private weak var jsHandler: MyBLEManagerJSExport? private override init() { super.init() // 在后臺(tái)隊(duì)列運(yùn)行避免阻塞主線程 let centralQueue DispatchQueue(label: com.myapp.ble.central) centralManager CBCentralManager(delegate: self, queue: centralQueue) } // MARK: - Public Methods called from UTS objc public func startScanWithServiceUUIDs(_ serviceUUIDStrings: [String]?) { guard centralManager.state .poweredOn else { print(藍(lán)牙未開(kāi)啟) return } var serviceUUIDs: [CBUUID]? if let strings serviceUUIDStrings { serviceUUIDs strings.map { CBUUID(string: $0) } } // 允許重復(fù)發(fā)現(xiàn)用于RSSI更新 centralManager.scanForPeripherals(withServices: serviceUUIDs, options: [CBCentralManagerScanOptionAllowDuplicatesKey: true]) } objc public func stopScan() { centralManager.stopScan() } objc public func connectToDevice(_ deviceId: String) { guard let uuid UUID(uuidString: deviceId), let peripheral discoveredPeripherals[uuid] else { print(未找到設(shè)備: \(deviceId)) return } centralManager.connect(peripheral, options: nil) } // 設(shè)置回調(diào)處理器 objc public func setDeviceFoundHandler() { // 這里UTS運(yùn)行時(shí)會(huì)自動(dòng)將實(shí)現(xiàn)了MyBLEManagerJSExport協(xié)議的對(duì)象傳遞進(jìn)來(lái) // 我們通過(guò)一個(gè)內(nèi)部方法獲取它具體機(jī)制由UTS橋接層處理這里簡(jiǎn)化表示 self.jsHandler getJSHandler() // 假設(shè)的獲取方法 } // MARK: - 將事件傳遞回JS private func notifyDeviceFound(peripheral: CBPeripheral, rssi: NSNumber, advertisementData: [String: Any]) { let deviceInfo: [String: Any] [ identifier: peripheral.identifier.uuidString, name: peripheral.name ?? advertisementData[CBAdvertisementDataLocalNameKey] as? String ?? , rssi: rssi.intValue, advertisementData: advertisementData ] // 切換到主線程調(diào)用JS方法 DispatchQueue.main.async { self.jsHandler?._onDeviceFoundFromNative(deviceInfo: deviceInfo) } } private func notifyConnected() { DispatchQueue.main.async { self.jsHandler?._onConnectedFromNative() } } } // MARK: - CBCentralManagerDelegate extension MyBLEManager: CBCentralManagerDelegate { public func centralManagerDidUpdateState(_ central: CBCentralManager) { print(藍(lán)牙狀態(tài)更新: \(central.state.rawValue)) } public func centralManager(_ central: CBCentralManager, didDiscover peripheral: CBPeripheral, advertisementData: [String : Any], rssi RSSI: NSNumber) { discoveredPeripherals[peripheral.identifier] peripheral notifyDeviceFound(peripheral: peripheral, rssi: RSSI, advertisementData: advertisementData) } public func centralManager(_ central: CBCentralManager, didConnect peripheral: CBPeripheral) { connectedPeripheral peripheral peripheral.delegate self // 設(shè)置Peripheral委托 peripheral.discoverServices(nil) // 發(fā)現(xiàn)所有服務(wù) notifyConnected() } // ... 實(shí)現(xiàn)其他CBCentralManagerDelegate方法 } // MARK: - CBPeripheralDelegate extension MyBLEManager: CBPeripheralDelegate { public func peripheral(_ peripheral: CBPeripheral, didDiscoverServices error: Error?) { guard let services peripheral.services else { return } for service in services { peripheral.discoverCharacteristics(nil, for: service) } } public func peripheral(_ peripheral: CBPeripheral, didDiscoverCharacteristicsFor service: CBService, error: Error?) { // 處理發(fā)現(xiàn)的特征值例如訂閱通知等 guard let characteristics service.characteristics else { return } for characteristic in characteristics { if characteristic.properties.contains(.notify) { peripheral.setNotifyValue(true, for: characteristic) } } } public func peripheral(_ peripheral: CBPeripheral, didUpdateValueFor characteristic: CBCharacteristic, error: Error?) { // 收到數(shù)據(jù)來(lái)自讀操作或通知 if let data characteristic.value { let byteArray [UInt8](data) // 通知JS層 DispatchQueue.main.async { self.jsHandler?._onDataReceivedFromNative(data: byteArray, serviceUUID: characteristic.service?.uuid.uuidString ?? , charUUID: characteristic.uuid.uuidString) } } } // ... 實(shí)現(xiàn)其他CBPeripheralDelegate方法如寫(xiě)入回調(diào)、斷開(kāi)連接等 }這個(gè)Swift類(lèi)做了幾件關(guān)鍵事單例管理確保只有一個(gè)CBCentralManager實(shí)例。狀態(tài)與隊(duì)列管理在自定義隊(duì)列處理藍(lán)牙事件不阻塞UI。橋接回調(diào)通過(guò)一個(gè)假設(shè)的jsHandler實(shí)際由UTS運(yùn)行時(shí)注入將原生事件發(fā)現(xiàn)設(shè)備、連接成功、收到數(shù)據(jù)傳遞回UTS/JS層。完整的BLE生命周期實(shí)現(xiàn)了掃描、連接、發(fā)現(xiàn)服務(wù)/特征、訂閱通知、接收數(shù)據(jù)等核心流程。3.4 在uni-app頁(yè)面中集成與使用最后在Vue頁(yè)面中你就可以像使用一個(gè)純JavaScript庫(kù)一樣使用這個(gè)功能強(qiáng)大的BLE插件了template view classcontent button clickstartScanning開(kāi)始掃描藍(lán)牙設(shè)備/button view v-fordevice in devices :keydevice.deviceId clickconnectDevice(device) text{{ device.name }} ({{ device.deviceId }}) - RSSI: {{ device.rssi }}/text /view button clicksendData :disabled!isConnected發(fā)送測(cè)試數(shù)據(jù)/button /view /template script import { bleManager } from /uni_modules/my-ble-plugin/uts/index.uts export default { data() { return { devices: [], isConnected: false, connectedDeviceId: null } }, onLoad() { this.setupBLEListeners(); }, methods: { setupBLEListeners() { bleManager.onDeviceFound((device) { console.log(發(fā)現(xiàn)設(shè)備:, device); // 去重 if (!this.devices.find(d d.deviceId device.deviceId)) { this.devices.push(device); } }); bleManager.onConnected(() { console.log(藍(lán)牙連接成功); this.isConnected true; uni.showToast({ title: 連接成功 }); }); bleManager.onDataReceived((data, serviceUUID, charUUID) { console.log(從[${serviceUUID}][${charUUID}]收到數(shù)據(jù):, data); // 處理數(shù)據(jù)... }); }, startScanning() { this.devices []; // 只掃描包含特定服務(wù)例如0xFFE0的設(shè)備 bleManager.startScan([FFE0]); }, connectDevice(device) { this.connectedDeviceId device.deviceId; bleManager.connect(device.deviceId); }, async sendData() { const testData new Uint8Array([0x01, 0x02, 0x03, 0x04]); const success await bleManager.write(FFE0, FFE1, testData.buffer); if (success) { uni.showToast({ title: 發(fā)送成功 }); } } } } /script通過(guò)這樣的封裝我們成功將一個(gè)復(fù)雜的、平臺(tái)相關(guān)的iOS CoreBluetooth功能轉(zhuǎn)化成了一個(gè)簡(jiǎn)潔、易用、類(lèi)型安全的JavaScript API并且在uni-app的Vue組件中可以無(wú)縫調(diào)用。這解決了文章開(kāi)頭提到的官方API能力不足、連接不穩(wěn)定的問(wèn)題。4. UTS插件開(kāi)發(fā)中的進(jìn)階技巧與避坑指南走通了整個(gè)流程后你會(huì)發(fā)現(xiàn)UTS插件開(kāi)發(fā)雖然強(qiáng)大但細(xì)節(jié)處陷阱不少。下面分享一些我積累下來(lái)的進(jìn)階技巧和常見(jiàn)問(wèn)題的解決方案。4.1 數(shù)據(jù)類(lèi)型映射UTS與Swift/Obj-C的“翻譯官”這是最容易出錯(cuò)的地方。UTSTypeScript中的數(shù)據(jù)類(lèi)型需要精確映射到Swift/Objective-C?；绢?lèi)型string-Stringnumber-Double(默認(rèn)) 或Int/Float(需在Swift端明確指定類(lèi)型UTS調(diào)用時(shí)需匹配)boolean-BoolArray-Array(元素類(lèi)型需一致)Recordstring, any/object-DictionaryString, Any/NSDictionary特殊類(lèi)型ArrayBuffer/Uint8Array 這是處理二進(jìn)制數(shù)據(jù)的關(guān)鍵。在Swift中通常對(duì)應(yīng)Data或[UInt8]。UTS傳ArrayBuffer到 Swift在Swift方法參數(shù)中聲明為Data類(lèi)型。UTS橋接層會(huì)自動(dòng)轉(zhuǎn)換。Swift 返回Data給 UTS在UTS中會(huì)收到一個(gè)ArrayBuffer。// Swift objc func processData(_ data: Data) - Data { var bytes [UInt8](data) // ... 處理bytes return Data(bytes) }// UTS let inputBuffer new ArrayBuffer(4); let outputBuffer: ArrayBuffer UTSiOS.invoke(MyClass, processData:, [inputBuffer]);回調(diào)函數(shù)CallbackUTS不能直接將一個(gè)JS函數(shù)對(duì)象傳到Swift。標(biāo)準(zhǔn)的做法是在UTS層定義一個(gè)事件處理器如我們前面BLE例子中的_onDeviceFoundFromNative。在Swift端通過(guò)UTS運(yùn)行時(shí)提供的機(jī)制通常是UTSiOS.invoke的某種變體或特定API來(lái)調(diào)用這個(gè)UTS層的方法。在上面的例子中我們簡(jiǎn)化了jsHandler的獲取實(shí)際開(kāi)發(fā)中需要查閱UTS的官方文檔了解如何正確設(shè)置和使用UTSiOS的交互API來(lái)注冊(cè)和觸發(fā)回調(diào)。4.2 內(nèi)存管理與循環(huán)引用在Swift和UTS/JavaScript交互時(shí)要特別注意內(nèi)存管理避免循環(huán)引用導(dǎo)致內(nèi)存泄漏。Swift中持有JS回調(diào)如果Swift類(lèi)強(qiáng)引用了一個(gè)來(lái)自JS的對(duì)象或回調(diào)而這個(gè)JS對(duì)象又間接引用了Swift實(shí)例就會(huì)形成循環(huán)引用。解決方案是使用弱引用weak。class MyPlugin { // 錯(cuò)誤強(qiáng)引用可能導(dǎo)致循環(huán)引用 // var jsCallback: SomeJSType? // 正確弱引用 weak var jsDelegate: MyPluginJSDelegate? }在我們的BLE例子中jsHandler就被聲明為weak。UTS中的對(duì)象生命周期UTS對(duì)象在JavaScript環(huán)境中被垃圾回收。只要Swift端沒(méi)有不必要的強(qiáng)引用當(dāng)Vue組件銷(xiāo)毀或頁(yè)面關(guān)閉時(shí)對(duì)應(yīng)的UTS插件實(shí)例和Swift實(shí)例都應(yīng)該能被正確釋放。4.3 線程安全UI操作必須回主線程這是一個(gè)非常經(jīng)典的iOS開(kāi)發(fā)陷阱在UTS插件中同樣存在。所有涉及更新用戶界面的操作如顯示Alert、更新UI控件狀態(tài)必須在主線程Main Thread上執(zhí)行。CoreBluetooth等后臺(tái)線程回調(diào)如centralManager(_:didDiscover:advertisementData:rssi:)是在初始化CBCentralManager時(shí)指定的隊(duì)列我們用了后臺(tái)隊(duì)列上調(diào)用的。切換到主線程在需要更新UI或調(diào)用會(huì)觸發(fā)UI更新的JS回調(diào)時(shí)務(wù)必使用DispatchQueue.main.async。public func centralManager(_ central: CBCentralManager, didDiscover peripheral: CBPeripheral, advertisementData: [String : Any], rssi RSSI: NSNumber) { // 這個(gè)回調(diào)在后臺(tái)隊(duì)列 DispatchQueue.main.async { // 切換到主線程 self.jsHandler?.onDeviceFound(deviceInfo: ...) // 安全調(diào)用JS回調(diào) } }忘記切線程會(huì)導(dǎo)致UI無(wú)響應(yīng)、崩潰或不可預(yù)知的行為。4.4 插件調(diào)試與問(wèn)題排查調(diào)試UTS插件比調(diào)試普通uni-app頁(yè)面復(fù)雜因?yàn)樯婕霸a編譯。編譯錯(cuò)誤首先檢查HBuilderX控制臺(tái)的編譯輸出。UTS語(yǔ)法錯(cuò)誤、Swift語(yǔ)法錯(cuò)誤、類(lèi)型不匹配都會(huì)在這里顯示。錯(cuò)誤信息通常比較直接按提示修改即可。運(yùn)行時(shí)崩潰如果App在調(diào)用插件時(shí)崩潰首先連接真機(jī)或模擬器在Xcode中運(yùn)行項(xiàng)目HBuilderX運(yùn)行到iOS基座后可以在Xcode的“Devices and Simulators”窗口中找到對(duì)應(yīng)進(jìn)程點(diǎn)擊底部調(diào)試按鈕。這樣可以在Xcode中看到原生層的崩潰堆棧精準(zhǔn)定位到是Swift代碼的哪一行出了問(wèn)題。常見(jiàn)原因有強(qiáng)制解包可選值!、數(shù)組越界、線程沖突、回調(diào)參數(shù)類(lèi)型錯(cuò)誤。日志輸出在Swift代碼中大量使用print或os_log。這些日志會(huì)輸出到HBuilderX的運(yùn)行控制臺(tái)選擇對(duì)應(yīng)的iOS設(shè)備日志標(biāo)簽頁(yè)或Xcode的控制臺(tái)。真機(jī)調(diào)試限制某些系統(tǒng)API如部分藍(lán)牙后臺(tái)模式、推送通知在模擬器上行為可能與真機(jī)不同甚至不可用。關(guān)鍵功能務(wù)必在真機(jī)上測(cè)試。4.5 插件發(fā)布與集成開(kāi)發(fā)完成后你需要將插件提供給其他項(xiàng)目使用或者上傳到插件市場(chǎng)。本地集成直接將整個(gè)uni_modules/my-uts-plugin目錄復(fù)制到目標(biāo)uni-app項(xiàng)目的uni_modules目錄下即可。在項(xiàng)目的pages.json或需要使用的頁(yè)面中無(wú)需像組件一樣注冊(cè)直接import使用。發(fā)布到插件市場(chǎng)完善package.json中的name,version,description,keywords等信息。編寫(xiě)詳細(xì)的README.md文檔說(shuō)明功能、安裝方式、API、示例。在HBuilderX中右鍵插件目錄選擇“發(fā)布到插件市場(chǎng)”。版本管理UTS插件遵循uni_modules的版本規(guī)范。在package.json中定義好版本號(hào)更新時(shí)注意兼容性。開(kāi)發(fā)UTS iOS插件本質(zhì)上是在用TypeScript作為“粘合劑”將uni-app的跨端便利性與iOS原生的強(qiáng)大能力結(jié)合。這個(gè)過(guò)程需要你同時(shí)理解JavaScript/TypeScript和Swift/Objective-C兩套生態(tài)對(duì)開(kāi)發(fā)者的綜合能力要求較高。但一旦打通你將能突破uni-app的能力邊界實(shí)現(xiàn)那些“官方做不到”的復(fù)雜功能在跨端開(kāi)發(fā)中游刃有余。從解決一個(gè)具體的藍(lán)牙連接問(wèn)題出發(fā)到掌握一整套原生插件開(kāi)發(fā)方法論這種投資對(duì)于深耕uni-app生態(tài)的開(kāi)發(fā)者來(lái)說(shuō)無(wú)疑是極具價(jià)值的。