From 7646011f1207a7b5d0dc9fd9eb9b84fb2aeb0b00 Mon Sep 17 00:00:00 2001
From: DCloud_Heavensoft <wanganxp@163.com>
Date: Mon, 17 Oct 2022 22:07:39 +0800
Subject: [PATCH] Add new file ext api doc

---
 docs/api/extapi.md | 196 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 196 insertions(+)
 create mode 100644 docs/api/extapi.md

diff --git a/docs/api/extapi.md b/docs/api/extapi.md
new file mode 100644
index 000000000..a5aa9c641
--- /dev/null
+++ b/docs/api/extapi.md
@@ -0,0 +1,196 @@
+## 什么是 uni ext api
+
+uni ext api，是一种需要下载[uni_modules](https://uniapp.dcloud.net.cn/plugin/uni_modules.html)插件才能使用的、uni.开头的js API。
+
+它是uni对象的方法，但不预置在uni-app的runtime中，需要单独下载对应的`uni_modules`。
+
+- 背景1，uni-app runtime越来越大
+
+uni对象的api，如uni.navigateTo，之前都是内置在uni-app的runtime中的，跟随uni-app/HBuilder的升级而变化。
+
+随着各家小程序和uni-app的演进，uni-app的api越来越多，而很多api又不常用，这会增加uni-app的runtime体积，尤其是在web和app平台。
+
+比如很多小程序都内置有`getBatteryInfo`获取电量的API，在uni-app中理应拉齐各端实现，但在uni-app的web和app上内置它并不合适。
+
+所以推出了`uni ext api`，这些API以`uni_modules`的方式出现，从插件市场单独下载。但导入到工程后，仍使用`uni.getBatteryInfo`方式来调用。
+
+为此，在这些`uni_modules`的`package.json`中提供了一种特殊的注册方式，允许插件向uni对象自动挂载api。（只有DCloud官方插件，以`uni-`开头的插件，才能使用此机制）
+
+- 背景2，uts将重构uni-app的内部实现
+
+在过去，uni-app的web和小程序端，是github的独立项目，由DCloud的js团队维护。而uni-app的app端，是另2个独立项目，由DCloud的原生团队维护。
+每次新加一个api，需要各个团队在不同的工程里开发，尤其是app端，需要先在原生项目里开发，然后在前端项目里封装。还需要再另一个语法提示工程中编写代码提示。
+
+有了uts后，uni-app的实现机制将被重构，大幅的简化。
+
+每个api，都使用uts这门统一的语言来开发，不再使用不同的技术语言。作为一个独立的`uni_modules`，独立的工程，有独立的版本。
+
+仍然以`uni.getBatteryInfo`电量为例，开发这个api，不再需要在庞大复杂的uni-app的若干个项目里编码，也不需要再关心功能间关联和耦合。
+
+只需要在`uni-getBatteryInfo`这个`uni_modules`下开发，目录结构如下。
+
+这个目录清晰的列出了这个插件要做的所有事情：在不同的目录下编写uts或js代码、在d.ts里写语法提示。
+
+```bash
+├── uni_modules
+│   ├── uni-getbatteryinfo
+│   │   ├── changelog.md
+│   │   ├── index.d.ts // 类型声明，需要同时扩展 uni 声明当前注册的 API
+│   │   ├── package.json
+│   │   ├── readme.md
+│   │   └── utssdk // 在不同目录实现平台能力
+│   │       ├── app-android
+│   │       │   └── index.uts
+│   │       ├── app-ios
+│   │       │   └── index.uts
+│   │       ├── mp-weixin
+│   │       │   └── index.js
+│   │       └── web
+│   │           └── index.js
+```
+
+这种模式，还给开发者带来若干好处，比如开放性和灵活性。
+
+	* 以往，uni-app内置api如果有bug，普通开发者很难看懂源码，很难参与完善。
+
+	现在，在uts的支持下，普通前端也可以review这些api的实现，发现其中的问题和提出改进方案。
+
+	* 以往，这些uni api的bug被修复时，需要等待HBuilder发版，由于每次发版都需要发很多功能，可能bug1虽然已经修好，但bug2复测出问题，导致版本不能及时发布。
+
+	现在，ext api的`uni_modules`脱离HBuilder独立升级，快速解决开发者的问题。并且开发者可以自己修本地工程中ext api的bug。让问题得以更快速的解决。
+
+- 背景3，内置api复写
+
+很多uni的内置api，比如`uni.showWaiting`，实现的比较简单，在web端，常见的waiting都有更丰富的样式、使用更多的图片资源。
+
+uni-app的runtime不适合内置很多waiting样式和资源，而使用三方插件，又需要按三方插件的写法调用，之前工程里写好的`uni.showWaiting`的代码不得不重改。
+
+有了`ext api`，可以实现一个`uni-showwaiting`的`uni_modules`，在web端提供更丰富的效果，并且开源，可自由裁剪和增补。
+
+导入这个`uni_modules`后，之前的`uni.showWaiting`的api的功能就被复写。
+
+
+综上，背景1、2、3的问题，都将使用`uni ext api`来解决。uni-app很多新增的、不常用的api将采用`ext api`方式。
+
+在uts的发展路线上，uni-app自身也将使用uts实现；使用uts将可以开发完整的uni-app。
+
+目前所有的`ext api`，在未来的uts版的uni-app，其内置的uni对象的api中，均会得到复用。也就是说`ext api`将大幅推进下一代uni-app（纯uts版）的上线速度。
+
+欢迎广大开发者参与到`uni ext api`的开源共建中来。
+
+## 注意事项
+
+1. 由于开发api是以uni.开头的，所以无法像普通插件那样由开发者自己开发、自己发布。
+
+参与共建的开发者需要在DCloud官方插件的开源项目中提pr，由官方审核后再发布新版uni_modules。
+
+也只有`uni-`开头的插件，才能在package.json中编写注册声明，挂载方法到uni对象上。
+
+2. `uni ext api`的版本将不再跟随HBuilder和uni-app cli的版本，它将是独立的版本。
+
+只有uni的内置api才跟随HBuilder升级。请记得内置api和`ext api`的区别。
+
+3. `ext api`在真机运行时，在如下情况需要打包自定义基座才能运行
+
+- iOS目前只能打包自定义基座。后续官方会继续优化
+- Android涉及arr、jar、so库等三方sdk的时候，也需打包自定义基座。
+
+4. wgt升级只对js、css生效，uts代码无法使用热更新
+
+## 如何开发uni ext api
+
+### 创建一个符合规则的`uni_modules`插件（通常是`utssdk`类型），如`uni-getbatteryinfo`
+
+**注意：** 插件ID格式为：`uni-API名称全小写`
+
+
+```bash
+├── uni_modules
+│   ├── uni-getbatteryinfo
+│   │   ├── changelog.md
+│   │   ├── index.d.ts // 类型声明，需要同时扩展 uni 声明当前注册的 API
+│   │   ├── package.json
+│   │   ├── readme.md
+│   │   └── utssdk // 在不同目录实现平台能力
+│   │       ├── app-android
+│   │       │   └── index.uts
+│   │       ├── app-ios
+│   │       │   └── index.uts
+│   │       ├── mp-weixin
+│   │       │   └── index.js
+│   │       └── web
+│   │           └── index.js
+```
+
+### 配置`package.json`
+
+```json
+{
+  "uni_modules": {
+    "uni-ext-api": {
+      "uni": ""// string | string[] | Record<string,string>
+    }
+  }
+}
+```
+
+- 默认导出
+
+```json
+{
+  "uni_modules": {
+    "uni-ext-api": {
+      "uni": "getBatteryInfo"
+      // 等同于
+      // import getBatteryInfo from "@/uni_modules/uni-getbatteryinfo";
+      // uni.getBatteryInfo = getBatteryInfo
+    }
+  }
+}
+```
+
+- 导出多个
+
+```json
+{
+  "uni_modules": {
+    "uni-ext-api": {
+      "uni": ["getBatteryInfo", "isCharging"]
+      // 等同于
+      // import { getBatteryInfo, isCharging } from "@/uni_modules/uni-getbatteryinfo";
+      // uni.getBatteryInfo = getBatteryInfo
+      // uni.isCharging = isCharging
+    }
+  }
+}
+```
+
+- 导出别名
+
+```json
+{
+  "uni_modules": {
+    "uni-ext-api": {
+      "uni": {
+        "onUserCaptureScreen": "onCaptureScreen",
+        "offUserCaptureScreen": "offCaptureScreen"
+      }
+      // 等同于
+      // import { onCaptureScreen, offCaptureScreen } from "@/uni_modules/uni-getbatteryinfo";
+      // uni.onUserCaptureScreen = onCaptureScreen
+      // uni.offUserCaptureScreen = offCaptureScreen
+    }
+  }
+}
+```
+
+- [示例(获取电量)参考](https://gitcode.net/dcloud/hello-uts/-/tree/dev/uni_modules/uni-getbatteryinfo)
+
+## 如何使用uni ext api
+
+在[插件市场](https://ext.dcloud.net.cn/)查找`uni ext api`插件，导入`HBuilderX`中的项目即可直接使用。
+
+
+如：[uni-getbatteryinfo](https://ext.dcloud.net.cn/plugin?name=uni-getbatteryinfo)，导入后，即可直接使用`uni.getBatteryInfo`
+
+
-- 
GitLab