UniApp插件开发实战：将原生蓝牙与联系人功能封装为HBuilderX插件

在移动应用开发领域，跨平台框架UniApp因其"一次开发，多端运行"的特性广受欢迎。然而，当开发者需要访问设备原生功能如蓝牙或联系人时，现有的JavaScript API可能无法满足特定需求。这时，将原生Android能力封装为UniApp插件就成为扩展生态的关键技能。

1. 原生插件开发基础准备

开发UniApp原生插件前，需要搭建完整的开发环境并理解基本架构。与常规Android开发不同，UniApp插件需要同时处理原生代码和JavaScript桥接逻辑。

环境要求：

• Android Studio 4.0+
• JDK 1.8
• HBuilderX最新稳定版
• UniApp项目模板

首先创建Android Library模块作为插件载体：

// build.gradle配置示例
apply plugin: 'com.android.library'

android {
    compileSdkVersion 30
    defaultConfig {
        minSdkVersion 21
        targetSdkVersion 30
        versionCode 1
        versionName "1.0"
    }
}

dependencies {
    implementation 'com.android.support:appcompat-v7:28.0.0'
    implementation 'com.alibaba:fastjson:1.1.46.android'
}

插件目录结构应包含三个核心部分：

├── libs/            # 原生依赖库
├── src/main/
│   ├── assets/      # 静态资源
│   ├── java/        # 原生代码
│   └── res/         # 资源文件
└── package.json     # 插件配置文件

2. 蓝牙功能模块封装实战

蓝牙功能封装需要处理设备扫描、连接、数据收发等核心操作。我们采用分层设计，将复杂原生API简化为易用的JavaScript接口。

2.1 蓝牙服务初始化

创建BluetoothService处理底层操作：

public class BluetoothService {
    private BluetoothAdapter bluetoothAdapter;
    private BluetoothGatt activeGatt;
    
    public void initialize(Context context) {
        BluetoothManager manager = (BluetoothManager) 
            context.getSystemService(Context.BLUETOOTH_SERVICE);
        bluetoothAdapter = manager.getAdapter();
    }
    
    public boolean isEnabled() {
        return bluetoothAdapter != null && bluetoothAdapter.isEnabled();
    }
}

2.2 JS桥接接口设计

通过UniApp的扩展机制暴露接口：

// package.json配置
{
  "name": "native-bluetooth",
  "id": "DCloud-Bluetooth",
  "version": "1.0.0",
  "description": "蓝牙原生插件",
  "_dp_type": "nativeplugin",
  "_dp_nativeplugin": {
    "android": {
      "plugins": [
        {
          "type": "module",
          "name": "DCloud-Bluetooth",
          "class": "com.dcloud.bluetooth.BluetoothModule"
        }
      ]
    }
  }
}

2.3 异步通信处理

使用CallbackContext处理跨线程通信：

public class BluetoothModule extends UniModule {
    private BluetoothService bluetoothService;
    
    @UniJSMethod
    public void enableBluetooth(UniJSCallback callback) {
        if(bluetoothService == null) {
            bluetoothService = new BluetoothService();
            bluetoothService.initialize(mUniSDKInstance.getContext());
        }
        
        if(!bluetoothService.isEnabled()) {
            Intent enableBtIntent = new Intent(BluetoothAdapter.ACTION_REQUEST_ENABLE);
            mUniSDKInstance.getActivity().startActivityForResult(enableBtIntent, 1);
        }
        
        callback.invoke(new JSONObject().put("success", true));
    }
}

3. 联系人模块开发要点

联系人访问涉及敏感权限处理和数据转换，需要特别注意用户体验和数据格式。

3.1 权限动态申请

@UniJSMethod
public void requestContactsPermission(UniJSCallback callback) {
    if (ContextCompat.checkSelfPermission(mUniSDKInstance.getContext(),
            Manifest.permission.READ_CONTACTS) != PackageManager.PERMISSION_GRANTED) {
        
        ActivityCompat.requestPermissions(mUniSDKInstance.getActivity(),
                new String[]{Manifest.permission.READ_CONTACTS}, 
                CONTACTS_PERMISSION_CODE);
    } else {
        callback.invoke(new JSONObject().put("granted", true));
    }
}

3.2 联系人数据结构转换

将原生Contact对象转为JSON：

private JSONObject contactToJson(Contact contact) {
    JSONObject json = new JSONObject();
    try {
        json.put("id", contact.getId());
        json.put("displayName", contact.getDisplayName());
        
        JSONArray phones = new JSONArray();
        for (PhoneNumber phone : contact.getPhones()) {
            phones.put(phone.getNumber());
        }
        json.put("phones", phones);
    } catch (JSONException e) {
        e.printStackTrace();
    }
    return json;
}

4. 插件调试与性能优化

完成功能开发后，需要在实际环境中测试并优化插件性能。

4.1 HBuilderX集成测试

将插件打包为aar文件后，按以下步骤集成：

1. 创建UniApp项目的nativeplugins目录
2. 添加插件配置：

{
  "plugins": {
    "myBluetoothPlugin": {
      "version": "1.0.0",
      "provider": "your-company-id"
    }
  }
}

4.2 常见问题排查

蓝牙连接不稳定问题：

• 增加重试机制
• 优化GATT连接生命周期管理
• 添加错误码体系

public enum BluetoothError {
    CONNECTION_TIMEOUT(1001, "连接超时"),
    SERVICE_DISCOVERY_FAILED(1002, "服务发现失败");
    
    private int code;
    private String message;
    
    // getters...
}

4.3 性能优化技巧

内存优化：

• 使用对象池管理BluetoothGattCallback
• 限制联系人查询结果集大小
• 采用流式处理大数据传输

// 分页查询联系人示例
@UniJSMethod
public void getContacts(JSONObject options, UniJSCallback callback) {
    int page = options.optInt("page", 1);
    int pageSize = options.optInt("pageSize", 50);
    
    ContentResolver resolver = mUniSDKInstance.getContext().getContentResolver();
    Cursor cursor = resolver.query(
        ContactsContract.Contacts.CONTENT_URI,
        null, null, null,
        ContactsContract.Contacts.DISPLAY_NAME + " LIMIT " + pageSize + " OFFSET " + (page-1)*pageSize
    );
    
    // 处理cursor数据...
}

5. 插件发布与生态贡献

完成开发和测试后，可以将插件贡献到UniApp官方市场或私有仓库。

发布流程：

1. 生成文档和示例代码
2. 编写版本变更日志
3. 压缩插件包结构：

bluetooth-plugin-1.0.0.zip
├── android/        # aar文件
├── docs/           # 使用文档
├── examples/       # 示例项目
└── package.json    # 插件配置

版本管理建议：

• 遵循语义化版本规范
• 保持向后兼容性
• 为重大变更提供迁移指南

实际开发中发现，良好的错误处理机制能显著提升插件可用性。建议为每个原生方法设计统一的错误返回格式，并在JavaScript端提供相应的错误处理工具函数。