This page is translated by Google Cloud Translation API

Switch to Chinese

What is uni ext api

Added in HBuilderX 3.6.7

uni ext api is a js API starting with uni. that needs to be downloaded from the uni_modules plug-in.

It is a method of the uni object, but it is not preset in the runtime of uni-app, and the corresponding uni_modules needs to be downloaded separately.

Example:

uni.getBatteryInfo, this API is an ext api, you need to download a plug-in to use it. See details

• Background 1, uni-app runtime is getting bigger and bigger

The api of the uni object, such as uni.navigateTo, was built in the runtime of uni-app before, and changes with the upgrade of uni-app/HBuilder.

With the evolution of various MiniApp and uni-apps, uni-apps have more and more APIs, and many APIs are not commonly used, which will increase the runtime volume of uni-apps, especially on web and app platforms.

For example, many MiniApp have a built-in getBatteryInfo API for obtaining power, which should be implemented in all ends of the uni-app, but it is not appropriate to build it into the web and app of the uni-app.

So the uni ext api was launched, these APIs appear in the form of uni_modules, downloaded separately from the plug-in market. However, after importing to the project, it is still called by uni.getBatteryInfo.

To this end, a special registration method is provided in the package.json of these uni_modules, which allows the plugin to automatically mount the api to the uni object. (Only DCloud official plugins, which start with uni-, can use this mechanism)

• Background 2, uts will refactor the internal implementation of uni-app

In the past, the web and MiniApp of uni-app were independent projects on github, maintained by DCloud's js team. The app side of uni-app is another two independent projects, maintained by DCloud's native team. Every time a new API is added, each team needs to develop it in different projects, especially the app side, which needs to be developed in the native project first, and then encapsulated in the front-end project. You also need to write code hints in another syntax hinting project.

With uts, the implementation mechanism of uni-app will be reconstructed and greatly simplified.

Each API is developed using the unified language of uts, instead of using different technical languages. As an independent uni_modules, independent project, with independent version.

Still taking uni.getBatteryInfo as an example, to develop this api, it is no longer necessary to code in several projects of the huge and complex uni-app, and there is no need to care about the correlation and coupling between functions.

Only need to develop under the uni_modules of uni-getBatteryInfo, the directory structure is as follows.

This directory clearly lists all the things this plugin needs to do: write uts or js code in different directories, and write syntax hints in d.ts.

├── uni_modules
│   ├── uni-getbatteryinfo
│   │   ├── changelog.md
│   │   ├── index.d.ts // 类型声明，需要同时扩展 uni 声明当前注册的 API，将废弃，使用interface.uts代替
│   │   ├── interface.uts  // 声明插件对外暴露的API及类型
│   │   ├── package.json
│   │   ├── readme.md
│   │   └── utssdk // 在不同目录实现平台能力
│   │       ├── app-android
│   │       │   └── index.uts
│   │       ├── app-ios
│   │       │   └── index.uts
│   │       ├── mp-weixin
│   │       │   └── index.js
│   │       └── web
│   │           └── index.js

This model also brings several benefits to developers, such as openness and flexibility.

• In the past, if there were bugs in the built-in API of uni-app, it was difficult for ordinary developers to understand the source code and participate in the improvement.

Now, with the support of uts, ordinary front-ends can also review the implementation of these APIs, find problems and propose improvement plans.

• In the past, when these uni api bugs were fixed, it was necessary to wait for the release of HBuilder. Since each release required a lot of functions, it may be that although bug 1 has been fixed, bug 2 has been re-tested, causing the version to not be released in time.

Now, uni_modules of ext api is upgraded independently from HBuilder, quickly solving developers' problems. And developers can fix ext api bugs in local projects by themselves. Let the problem be solved more quickly.

• Background 3, built-in api replication

Many uni's built-in APIs, such as uni.showWaiting, are relatively simple to implement. On the web side, common waiting has richer styles and uses more image resources.

The runtime of uni-app is not suitable for many built-in waiting styles and resources, and the use of third-party plug-ins needs to be called according to the writing method of the third-party plug-ins. The code of uni.showWaiting written in the previous project had to be rewritten.

With ext api, you can implement a uni_modules of uni-showwaiting, which provides richer effects on the web side, and is open source, free to cut and supplement.

After importing this uni_modules, the function of the previous uni.showWaiting api is overwritten.

To sum up, the problems of background 1, 2, and 3 will be solved by using uni ext api. Many new and infrequently used APIs in uni-app will use ext api.

On the development route of uts, uni-app itself will also be implemented using uts; using uts will allow the development of a complete uni-app.

All current ext api will be reused in the built-in uni object api of the future uts version of uni-app. That is to say, ext api will greatly promote the launch speed of the next generation uni-app (pure uts version).

Developers are welcome to participate in the open source co-construction of uni ext api.

Precautions

1. Since the development api starts with uni., it cannot be developed and released by the developers themselves like ordinary plug-ins.

Developers participating in the co-construction need to submit a pr in the open source project of DCloud's official plug-in, and the new version of uni_modules will be released after the official review.

Only plug-ins starting with uni- can write registration statements in package.json and mount methods to uni objects.

2. The version of uni ext api will no longer follow the version of HBuilder and uni-app cli, it will be an independent version.

Only uni's built-in api is upgraded along with HBuilder. Please remember the difference between built-in api and ext api.

3. The implementation of ext api is not necessarily all uts, but if uts is used, it will be subject to the constraints of uts itself. Such as

• uts must be packaged with a custom base to run on the real machine on iOS. Subsequent official will continue to optimize
• When uts involves three-party SDKs such as arr, jar, and so libraries on Android, it also needs to package a custom base to run on the real machine.
• The wgt upgrade only takes effect for js and css, and the uts code cannot be hot updated. But this does not mean that the project using uts loses the hot update ability, but the uts part cannot be hot updated. js, vue, css, and images can still be packaged into wgt hot updates.

4. ext api在入口文件export的API，必须在package.json中编写注册声明

How to develop uni ext api

Create a conforming uni_modules plugin (usually of type utssdk), such as uni-getbatteryinfo

Note: The plugin ID format is: uni-API name all lowercase

├── uni_modules
│   ├── uni-getbatteryinfo
│   │   ├── changelog.md
│   │   ├── interface.uts // 类型声明
│   │   ├── package.json
│   │   ├── readme.md
│   │   └── utssdk // 在不同目录实现平台能力
│   │       ├── app-android
│   │       │   └── index.uts
│   │       ├── app-ios
│   │       │   └── index.uts
│   │       ├── mp-weixin
│   │       │   └── index.js
│   │       └── web
│   │           └── index.js

Configure package.json

{
  "uni_modules": {
    "uni-ext-api": {
      "uni": ""// string | string[] | Record<string,string>
    }
  }
}

• default export

{
  "uni_modules": {
    "uni-ext-api": {
      "uni": "getBatteryInfo"
      // import getBatteryInfo from "@/uni_modules/uni-getbatteryinfo";
      // uni.getBatteryInfo = getBatteryInfo
    }
  }
}

• Export multiple

{
  "uni_modules": {
    "uni-ext-api": {
      "uni": ["getBatteryInfo", "isCharging"]
      // import { getBatteryInfo, isCharging } from "@/uni_modules/uni-getbatteryinfo";
      // uni.getBatteryInfo = getBatteryInfo
      // uni.isCharging = isCharging
    }
  }
}

• export aliases

{
  "uni_modules": {
    "uni-ext-api": {
      "uni": {
        "onUserCaptureScreen": "onCaptureScreen",
        "offUserCaptureScreen": "offCaptureScreen"
      }
      // import { onCaptureScreen, offCaptureScreen } from "@/uni_modules/uni-getbatteryinfo";
      // uni.onUserCaptureScreen = onCaptureScreen
      // uni.offUserCaptureScreen = offCaptureScreen
    }
  }
}

• 指定支持的运行环境

{
  "uni_modules": {
    "uni-ext-api": {
      "uni": {
        "request": {
          "name": "request", // 可选别名配置
          "app": {// 表示在app平台，仅在iOS swift环境下生效
            "js": false,
            "kotlin": false,
            "swift": true
          }
        }
      }
    }
  }
}

注意：

• 所有 uni ext api 均需要提供 utssdk/interface.uts 文件

• 所有对外暴露的方法，类型均需要在 interface.uts 中定义

• 在具体平台实现中，通过引用 interface.uts 中的定义的方法，类型来约束实现

• 声明对象字面量时，必须指定具体类型，如：const res:GetBatteryInfoSuccess = { level:10,.. }

• 命名规范：

  • API入参类型命名为API名称首字母大写 + 'Options'，

  如 uni.getBatteryInfo(options)，则 options 类型命名为：type GetBatteryInfoOptions = {}

  • 异步API success,fail 回调结果类型命名为API名称首字母大写 + 'Success' 和 API名称首字母大写 + 'Fail'

  如 uni.getBatteryInfo() 的 success,fail 回调结果类型为：type GetBatteryInfoSuccess = {} 和 type GetBatteryInfoFail = {}

  • 事件API 回调结果类型命名为API名称首字母大写 + 'CallbackResult'

  如 uni.onUserCaptureScreen 的 callback 回调结果类型为：type OnUserCaptureScreenCallbackResult = {}

• 示例(获取电量)参考

• HBuilderX3.96及以下使用uni ext api后，云打包同时勾选android和iOS会导致打出来的包不能正确包含uni ext api插件，解决方案：升级至3.97+或android和iOS单独打包

How to use uni ext api

Find uni ext api plug-in in plug-in market, import the project in HBuilderX and use it directly.

For example: uni-getbatteryinfo, after importing, you can directly use uni.getBatteryInfo