Skip to content
体验新版
项目
组织
正在加载...
登录
切换导航
打开侧边栏
DCloud
unidocs-zh
提交
7646011f
unidocs-zh
项目概览
DCloud
/
unidocs-zh
通知
3594
Star
108
Fork
920
代码
文件
提交
分支
Tags
贡献者
分支图
Diff
Issue
120
列表
看板
标记
里程碑
合并请求
108
DevOps
流水线
流水线任务
计划
Wiki
0
Wiki
分析
仓库
DevOps
项目成员
Pages
unidocs-zh
项目概览
项目概览
详情
发布
仓库
仓库
文件
提交
分支
标签
贡献者
分支图
比较
Issue
120
Issue
120
列表
看板
标记
里程碑
合并请求
108
合并请求
108
Pages
DevOps
DevOps
流水线
流水线任务
计划
分析
分析
仓库分析
DevOps
Wiki
0
Wiki
成员
成员
收起侧边栏
关闭侧边栏
动态
分支图
创建新Issue
流水线任务
提交
Issue看板
提交
7646011f
编写于
10月 17, 2022
作者:
DCloud_Heavensoft
浏览文件
操作
浏览文件
下载
电子邮件补丁
差异文件
Add new file ext api doc
上级
edf8bdcc
变更
1
隐藏空白更改
内联
并排
Showing
1 changed file
with
196 addition
and
0 deletion
+196
-0
docs/api/extapi.md
docs/api/extapi.md
+196
-0
未找到文件。
docs/api/extapi.md
0 → 100644
浏览文件 @
7646011f
## 什么是 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`
编辑
预览
Markdown
is supported
0%
请重试
或
添加新附件
.
添加附件
取消
You are about to add
0
people
to the discussion. Proceed with caution.
先完成此消息的编辑!
取消
想要评论请
注册
或
登录