uni Native Plugin Development

https://nativesupport.dcloud.net.cn/NativePlugin
Admin
This documentation guides developers on how to create native plugins to extend the capabilities of...
Tokens:27,157
Snippets:282
Trust Score:7.7
Update:3 months ago
Show doc for...
Tokens:
Raw
### Full Example: Requesting Location Permissions

Source: https://nativesupport.dcloud.net.cn/NativePlugin/course/android

A comprehensive example demonstrating how to request fine and coarse location permissions and handle the results within a UniModule.

```java
import io.dcloud.common.core.permission.PermissionControler;
import android.Manifest;
import android.app.Activity;
import android.content.pm.PackageManager;
import io.dcloud.common.module.UniModule;
import io.dcloud.common.annotation.UniJSMethod;

public class TestModule extends UniModule {
    final int REQUEST_CODE = 11111;
    private static String[] permissions = new String[]{
            Manifest.permission.ACCESS_FINE_LOCATION,
            Manifest.permission.ACCESS_COARSE_LOCATION
    };

    @UniJSMethod(uiThread = true)
    public void requestPermissions() {
        if(mUniSDKInstance.getContext() != null) {
            Activity activity = (Activity) mUniSDKInstance.getContext();
            PermissionControler.requestPermissions(activity, permissions, REQUEST_CODE);
        }
    }

    @Override
    public void onRequestPermissionsResult(int requestCode, String[] permissions, int[] grantResults) {
        if(requestCode == REQUEST_CODE) {
            for(int i= 0; i< permissions.length; i++) {
                String preName = permissions[i];
                int granted = grantResults[i];
                if(Manifest.permission.ACCESS_FINE_LOCATION.equals(preName) && granted == PackageManager.PERMISSION_GRANTED) {
                    //获取权限结果
                }
            }
        }
        super.onRequestPermissionsResult(requestCode, permissions, grantResults);
    }
}
```

--------------------------------

### Define Plugin Parameters (Simple Key)

Source: https://nativesupport.dcloud.net.cn/NativePlugin/course/package

Configure plugin parameters with descriptions and keys for Info.plist. This example shows basic 'appid_ios' and 'appkey_ios' configurations.

```json
"parameters": {
  "appid_ios": {
    "des": "iOS平台的appid",
    "key": "HelloPlugin:appid"
  },
  "appkey_ios": {
    "des": "iOS平台的appkey",
    "key": "HelloPlugin:appkey"
  }
}

```

--------------------------------

### Configure Plugin Parameters with Key

Source: https://nativesupport.dcloud.net.cn/NativePlugin/course/package

Example of configuring plugin parameters 'appid_android' and 'appkey_android' using the 'key' field for manifest meta-data. This allows for direct mapping in AndroidManifest.xml.

```json
"parameters": {
  "appid_android": {
    "des": "Android平台的appid",
    "key": "HelloPlugin_appid"
  },
  "appkey_android": {
    "des": "Android平台的appkey",
    "key": "HelloPlugin_appkey"
  }
}

```

--------------------------------

### Register Native Module Example

Source: https://nativesupport.dcloud.net.cn/NativePlugin/API/harmony.html

Use `registerModule` to register a native module. This example demonstrates registering an 'echo' module with synchronous and asynchronous methods that handle string and object data types.

```typescript
import { registerModule } from '@dcloudio/uni-app-runtime'
interface IEchoObject {
  message: string
}

class Echo {
  echoSync(str: string) {
    return 'response: ' + str
  }
  echoAsync(str:string, callback: Function) {
    setTimeout(() => {
      callback('response: ' + str)
    }, 1000)
  }
  echoObjSync(str: string) {
    return { message: 'response: ' + str } as IEchoObject
  }
  echoObjAsync(str:string, callback: Function) {
    setTimeout(() => {
      callback({ message: 'response: ' + str } as IEchoObject)
    }, 1000)
  }
}
registerModule('echo', new Echo())
```

--------------------------------

### Navigate to Native Activity

Source: https://nativesupport.dcloud.net.cn/NativePlugin/course/android

Use this method to navigate from a UniApp plugin to a native Android Activity. Ensure the UniSDKInstance is available and get the context to start the activity.

```java
@UniJSMethod (uiThread = true)
public void gotoNativePage(){
    if(mUniSDKInstance != null) {
        Intent intent = new Intent(mUniSDKInstance.getContext(), NativePageActivity.class);
        mUniSDKInstance.getContext().startActivity(intent);
    }
}
```

--------------------------------

### Start Activity for Result

Source: https://nativesupport.dcloud.net.cn/NativePlugin/course/android

Use this method to launch a native Android Activity and expect a result back. Ensure the context is an Activity and provide a request code.

```java
@UniJSMethod (uiThread = true)
 public void gotoNativePage(){
     if(mUniSDKInstance != null && mUniSDKInstance.getContext() instanceof Activity) {
         Intent intent = new Intent(mUniSDKInstance.getContext(), NativePageActivity.class);
         ((Activity)mUniSDKInstance.getContext()).startActivityForResult(intent, REQUEST_CODE);
     }
 }
```

--------------------------------

### Android Plugin Dependency Source Example

Source: https://nativesupport.dcloud.net.cn/NativePlugin/course/package

Example of a dependency source string that will be added to the build.gradle file's dependencies during cloud packaging. Note that newline characters must be escaped as \r\n.

```gradle
implementation('com.android.support.test.espresso:espresso-contrib:2.2.2', {
    exclude group: 'com.android.support', module: 'support-v4'
})
```

--------------------------------

### UniApp iOS Native Plugin Configuration

Source: https://nativesupport.dcloud.net.cn/NativePlugin/course/ios

Example package.json for an iOS native plugin. It specifies plugin details, modules, components, required frameworks, integration type, and deployment target.

```json
{
	"name": "TestUniPlugin",
	"id": "DCTestUniPlugin",
	"version": "1.0.0",
	"description": "uni示例插件",
	"_dp_type": "nativeplugin",
	"_dp_nativeplugin": {
		"ios": {
			"plugins": [{
				"type": "module",
				"name": "DCTestUniPlugin-TestModule",
				"class": "TestModule"
			}, {
				"type": "component",
				"name": "dc-testmap",
				"class": "TestComponent"
			}],
			"frameworks": ["MapKit.framework"],
			"integrateType": "framework",
			"deploymentTarget": "9.0"
		}
	}
}
```

--------------------------------

### ios-extension.json Configuration Example

Source: https://nativesupport.dcloud.net.cn/NativePlugin/course/package

This JSON structure defines the configuration for an iOS Extension within a uni-native plugin. It specifies the extension's bundle identifier, provisioning profile, and optional plist and entitlement data.

```json
{
  "XXX.appex": {      //必填，多个iOS Extension需使用多个节点
    "identifier": "uni.XXX.ext",                //必填，Bundle identifier
    "profile": "ios-XXXExt.mobileprovision",    //必填，Provisioning Profile，相对于插件目录的路径
    "plists": {      //可选，合并到iOS Extension的Info.plist中的数据（json格式）
      
    },
    "entitlements": { //可选，覆盖iOS Extension的entitlements.plist中的数据（json格式）
      
    }
  }
}
```

--------------------------------

### Android Plugin Dependencies in app.gradle

Source: https://nativesupport.dcloud.net.cn/NativePlugin/course/package

Example of how to declare Android dependencies in the app.gradle file. These are third-party SDKs integrated into the Android plugin.

```gradle
dependencies {
    implementation "androidx.localbroadcastmanager:localbroadcastmanager:1.0.0"
    implementation "androidx.core:core:1.1.0"
	implementation "androidx.fragment:fragment:1.1.0"
	implementation "androidx.webkit:webkit:1.3.0"
    implementation "androidx.appcompat:appcompat:1.1.0"
    implementation "com.alibaba:fastjson:1.2.83"
}

```

--------------------------------

### Call Native Module Methods in uni-app

Source: https://nativesupport.dcloud.net.cn/NativePlugin/course/ios

Use `uni.requireNativePlugin` to get a module instance and then call its asynchronous or synchronous methods. Ensure the module name matches the one configured in the plist.

```javascript
<template>
	<div>
		<button type="primary" @click="testAsyncFunc">testAsyncFunc</button>
		<button type="primary" @click="testSyncFunc">testSyncFunc</button>
	</div>
</template>

<script>
	// 首先需要通过 uni.requireNativePlugin("ModuleName") 获取 module
	var testModule = uni.requireNativePlugin("DCTestUniPlugin-TestModule")
	export default {
		methods: {
			testAsyncFunc() {
				// 调用异步方法
				testModule.testAsyncFunc({
						'name': 'uni-app',
						'age': 1
					},
					(ret) => {
						uni.showToast({
							title:'调用异步方法 ' + ret,
							icon: "none"
						})
					})
			},
			testSyncFunc() {
				// 调用同步方法
				var ret = testModule.testSyncFunc({
					'name': 'uni-app',
					'age': 1
				})

				uni.showToast({
					title:'调用同步方法 ' + ret,
					icon: "none"
				})
			}
		}
	}
</script>
```

--------------------------------

### Android Native Method with Callback

Source: https://nativesupport.dcloud.net.cn/NativePlugin/course/android

Example of an Android native method that uses `UniJSCallback` to return data to JavaScript. Ensure callback data is placed within the 'detail' object when using `fireEvent`.

```java
@UniJSMethod(uiThread = true)
public void testAsyncFunc(JSONObject options, UniJSCallback callback) {
    Log.e(TAG, "testAsyncFunc--"+options);
    if(callback != null) {
        JSONObject data = new JSONObject();
        data.put("code", "success");
        callback.invoke(data);
    }
}
```

--------------------------------

### Objective-C: Handle Array Input Safely

Source: https://nativesupport.dcloud.net.cn/NativePlugin/use/faq.html

When dealing with array inputs in Objective-C, ensure proper type checking before accessing elements to prevent crashes. This example shows how to safely access the first element of an array.

```objectivec
- (void)test:(NSArray*)files callback:(DCUniModuleCallback)callback 
{
	NSString * first =[files objectAtIndex:0];
}
```

--------------------------------

### Configure Plugin Information (plist)

Source: https://nativesupport.dcloud.net.cn/NativePlugin/course/ios

Add this dictionary to the `dcloud_uniplugins` node in your `HBuilder-uniPlugin-Info.plist` file. Ensure you replace placeholder values with your plugin's actual information.

```xml
<dict>
	<key>hooksClass</key>
	<string>填写 hooksClass 类名 </string>
	<key>plugins</key>
	<array>
		<dict>
			<key>class</key>
			<string>填写 module 或 component 的类名</string>
			<key>name</key>
			<string>填写暴露给js端对应的 module 或 component 名称</string>
			<key>type</key>
			<string>填写 module 或 component</string>
		</dict>
	</array>
</dict>
```

--------------------------------

### Implement UniAppHookProxy for Plugin Initialization

Source: https://nativesupport.dcloud.net.cn/NativePlugin/course/android

Implement the `UniAppHookProxy` interface to handle plugin initialization logic, including module and component registration. The `onCreate` method is called once per uni-app process, while `onSubProcessCreate` is for child processes.

```java
public class RichAlert_AppProxy implements UniAppHookProxy {
 	@Override
 	public void onCreate(Application application) {
 		//当前uni应用进程回调 仅触发一次 多进程不会触发
   	//可通过UniSDKEngine注册UniModule或者UniComponent
 	}

   @Override
   public void onSubProcessCreate(Application application) {
   	//其他子进程初始化回调 可用于初始化需要子进程初始化需要的逻辑
   }
 }
```

--------------------------------

### Get Image Resource Path (JavaScript)

Source: https://nativesupport.dcloud.net.cn/NativePlugin/course/ios

Two methods to get image paths in JavaScript: using relative paths directly with `_doc/` or converting `_doc/` to an absolute platform path using `plus.io.convertLocalFileSystemURL`.

```javascript
var relativePath = "_doc/test.png"

```

```javascript
var docPath = plus.io.convertLocalFileSystemURL("_doc/");
var absolutePath = docPath + 'test.png'

```

--------------------------------

### Define Plugin Parameters for Info.plist

Source: https://nativesupport.dcloud.net.cn/NativePlugin/course/package

Configure parameters like appid and appkey that will be added to the Info.plist file during cloud packaging. 'key' specifies the plist key, and 'value' can format the input.

```json
"parameters": {
    "appid_ios": {
        "des": "XXX插件的appid参数",
        "key": "XXX:appid",
        "value": "TEST_${ios_appid}"
   }
}

```

--------------------------------

### Configure dcloud_uniplugins in Info.plist

Source: https://nativesupport.dcloud.net.cn/NativePlugin/offline_package/ios.html

Add the 'dcloud_uniplugins' key to your Info.plist file to register native plugins, specifying their hooksClass, type, name, and class. Multiple plugins can be configured within a single 'dcloud_uniplugins' array.

```xml
	<key>dcloud_uniplugins</key>
	<array>
		<dict>
			<key>hooksClass</key>
			<string>插件事件钩子注册类名</string>
			<key>plugins</key>
			<array>
				<dict>
					<key>type</key>
					<string>插件类型</string>
					<key>name</key>
					<string>插件名称</string>
					<key>class</key>
					<string>插件的类名</string>
				</dict>
			</array>
		</dict>
	</array>

```

--------------------------------

### Include Bundle and Data Resources

Source: https://nativesupport.dcloud.net.cn/NativePlugin/course/package

Include both .bundle directories and specific data files like license files. Ensure data files are placed in the correct path within the plugin's 'ios' directory for cloud packaging.

```json
"resources": [
    "HelloPlugin.bundle",
    "license-ios.dat"
   ]
}

```

--------------------------------

### Use Custom Component in Nvue

Source: https://nativesupport.dcloud.net.cn/NativePlugin/course/android

After registering the component group, you can use the custom component in your nvue files. This example shows how to reference and call a method on the custom component.

```vue
<template>
	<div>
		<myText ref="telText" tel="12305" style="width:200;height:100" @onTel="onTel" @click="myTextClick"></myText>
	</div>
</template>
<script>
    export default {
        methods: {
			myTextClick(e) {
				this.$refs.telText.clearTel();
			}
        }
    }
</script>
```

--------------------------------

### Troubleshoot iOS Local Plugin Packaging Error on Windows

Source: https://nativesupport.dcloud.net.cn/NativePlugin/use/use_local_plugin.html

When packaging iOS local plugins on Windows results in errors due to broken symbolic links in .framework files, manually replace the symbolic links with actual file copies. This ensures the framework is correctly included during the packaging process.

```bash
1. Check the .framework library files in the plugin's iOS directory. If files like UTDID, Resources, Headers within UTDID.framework are 1kb, they are likely symbolic links that have become invalid on Windows.
2. Open these 1kb files with a text editor. They will contain the path to the actual linked file (e.g., within '/Versions/A/').
3. Copy the actual file from the '/Versions/A/' directory to the root of the .framework library. Delete all other files within the .framework library.
4. Resubmit for packaging.
```

--------------------------------

### Specify Valid CPU Architectures

Source: https://nativesupport.dcloud.net.cn/NativePlugin/course/package

Define the supported CPU architectures for the plugin. If not specified, all common architectures are assumed. Cloud packaging will use the intersection of supported architectures.

```json
"validArchitectures": [
    "arm64", "arm64e"
]

```

--------------------------------

### Configure Plugin Parameters in Info.plist

Source: https://nativesupport.dcloud.net.cn/NativePlugin/offline_package/ios.html

For parameters defined in package.json, such as 'getui:appid', add corresponding keys and string values to your Info.plist file. Nested keys should be represented using a colon separator.

```xml
<key>getui</key>
<dict>
	<key>appid</key>
	<string>填写对应的appid</string>
</dict>

```

--------------------------------

### Include Bundle Resources

Source: https://nativesupport.dcloud.net.cn/NativePlugin/course/package

Specify .bundle directories to be included in the plugin package. Avoid using names like 'Resources' that may conflict with system resources.

```json
"resources": [
    "HelloPlugin.bundle"
   ]
}

```

--------------------------------

### Get Image Resource Path (iOS Native)

Source: https://nativesupport.dcloud.net.cn/NativePlugin/course/ios

Obtain the document path for storing images in iOS native code. This path corresponds to `_doc/` in JavaScript. Images stored here can be accessed by Vue pages, avoiding cross-domain issues.

```objectivec
#import "PDRCoreApp.h"
#import "PDRCoreAppManager.h"
#import "PDRCoreAppInfo.h"

PDRCoreAppInfo *appinfo = [PDRCore Instance].appManager.getMainAppInfo;
NSString *imgPath = [appinfo.documentPath stringByAppendingPathComponent:@"test.png"];

```

--------------------------------

### Initialize Component Host View

Source: https://nativesupport.dcloud.net.cn/NativePlugin/course/android

The initComponentHostView callback function is triggered when building the Component's view. It should return the host view for the component.

```java
@Override
protected TextView initComponentHostView(@NonNull Context context) {
    TextView textView = new TextView(context);
    textView.setTextSize(20);
    textView.setTextColor(Color.BLACK);
    return textView;
}
```

--------------------------------

### Configure Entitlements for Capabilities

Source: https://nativesupport.dcloud.net.cn/NativePlugin/course/package

Add necessary entitlements for services like WiFi information. The key and value are derived from the .entitlements file configuration.

```json
"capabilities": {
	"entitlements": {
		"com.apple.developer.networking.wifi-info":true
	}
}

```

--------------------------------

### Get Current UIViewController in iOS

Source: https://nativesupport.dcloud.net.cn/NativePlugin/course/ios

This Objective-C code provides a utility to find the currently displayed UIViewController. It handles navigation controllers, tab bar controllers, and presented view controllers recursively. Use this when you need to interact with or present new views from a native module.

```Objective-C
// Get the currently displayed UIViewController
+ (UIViewController *)dc_findCurrentShowingViewController {
    // Get the root view controller of the current active window
    UIViewController *vc = [UIApplication sharedApplication].keyWindow.rootViewController;
    UIViewController *currentShowingVC = [self findCurrentShowingViewControllerFrom:vc];
    return currentShowingVC;
}
+ (UIViewController *)findCurrentShowingViewControllerFrom:(UIViewController *)vc
{
    // Recursive method
    UIViewController *currentShowingVC;
    if ([vc presentedViewController]) {
        // The current view is presented
        UIViewController *nextRootVC = [vc presentedViewController];
        currentShowingVC = [self findCurrentShowingViewControllerFrom:nextRootVC];

    } else if ([vc isKindOfClass:[UITabBarController class]]) {
        // The root view is a UITabBarController
        UIViewController *nextRootVC = [(UITabBarController *)vc selectedViewController];
        currentShowingVC = [self findCurrentShowingViewControllerFrom:nextRootVC];

    } else if ([vc isKindOfClass:[UINavigationController class]]){
        // The root view is a UINavigationController
        UIViewController *nextRootVC = [(UINavigationController *)vc visibleViewController];
        currentShowingVC = [self findCurrentShowingViewControllerFrom:nextRootVC];

    } else {
        // The root view is not a navigation type
        currentShowingVC = vc;
    }

    return currentShowingVC;
}
```

--------------------------------

### iOS Extension Configuration File Structure

Source: https://nativesupport.dcloud.net.cn/NativePlugin/course/package

This illustrates the directory structure required for a uni-native plugin that includes an iOS Extension. Ensure the `ios-extension.json` file is placed correctly within the plugin's iOS directory.

```text
-- HelloUniApp项目目录
  |-- nativeplugins
    |-- DCloud-RichAlert(实际包含iOS Extension的uni原生插件标识)
      |-- ios-extension.json
      |-- ios-XXXExt.mobileprovision
```

--------------------------------

### Configure Native Plugins in dcloud_uniplugins.json

Source: https://nativesupport.dcloud.net.cn/NativePlugin/offline_package/android.html

Define native plugin configurations, including module type, name, and class, in the `dcloud_uniplugins.json` file located in the assets directory. This file is crucial for uni-app to recognize and load native plugins.

```json
{
  "nativePlugins": [
    {
      "plugins": [
        {
          "type": "module",
          "name": "DCloud-RichAlert",
          "class": "uni.dcloud.io.uniplugin_richalert.RichAlertWXModule"
        }
      ]
    }
  ]
}
```

--------------------------------

### UniSDKEngine

Source: https://nativesupport.dcloud.net.cn/NativePlugin/API/android.html

Provides methods for registering custom modules and components within the UniApp framework.

```APIDOC
## registerUniModule(String moduleName, Class<? extends UniModule> moduleClass)

### Description
Registers a UniModule with the specified module name and class.

### Method
`registerUniModule`

### Parameters
#### Path Parameters
- **moduleName** (String) - Required - The name of the module.
- **moduleClass** (Class<? extends UniModule>) - Required - The class of the module to register.

### Return Value
- **boolean** - Returns true if the registration was successful, false otherwise.
```

```APIDOC
## registerUniComponent(String type, Class<? extends UniComponent> clazz)

### Description
Registers a UniComponent with the specified type and class.

### Method
`registerUniComponent`

### Parameters
#### Path Parameters
- **type** (String) - Required - The name of the component.
- **clazz** (Class<? extends UniComponent>) - Required - The class of the component to register.

### Return Value
- **boolean** - Returns true if the registration was successful, false otherwise.
```

```APIDOC
## registerUniVContainer(String type, Class<? extends UniVContainer> clazz)

### Description
Registers a UniVContainer (parent container component) with the specified type and class.

### Method
`registerUniVContainer`

### Parameters
#### Path Parameters
- **type** (String) - Required - The name of the container component.
- **clazz** (Class<? extends UniVContainer>) - Required - The class of the container component to register.

### Return Value
- **boolean** - Returns true if the registration was successful, false otherwise.
```

--------------------------------

### Configure Plugin Assets

Source: https://nativesupport.dcloud.net.cn/NativePlugin/course/package

Specify .xcassets files to be included in the plugin package. Avoid using system-reserved names like 'app.imageset' or 'AppIcon.appiconset' to prevent conflicts.

```json
"assets": [
 	"myimage.xcassets"      //使用的xcassets文件列表
]

```

--------------------------------

### Add Dependencies in Gradle Configuration

Source: https://nativesupport.dcloud.net.cn/NativePlugin/offline_package/android.html

Configure your project's `build.gradle` file to include necessary libraries and plugins. This includes file tree dependencies for local JARs and AARs, as well as specific library implementations like BindingX, OkHttp, and Glide.

```gradle
dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar'])
    implementation fileTree(dir: 'libs', include: ['*.aar'])

    implementation "androidx.localbroadcastmanager:localbroadcastmanager:1.0.0"
    implementation "androidx.core:core:1.1.0"
    implementation "androidx.fragment:fragment:1.1.0",
	implementation "androidx.recyclerview:recyclerview:1.1.0",
	implementation "androidx.appcompat:appcompat:1.1.0",

    implementation 'com.alibaba.android:bindingx-core:1.0.3'
    implementation 'com.alibaba.android:bindingx_weex_plugin:1.0.3'
    implementation 'com.squareup.okhttp:okhttp:2.3.0'
    implementation 'com.squareup.okhttp:okhttp-ws:2.3.0'
    // 基座需要，必须添加
    implementation 'com.github.bumptech.glide:glide:4.9.0'
}
```

--------------------------------

### iOS Plugin Directory Structure

Source: https://nativesupport.dcloud.net.cn/NativePlugin/offline_package/ios.html

Understand the standard directory layout for native iOS plugins, including folders for Android and iOS specific code, and the essential package.json configuration file.

```plaintext
|-- 插件目录结构
	|-- android				// android 插件
	|-- ios				// ios 插件
	|-- package.json				// 插件配置文件

```

--------------------------------

### iOS SDK Package Structure

Source: https://nativesupport.dcloud.net.cn/NativePlugin/course/ios

This structure outlines the essential directories and files within the iOS SDK package for uni-app native plugin development. The `HBuilder-uniPluginDemo` directory is the primary project for developing plugins.

```text
|--iOSSDK
	|-- HBuilder-Hello			// uni-app 离线打包工程
	|-- HBuilder-uniPluginDemo		// uni-app 插件开发主工程 （本文档需要使用的工程）
	|-- SDK						// 依赖库及依赖资源文件
	|-- Feature-iOS.xls			// 功能模块与依赖库对应关系说明表格
	|-- readme.txt				// 目录说明

```

--------------------------------

### Configure Gradle Dependencies for Module Extension

Source: https://nativesupport.dcloud.net.cn/NativePlugin/course/android

Add these configurations to your Module's build.gradle file to include necessary AAR files and dependencies for uni-app native module development. Ensure the uniapp-v8-release.aar is in the app/libs directory.

```gradle
//导入aar需要的配置
repositories {
	flatDir {
		dirs 'libs'
	}
}
dependencies {
	//必须添加的依赖
	compileOnly 'androidx.localbroadcastmanager:localbroadcastmanager:1.0.0',
	compileOnly 'androidx.core:core:1.1.0'
	compileOnly 'androidx.fragment:fragment:1.1.0'
	compileOnly 'androidx.appcompat:appcompat:1.1.0'
	compileOnly 'androidx.recyclerview:recyclerview:1.1.0'
	compileOnly 'com.alibaba:fastjson:1.2.83'

	compileOnly fileTree(include: ['uniapp-v8-release.aar'], dir: '../app/libs')
}
```

--------------------------------

### UniUtils

Source: https://nativesupport.dcloud.net.cn/NativePlugin/API/android.html

Provides general utility methods for common tasks.

```APIDOC
## io.dcloud.feature.uniapp.utils.UniUtils

### isUiThread()

Checks if the current thread is the UI thread.

### getFloatByViewport(Object value, float viewport)

Converts a value based on viewport dimensions.

#### Parameters
- **value** (Object) - The value to convert.
- **viewport** (float) - The viewport value.

#### Returns
- **float** - The converted value.

### getFloat(Object value, Float df)

Converts a value to a float type.

#### Parameters
- **value** (Object) - The value to convert.
- **df** (Float) - The default value.

#### Returns
- **float** - The float representation of the value.

### getInt(String|Object value)

Converts a string or object to an integer.

#### Parameters
- **value** (String|Object) - The string or object to convert.

#### Returns
- **int** - The integer representation of the value, defaults to 0.

### getInteger(Object value, Integer df)

Retrieves an Integer object from a given value, with a default.

#### Parameters
- **value** (Object) - The object to convert.
- **df** (Integer) - The default Integer value.

#### Returns
- **integer** - The Integer representation of the value.

### parseInt(String|Object value)

Converts a string or object to an integer.

#### Parameters
- **value** (String|Object) - The string or object to convert.

#### Returns
- **int** - The integer representation of the value.

### parseFloat(String|Object value)

Converts a string or object to a float.

#### Parameters
- **value** (String|Object) - The string or object to convert.

#### Returns
- **float** - The float representation of the value.

### getDouble(Object value)

Converts a string or object to a double.

#### Parameters
- **value** (Object) - The string or object to convert.

#### Returns
- **double** - The double representation of the value.

### getLong(Object value)

Converts a string or object to a long.

#### Parameters
- **value** (Object) - The string or object to convert.

#### Returns
- **long** - The long representation of the value.

### getBoolean(Object value, Boolean df)

Converts a string or object to a Boolean.

#### Parameters
- **value** (Object) - The string or object to convert.
- **df** (Boolean) - The default Boolean value.

#### Returns
- **Boolean** - The Boolean representation of the value.
```

--------------------------------

### uni-app Native Plugin package.json Configuration

Source: https://nativesupport.dcloud.net.cn/NativePlugin/course/package

This is the main configuration file for a uni-app native plugin. It must be in JSON format without comments and is essential for cloud packaging. It defines plugin metadata, and platform-specific configurations for Android and iOS.

```json
{
	"name": "插件名称",
	"id": "插件标识，需要保证唯一性",
	"version": "插件版本号",
	"description": "插件描述信息",
	"_dp_type":"nativeplugin",
	"_dp_nativeplugin":{
		"android": {
			"plugins": [
				{
					"type": "module|component, 必填, 根据插件类型选择",
					"name": "必填, 注册插件的名称, 注意：module 的 name 必须以插件id为前缀或和插件id相同，比如 `DCTestUniPlugin-TestModule`，其中 DCTestUniPlugin 为插件的id，避免与其他插件冲突，component 的 name 没有强制要求，但是也要保证唯一比如 `dc-map`",
					"class": "必填, 注册插件的类名"
				}
			],
			"hooksClass": "可选, 事件钩子注册类名",
			"integrateType": "必填, 可取值aar|jar",
			"dependencies": [
				"可选, 依赖的库名称"
			],
			"excludeDependencies": [
				"可选，需要排除的HX内置模块依赖库名称"  //HBuilderX3.1.18+支持：仅在插件与HX内置模块依赖库存在冲突时可能需要，使用前请在官方QQ交流群“DCloud原生开发者群”中联系管理员确认
			],
			"compileOptions": {
				"sourceCompatibility": "1.8",
				"targetCompatibility": "1.8"
			},
			"abis": [
				"可选, 支持的abi类型, 可取值armeabi-v7a|arm64-v8a|x86"
			],
			"minSdkVersion": "可选，支持的Android最低版本，如21",
			"useAndroidX": false,   //可选，是否兼容使用AndroidX  3.2.5+版本后废弃该属性
			"permissions": [
				"可选, 要使用的Android权限列表"
			],
			"parameters": {
				"插件需要配置的参数名称, 如appid": {
					"des": "参数描述",
					"key": "AndroidManifest.xml中添加meta-data节点！对应android:name属性值, 如GETUI_APPID",
					"placeholder": "build.gradle中添加到manifestPlaceholders中的字段名"
				}
			}
		},
		"ios": {
			"plugins": [
				{
					"type": "必填, module|component, 根据插件类型选择",
					"name": "必填, 注册插件的名称, 通常与插件标识一致",
					"class": "必填, 注册插件的类名" 
				}
			],
			"integrateType": "必填, 可取值framework|library",
			"hooksClass": "可选, 事件钩子注册类名",
			"frameworks": [
				"依赖的系统库(系统库有.framework和.tbd和.dylib类型)，和第三方.framework动态库;（.a 库或 .framework**静态库**直接放到ios根目录即可，不需要配置）"
			],
			"embedFrameworks": [
				"依赖的.framework动态库（注意.framework动态库也需要在上面的 frameworks 节点添加配置，同样将动态库.framework文件放到 ios 目录）"
			],
			"capabilities": {
				"entitlements": {
				},
				"plists": {
				}
			},
			"plists": {
			},
			"assets": [
			 	"可选，插件要使用的xcassets文件列表，相对于ios目录的路径"
			],
			"privacies": [
				"可选, 插件使用到的隐私列表，如NSPhotoLibraryUsageDescription"
			],
			"embedSwift": false, 
			"deploymentTarget": "8.0, 可选，注意：使用 Xcode14 需配置为 \"11.0\"",
			"validArchitectures": [
			 	"arm64"    
			],
			"parameters": {
				"插件需要配置的参数名称, 如appid": {
					"des": "参数描述信息",
					"key": "参数需要配置到info.plist中的键名, 嵌套时使用:分割，如getui:appid"
				}
			},
			"resources": [
				"可选, 插件要使用的资源文件列表，相对于ios目录的路径 ，HX 3.2.0+ 版本不在推荐使用，请参考文档下面的 “依赖资源文件” 说明"
			]
		}
	}
}

```

--------------------------------

### UniResourceUtils

Source: https://nativesupport.dcloud.net.cn/NativePlugin/API/android.html

Provides utility methods for resource data conversion, specifically for color values.

```APIDOC
## io.dcloud.feature.uniapp.utils.UniResourceUtils

### getColor(String color)

Converts a color string to an integer representation.

#### Parameters
- **color** (String) - The color value string.

### getColor(String color, int defaultColor)

Converts a color string to an integer representation, with a default value if conversion fails.

#### Parameters
- **color** (String) - The color value string.
- **defaultColor** (int) - The default color value.

### isNamedColor(String name)

Checks if the given color name is a recognized named color.

#### Parameters
- **name** (String) - The color name to check.

### parseAlpha(float alpha)

Parses an alpha value from the range 0-1 to the range 0-255.

#### Parameters
- **alpha** (float) - The alpha value, ranging from 0 to 1.

#### Returns
- **int** - The alpha value in the range 0-255.
```

--------------------------------

### Add Local Native Plugin to manifest.json

Source: https://nativesupport.dcloud.net.cn/NativePlugin/use/use_local_plugin.html

After placing the native plugin in the 'nativeplugins' directory, select it in the 'App Native Plugin Configuration' section of manifest.json. Cloud packaging is required for the plugin to take effect.

```json
{
  "App原生插件配置": {
    "选择本地插件": [
      "DCloud-RichAlert"
    ]
  }
}
```

--------------------------------

### Add Plugins to info.plist for iOS

Source: https://nativesupport.dcloud.net.cn/NativePlugin/offline_package/ios.html

This XML snippet shows how to add native plugin information to the app's info.plist file. It registers the plugin modules and their classes.

```xml
<key>dcloud_uniplugins</key>
	<array>
		<dict>
			<key>hooksClass</key>
			<string></string>
			<key>plugins</key>
			<array>
				<dict>
					<key>type</key>
					<string>module</string>
					<key>name</key>
					<string>DCloud-RichAlert</string>
					<key>class</key>
					<string>DCRichAlertModule</string>
				</dict>
			</array>
		</dict>
	</array>

```

--------------------------------

### iOS Hook System Events

Source: https://nativesupport.dcloud.net.cn/NativePlugin/course/ios

Implement these methods in a `XXXXProxy` class inheriting from `NSObject` and conforming to `UniPluginProtocol` to handle system events during app launch and lifecycle.

```objectivec
-(void)onCreateUniPlugin;

- (BOOL)application:(UIApplication *_Nullable)application didFinishLaunchingWithOptions:(NSDictionary *_Nullable)launchOptions;
- (void)didRegisterForRemoteNotificationsWithDeviceToken:(NSData *_Nullable)deviceToken;
- (void)didFailToRegisterForRemoteNotificationsWithError:(NSError *_Nullable)err;
- (void)didReceiveRemoteNotification:(NSDictionary *_Nullable)userInfo;
- (void)didReceiveLocalNotification:(UILocalNotification *_Nullable)notification;
- (BOOL)application:(UIApplication *_Nullable)application handleOpenURL:(NSURL *_Nullable)url;
- (BOOL)application:(UIApplication *_Nullable)app openURL:(NSURL *_Nonnull)url options:(NSDictionary<UIApplicationOpenURLOptionsKey, id> *_Nullable)options NS_AVAILABLE_IOS(9_0);

- (void)applicationWillResignActive:(UIApplication *_Nullable)application;
- (void)applicationDidBecomeActive:(UIApplication *_Nullable)application;
- (void)applicationDidEnterBackground:(UIApplication *_Nullable)application;
- (void)applicationWillEnterForeground:(UIApplication *_Nullable)application;


- (void)applicationMain:(int)argc argv:(char * _Nullable [_Nonnull])argv;

- (BOOL)application:(UIApplication *_Nullable)application continueUserActivity:(NSUserActivity *_Nullable)userActivity restorationHandler:(void(^_Nullable)(NSArray * __nullable restorableObjects))restorationHandler API_AVAILABLE(ios(8.0));

```

--------------------------------

### Request Permissions with PermissionControler

Source: https://nativesupport.dcloud.net.cn/NativePlugin/course/android

Use PermissionControler to request permissions from the user. Ensure you have the Activity context and the list of permissions.

```java
PermissionControler.requestPermissions(Activity, permissions, REQUEST_CODE);
```

--------------------------------

### getRealPxByWidth

Source: https://nativesupport.dcloud.net.cn/NativePlugin/API/android.html

Converts px values from JS/CSS to native data values based on a custom viewport.

```APIDOC
## getRealPxByWidth(float pxValue, float customViewport)

### Description
Converts px values from JS/CSS data to native data values.

### Method Signature
`getRealPxByWidth(float pxValue, float customViewport)`

### Parameters
#### Path Parameters
- **pxValue** (float) - Required - The px value obtained from JS/CSS.
- **customViewport** (float) - Required - The 'viewport' value, obtained via `mUniSDKInstance.getInstanceViewPortWidth()`.

### Return Value
- **float** - The native data value.
```

--------------------------------

### Access Native Plugin in uni-app

Source: https://nativesupport.dcloud.net.cn/NativePlugin/course/android

Use `uni.requireNativePlugin` to obtain an instance of a registered native plugin within your uni-app project. Ensure the plugin name matches the one defined in `dcloud_uniplugins.json`.

```javascript
const pluginImpl = uni.requireNativePlugin('插件 name')
```

--------------------------------

### Expose Native Method to Frontend

Source: https://nativesupport.dcloud.net.cn/NativePlugin/course/ios

Use the UNI_EXPORT_METHOD macro to expose a native Objective-C method (e.g., 'focus:') to be callable from the uni-app frontend. The method accepts a dictionary of options.

```objectivec
@implementation TestMapComponent

// 通过 UNI_EXPORT_METHOD 将方法暴露给前端
UNI_EXPORT_METHOD(@selector(focus:))

// options 为前端传递的参数，支持 NSDictionary 或 NSString 类型
- (void)focus:(NSDictionary *)options {
    NSLog(@"%@",options);
}
@end

```

--------------------------------

### Complete package.json for iOS Native Plugins

Source: https://nativesupport.dcloud.net.cn/NativePlugin/offline_package/ios.html

This JSON structure defines the configuration for an iOS native plugin, including its metadata, types, dependencies, resources, and privacy permissions. Manual configuration in Xcode is required if not using HBuilderX cloud packaging.

```json
{
    "name": "插件名称",
    "id": "插件标识",
    "version": "插件版本号",
    "description": "插件描述信息",
    "_dp_type":"nativeplugin",
    "_dp_nativeplugin":{
        "ios": {
            "plugins": [
                {
                    "type": "module|component, 插件类型",
                    "name": "插件名称",
                    "class": "插件的类名"
                }
            ],
            "hooksClass": "插件事件钩子注册类名",
            "frameworks": [
                "插件依赖的系统库(系统库有.framework和.tbd和.dylib类型)"
            ],
            "embedFrameworks": [
                "依赖的framework动态库"
            ],
            "resources": [
                "插件要使用的资源文件列表，相对于ios目录的路径"
            ],
            "privacies": [
                "插件使用到的隐私列表，如NSPhotoLibraryUsageDescription"
            ],
            "parameters": {
                "插件需要配置的参数名称, 如appid": {
                    "des": "参数描述信息",
                    "key": "参数需要配置到infor.plist中的键名, 嵌套时使用:分割，如getui:appid"
                }
            }
        }
    }
}

```

--------------------------------

### Package.json for Native Plugin

Source: https://nativesupport.dcloud.net.cn/NativePlugin/course/android

Defines the plugin's metadata, including its ID, version, and native plugin configurations for Android modules and components. Use the plugin ID as a prefix for module and component names.

```json
{
    "name": "插件名称",
    "id": "DCloud-RichAlert", // 插件标识
    "version": "插件版本号",
    "description": "插件描述信息",
    "_dp_type":"nativeplugin",
    "_dp_nativeplugin":{
        "android": {
            "plugins": [
                {
                    "type": "module",
                    "name": "DCloud-RichAlert_TestModule", //id为前缀
                    "class": "uni.dcloud.io.uniplugin_richalert.TestModule"
                },
                {
                    "type": "component",
                    "name": "DCloud-RichAlert_TestComponent",
                    "class": "uni.dcloud.io.uniplugin_richalert.TestComponent"
                }
            ]
        }
    }
	...
	...

```

--------------------------------

### Define TestModule Header

Source: https://nativesupport.dcloud.net.cn/NativePlugin/course/ios

Define the header file for a custom module by inheriting from DCUniModule and importing the necessary header. This sets up the basic structure for your native module.

```objectivec
#import <Foundation/Foundation.h>
// 引入 DCUniModule.h 头文件
#import "DCUniModule.h"

@interface TestModule : DCUniModule

@end

```

--------------------------------

### Enable Swift Compilation Support

Source: https://nativesupport.dcloud.net.cn/NativePlugin/course/package

Set 'embedSwift' to true if the plugin is developed using Swift. The default value is false if Swift is not used.

```json
"embedSwift": true

```

--------------------------------

### Native Plugin Package Structure

Source: https://nativesupport.dcloud.net.cn/NativePlugin/course/ios

Defines the standard directory structure for a UniApp native plugin package. It includes folders for platform-specific code (android, ios) and a configuration file (package.json).

```plaintext
|-- 插件id				// 插件包是一个以插件id命名的文件夹
	|-- android				// 存放 android 插件所需要的依赖库及资源文件
	|-- ios					// 存放 ios 插件所需要的依赖库及资源文件
	|-- package.json				// 插件配置文件
```

--------------------------------

### Implement Asynchronous Module Method

Source: https://nativesupport.dcloud.net.cn/NativePlugin/course/ios

Implement an asynchronous method for a native module. This method executes on the main thread and uses a callback to return data to JavaScript. Ensure the callback supports multiple invocations if needed.

```objectivec
/// 异步方法（注：异步方法会在主线程（UI线程）执行）
/// @param options js 端调用方法时传递的参数   支持：String、Number、Boolean、JsonObject 类型
/// @param callback 回调方法，回传参数给 js 端   支持： NSString、NSDictionary（只能包含基本数据类型）、NSNumber 类型
- (void)testAsyncFunc:(NSDictionary *)options callback:(UniModuleKeepAliveCallback)callback {

    // options 为 js 端调用此方法时传递的参数 NSLog(@"%@",options); // 可以在该方法中实现原生能力，然后通过 callback 回调到 js

   if (callback) {
       // 第一个参数为回传给js端的数据，第二个参数为标识，表示该回调方法是否支持多次调用，如果原生端需要多次回调js端则第二个参数传 YES;
        callback(@"success",NO);

    }
}

```

--------------------------------

### Enable AndroidX Support

Source: https://nativesupport.dcloud.net.cn/NativePlugin/course/package

Configure this setting to true if your plugin or its dependencies require AndroidX compatibility. This is automatically handled by HBuilderX for versions 2.8.11+.

```json
"useAndroidX": true

```

--------------------------------

### Configure package.json for iOS Native Plugin

Source: https://nativesupport.dcloud.net.cn/NativePlugin/offline_package/ios.html

This JSON configuration is used in the package.json file to define the native plugin's details for iOS integration. It specifies plugin modules, integration type, and deployment target.

```json
{
	"name": "RichAlert",
	"id": "DCloud-RichAlert",
	"version": "0.1.3",
	"description": "示例插件",
	"_dp_type":"nativeplugin",
	"_dp_nativeplugin":{
		"ios": {
			"plugins": [
				{
					"type": "module",
					"name": "DCloud-RichAlert",
					"class": "DCRichAlertModule"
				}
			],
			"integrateType": "library",
			"deploymentTarget": "8.0"
		}
	}
}

```

--------------------------------

### Require Native Plugin

Source: https://nativesupport.dcloud.net.cn/NativePlugin/use/use.html

Use `uni.requireNativePlugin` to load a native plugin by its ID. Ensure the plugin ID matches the one registered in the native plugin market.

```javascript
const dcRichAlert = uni.requireNativePlugin('DCloud-RichAlert')
```
Tokens:
Raw