UTS插件全面介绍与开发指南

UTS Plugin Introduction

Introduction

HBuilderX 3.6+ supports the development of UTS plugins, enabling developers to extend native capabilities across platforms using a unified syntax.

What is UTS Language

UTS, short for Uni Type Script, is a unified, strongly-typed scripting language. It compiles into platform-specific programming languages: JavaScript for the web, Kotlin for Android, and Swift for iOS (supported by HBuilderX 3.6.7+). UTS adopts the same syntax specification as TypeScript and supports most ES6 APIs. For detailed UTS syntax, refer to the UTS syntax introduction.

UTS can be used to develop standalone apps via uni-app x or to create plugins known as UTS plugins.

What is a UTS Plugin

A UTS plugin utilizes UTS syntax to interact with native APIs (including OS APIs or third-party SDKs) and packages them as a uni_modules plugin for front-end invocation. In uni-app, JavaScript calls the UTS plugin (supported by HBuilderX 3.6 for Vue 3 and 3.6.8 for Vue 2). In uni-app x, UTS calls the UTS plugin (supported by HBuilderX 3.9). Thus, a single UTS plugin can support both uni-app and uni-app x.

For cross-platform compatibility, UTS plugins can organize code into directories for each platform (e.g., app-android, app-ios, web, mp-weixin), allowing extensions beyond App to web and mini-programs. An example is the Battery plugin, which works in both uni-app and uni-app x.

UTS plugins come in two types: API plugins and component plugins. API plugins extend API capabilities called within scripts, while component plugins extend UI components embedded in templates. For instance, a Lottie animation UTS plugin is a component plugin.

Difference Between UTS Plugin and Uni Native Language Plugin

When compiled for the App platform, UTS plugins functionally equate to the traditional App native plugins in uni-app, both extending native capabilities. However, UTS plugins are written in UTS syntax, eliminating the need to learn Kotlin or Swift, though familiarity with Android and iOS system APIs is required.

Before HBuilderX 3.6, uni-app supported only "App native language plugins" developed in Java or Objective-C. With UTS, these were renamed to distinguish the development language. Both yield native binary code but differ in language and tooling.

Key Advantages of UTS Plugins:

1. Unified programming language (UTS) for all platforms.
2. Unified development tool (HBuilderX), avoiding complex native environment setup.
3. Simplified concepts: UTS integrates purely into front-end workflows, reducing complexities like JS-native communication.
4. Unified debugging within HBuilderX for front-end and native code.
5. UTS plugins in the marketplace support version pinning after download.
6. Paid UTS plugins support source code sales with protection mechanisms.
7. UTS plugins support both uni-app and uni-app x.

For plugin authors, more details on differences are available in the publishing guide.

Difference Between UTS Plugin and Native.js

• Native.js runs on JavaScript, invoking OS APIs via reflection, with limited functionality and performance.
• UTS runs truly natively, not in the JS engine on App.

Creating a UTS Plugin

UTS Plugin Directory Structure

In a uni-app project, UTS plugins are stored in the utssdk directory. Using uni_modules for package management is recommended. Ensure a uni_modules folder exists in the project root; create it manually if absent.

To create a new plugin, right-click the uni_modules directory, select "New Plugin," and choose "uts plugin." It's advisable to use a custom prefix to avoid conflicts with marketplace plugins.

The directory structure typically includes:

• common/ for cross-platform UTS code.
• static/ for static resources.
• utssdk/ with subdirectories for each platform (e.g., app-android, app-ios, web, mp-weixin).
• package.json for plugin configuration.
• index.uts as the main entry point, with platform-specific implementations in subdirectories.

The index.d.ts file declares plugin capabilities for type hints but is deprecated in favor of interface.uts.

App Native Configuration

Android Platform Native Configuration

The app-android folder contains:

• assets/: Native assets resources (for built-in plugin files).
• libs/: Third-party libraries (jar, aar, so files). Prefer repository dependencies over local files to avoid conflicts.
• res/: Native res resources (for built-in files).
• AndroidManifest.xml: Native manifest configuration.
• config.json: Configuration for dependencies, ABIs, minSdkVersion, etc.

Note: Native configurations require cloud packaging or custom debuggers to take effect. HBuilderX includes common Android dependencies; avoid manually adding conflicting jars/aars.

iOS Platform Native Configuration

The app-ios folder contains:

• Frameworks/: Third-party framework dependencies.
• Libs/: Third-party .a libraries (supported from HBuilderX 3.7.2+).
• Resources/: Native resource files.
• Info.plist: Configuration merged into the native project.
• UTS.entitlements: Entitlements configuration.
• config.json: Settings for frameworks, deploymentTarget, validArchitectures, and dependencies-pods.

Developing a UTS Plugin

Example: Battery Plugin

Create a UTS plugin named uts-getbatteryinfo under uni_modules.

Android Platform

In app-android/index.uts, implement the battery retrieval using Android APIs. The code can expose synchronous or asynchronous interfaces. HBuilderX provides code hints for Android APIs via the io.dcloud.uts.android library.

iOS Platform

In app-ios/index.uts, implement using iOS APIs, similarly supporting synchronous or asynchronous patterns.

Application Lifecycle Hook Listening

Supported from HBuilderX 3.97+.

iOS Platform

Implement a class conforming to UTSiOSHookProxy to listen to lifecycle events like app launch or push notifications. The class must be exported and will auto-register.

Android Platform

Implement the UTSAndroidHookProxy interface to execute code in Application.onCreate. Note: This doesn't support uni API calls, and only one class per plugin can implement it. Privacy compliance should be checked before initialization.

Data Interaction Between UTS and uni-app

UTS can pass values to uni-app as: basic TypeScript types (number, string, boolean) or UTSJSONObject. uni-app can pass values to UTS as: basic types, type data, or UTSJSONObject. When declared as any, objects from uni-app become UTSJSONObject in UTS.

Currently, complex parameter passing (e.g., arrays of objects) requires using any[] and accessing elements via UTSJSONObject. Improvements are planned.

Front-end Usage of Plugins

Front-end code (JavaScript or TypeScript) can reference UTS plugins without requiring TypeScript.

General Import:
Import the entire plugin as an object and call its methods or properties.

Explicit Import:
Import specific exports for direct use.

Always import from the plugin root directory, not specific platform files.

The battery plugin example is available on the marketplace with support for Android, web, and mini-programs.

Real Machine Running

UTS Supports Real Machine Running

UTS plugins can run on real devices with hot refresh and console.log support (downloading the "uts compile and run plugin" if missing).

Android Platform

Similar to uni-app, supports hot refresh and logging.

iOS Platform

• Below HBuilderX 3.6.9: Requires custom debuggers via cloud packaging.
• HBuilderX 3.6.9+: Supports local compilation and real device running.

Custom Debuggers

Custom debuggers are needed for UTS plugins involving:

• Integrated third-party SDKs.
• New resources (res/assets, etc.).

On iOS, if XCode is not installed (Windows or Mac without XCode), cloud packaging is required for custom debuggers.

Debug Breakpoint Debugging

UTS plugins support debug breakpoints on both Android and iOS.

Legacy Issues

As of HBuilderX 3.6.9: Android doesn't support cross-process debugging/logging; console.log works only in the current process.

Cloud Packaging

Cloud packaging is supported, but UTS compiles to pure native binary code and doesn't support wgt hot updates.

Common Problems

Common Errors

• Failed to resolve entry: Ensure HBuilderX 3.6.0+ for Vue 3 or 3.6.8+ for Vue 2.
• File not found: Check version requirements.
• UTSCallback: From HBuilderX 3.7.7, use specific function types instead of UTSCallback.

Float Type Parameters

In Android, use toFloat() for float conversions.

Long Type Parameters

Use toLong() for long conversions.

Asynchronous Tasks

Currently, only Android supports Promises; iOS can use setTimeout.

Anonymous Inner Classes

UTS doesn't support anonymous inner classes; declare an implementation class and instantiate it.

Generic Parameters

Use type assertions or helper classes for generics in Android UI APIs.

Function Parameter Default Values

Supported, e.g., function test(name: string = "default").

Export Limitations in uni-app 1.0

In uni-app 1.0 (JS environment), only UTS-declared custom objects/classes/methods can be exported, not native objects, due to the JS runtime handling.

Accessing JSON Object Properties

Use subscript notation (e.g., user['age']) instead of dot notation. For dot operator, use type definitions.

Example Projects

• DCloud's Hello UTS: GitCode.
• Marketplace UTS plugins: Battery API, Tencent Location, Lottie component.
• Explore more at: UTS Plugins.