Skip to content
体验新版
项目
组织
正在加载...
登录
切换导航
打开侧边栏
没有积善却想登上天堂
unidocs-zh
提交
7646011f
U
unidocs-zh
项目概览
没有积善却想登上天堂
/
unidocs-zh
与 Fork 源项目一致
Fork自
DCloud / unidocs-zh
通知
1
Star
0
Fork
0
代码
文件
提交
分支
Tags
贡献者
分支图
Diff
Issue
0
列表
看板
标记
里程碑
合并请求
0
DevOps
流水线
流水线任务
计划
Wiki
0
Wiki
分析
仓库
DevOps
项目成员
Pages
U
unidocs-zh
项目概览
项目概览
详情
发布
仓库
仓库
文件
提交
分支
标签
贡献者
分支图
比较
Issue
0
Issue
0
列表
看板
标记
里程碑
合并请求
0
合并请求
0
Pages
DevOps
DevOps
流水线
流水线任务
计划
分析
分析
仓库分析
DevOps
Wiki
0
Wiki
成员
成员
收起侧边栏
关闭侧边栏
动态
分支图
创建新Issue
流水线任务
提交
Issue看板
体验新版 GitCode,发现更多精彩内容 >>
提交
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.
先完成此消息的编辑!
取消
想要评论请
注册
或
登录