Skip to content
体验新版
项目
组织
正在加载...
登录
切换导航
打开侧边栏
DCloud
unidocs-zh
提交
893e48cb
unidocs-zh
项目概览
DCloud
/
unidocs-zh
通知
3598
Star
108
Fork
921
代码
文件
提交
分支
Tags
贡献者
分支图
Diff
Issue
120
列表
看板
标记
里程碑
合并请求
109
DevOps
流水线
流水线任务
计划
Wiki
0
Wiki
分析
仓库
DevOps
项目成员
Pages
unidocs-zh
项目概览
项目概览
详情
发布
仓库
仓库
文件
提交
分支
标签
贡献者
分支图
比较
Issue
120
Issue
120
列表
看板
标记
里程碑
合并请求
109
合并请求
109
Pages
DevOps
DevOps
流水线
流水线任务
计划
分析
分析
仓库分析
DevOps
Wiki
0
Wiki
成员
成员
收起侧边栏
关闭侧边栏
动态
分支图
创建新Issue
流水线任务
提交
Issue看板
提交
893e48cb
编写于
5月 23, 2024
作者:
W
wanganxp
浏览文件
操作
浏览文件
下载
电子邮件补丁
差异文件
更新uni_modules概念
上级
264f6852
变更
1
隐藏空白更改
内联
并排
Showing
1 changed file
with
67 addition
and
39 deletion
+67
-39
docs/plugin/uni_modules.md
docs/plugin/uni_modules.md
+67
-39
未找到文件。
docs/plugin/uni_modules.md
浏览文件 @
893e48cb
# uni_modules
##
#
什么是 uni_modules
## 什么是 uni_modules
`uni_modules`
是uni-app的插件模块化规范(HBuilderX 3.1.0+支持),通常是对一组js sdk、组件、页面、uniCloud云函数、公共模块等的封装,用于嵌入到uni-app项目中使用,也支持直接封装为项目模板
。
主流的语言/平台,都有自己包管理方案,js的npm、Android的仓储、iOS的cocoapods、鸿蒙的ohpm、dart的pub。。
。
你可以简单理解,把一个项目的各种工程目录都挪到了一个uni_modules下,打包成了一个模块,这里面只要符合uni-app规范的文件都可以放
。
uni-app是大一统开发,包括客户端和uniCloud服务器。在客户端部分包括web、Android、iOS、各家小程序
。
插件开发者,可以像开发uni-app项目一样编写一个
`uni_modules`
插件,并在HBuilderX中直接上传至
[
插件市场
](
https://ext.dcloud.net.cn/
)
。
在uni-app中可以调用npm库,可以调用Android仓储里的aar,可以调用iOS的cocoapods里framework,以及鸿蒙的ohpm
。
插件使用者,可以在
[
插件市场
](
https://ext.dcloud.net.cn/
)
查找符合自己需求的
`uni_modules`
插件,使用HBuilderX 3.1.0+直接导入到自己的uni-app项目中。后续还可以在HBuilderX中直接点右键升级插件
。
甚至uts语言本身也可以编译为js、kotlin、swift
。
相对于普通的插件,
`uni_modules`
插件拥有更强的独立性,拥有独立的目录结构,可以更加方便的发布,更新,卸载(HBuilderX 3.1.0+对
`uni_modules`
插件提供了右键菜单,支持发布,更新,安装依赖等)
那么uni-app的开发者,需要一个大一统的包管理方案,那就是
`uni_modules`
。
相对于node_modules(node.js模块),
`uni_modules`
的三方依赖安装时默认最新版本,插件均直接安装在
`uni_modules`
目录下,不做嵌套,当然,如果开发者希望固定某个版本的依赖,可以将该三方依赖包含到自己的插件包内。
`uni_modules`
是uni-app的包管理方案(HBuilderX 3.1.0+支持),它是一个海纳百川型的设计,
-
不管是js/uts库、组件、页面、uniCloud云函数、公共模块等的封装,甚至是整个项目,都可以封装成一个
`uni_modules`
。(类似Android的aar)
-
不管是npm、Android仓储、iOS的cocoapods、鸿蒙的ohpm,都可以纳入
`uni_modules`
中。
为什么有了
`node_modules`
,还需要再发明一个
`uni_modules`
的轮子?
1.
`node_modules`
不满足云端一体的需求。uniCloud的云函数、公共模块、schema和前端的各种js_sdk、组件、页面、项目,无法在
`node_modules`
模式下有效融合。
2.
`uni_modules`
有付费和商业的插件,DCloud插件市场提供了版权保护。而
`node_modules`
不支持付费和版权保护。
3.
`node_modules`
是开发者友好而影响终端用户性能的模式。开发者为了省事,层层嵌套
`node_modules`
,造成数量惊人的文件数目。
`uni_modules`
不支持module嵌套,鼓励开发者优化包体积
4.
`uni_modules`
鼓励开发者总是使用最新版。并在HBuilderX中提供了版本内容对比工具
5.
`uni_modules`
里也支持放置
`node_modules`
,没有强行排斥。
由于uni-app有自己的项目目录结构规范(uni-app
[
详见
](
../tutorial/project.md
)
、uni-app x
[
详见
](
https://doc.dcloud.net.cn/uni-app-x/project.html
)
),
所以你可以简单理解,把一个项目的这些工程目录都挪到了一个uni_modules下,打包成了一个模块,这里面只要符合uni-app规范的文件都可以放。
详细的uni_modules目录结构
[
见下
](
#dir
)
### uni_modules的优势
1.
uni_modules支持在
[
插件市场
](
https://ext.dcloud.net.cn/
)
计费销售。由DCloud提供商业插件的代码加密和版权保护。
2.
HBuilderX提供了对
`uni_modules`
的便捷管理,可以对一个
`uni_modules`
点右键(如果是项目型
`uni_modules`
,是对根目录的package.json点右键),直接上传
`uni_modules`
、更新
`uni_modules`
、安装依赖。版本更新时还会给出新旧代码的详细对比。
与之前插件市场的普通插件相比,
`uni_modules`
有何优势?
1.
支持在HBuilderX里直接发布、更新、删除。而无需在web界面操作。
2.
支持依赖(在package.json中配置)
3.
插件文件位置统一
,不会造成下载一个插件,不知道给工程下多少个目录写入了多少个文件。删除插件时也可以一点
删除
3.
插件文件位置统一
。以往下载一个插件,不知道给工程下多少个目录写入了多少个文件,这种困惑不再存在。删除插件时也可以一处统一
删除
`uni_modules`
同时也是一种大型工程的模块分割方案。比如一个旅游应用,可以把机票、酒店、火车票、自由行等模块分拆成不同的
`uni_modules`
,由不同的部门来开发。
### 目录结构
有
`node_modules`
了,为何还发明一个
`uni_modules`
的轮子?
1.
`node_modules`
不满足全平台包管理需求,无法容纳Android仓储、iOS的cocoapods、鸿蒙的ohpm。
2.
`node_modules`
不满足云端一体的需求。uniCloud的云函数、公共模块、schema和前端部分,无法在
`node_modules`
模式下有效融合。很多组件是云端一体组件,即有客户端又有服务器,需要按uni-app的目录规范放置。
3.
`uni_modules`
有付费和商业的插件,DCloud插件市场提供了版权保护。而
`node_modules`
不支持付费和版权保护。
4.
`node_modules`
层层嵌套
`node_modules`
,造成数量惊人的文件数目。
`uni_modules`
支持依赖但不支持module嵌套,鼓励开发者优化包体积。当然这算差异,并非
`uni_modules`
的优势
5.
`uni_modules`
在js支持的平台,也容纳了
`node_modules`
,没有排斥。
#### 项目插件的uni_modules
除了发布插件,
`uni_modules`
同时也是一种大型工程的模块分割方案。比如一个旅游应用,可以把机票、酒店、火车票、自由行等模块分拆成不同的
`uni_modules`
,由不同的部门来开发。
## 目录结构@dir
### 项目插件的uni_modules
`uni_modules`
插件如果是项目类型的插件,只需要在项目的根目录下放一个符合
`uni_modules`
规范的package.json。
...
...
@@ -38,7 +51,7 @@
比如
[
uni-admin
](
https://ext.dcloud.net.cn/plugin?id=3268
)
、
[
uni-starter
](
https://ext.dcloud.net.cn/plugin?id=5057
)
,都可以通过这种方式更新。
###
#
非项目插件的uni_modules
### 非项目插件的uni_modules
如果是非项目类型的插件,比如组件、js sdk、页面模板、云函数,则需要放置在项目的
`uni_modules`
目录下。
...
...
@@ -66,7 +79,7 @@ uni_modules 项目根目录下
也就是
`uni_modules`
目录下相当于复制一遍uni-app的项目结构。
**Tips**
-
插件目录不支持pages.json、App.vue
、main.j
s、manifest.json、uni.scss文件,如果需要插件使用者修改这些文件内容,请在插件文档(readme.md)中详细说明。
-
插件目录不支持pages.json、App.vue
/uvue、main.js/ut
s、manifest.json、uni.scss文件,如果需要插件使用者修改这些文件内容,请在插件文档(readme.md)中详细说明。
-
插件目录支持
`pages_init.json`
,可以方便注册页面到项目的pages.json中,
[
见下
](
?id=pages-init
)
-
在插件内部引用资源、跳转页面时,请尽量使用相对路径。
-
插件内components目录同样支持easycom规范,插件使用者可以直接在项目中使用插件内符合easycom规范的组件,当项目或插件内存在easycom组件冲突,编译时会给予提示,您可以通过修改组件目录及组件文件名称来解决冲突问题。
...
...
@@ -80,8 +93,23 @@ uni_modules 项目根目录下
HBuilderX 中打开配有引用图标指示的文件,会打开原始地址。
### 使用 uni_modules 插件
#### 下载uni_modules插件
#### uts插件
在uni_modules的utssdk目录,可以放置uts插件。
uts插件是非常重要的一种跨端插件。它支持API插件和组件插件。
在utssdk目录下,可以放置一个interface.uts的声明,然后可以新建app-android、app-ios、web、mp-weixin、app-harmony等目录,每个目录下可以存放不同客户端平台的代码。
以获取电量的API为例,uni.getBatteryInfo(),在根目录的interface.uts中定义了api的对外暴露接口、定义统一的错误码,然后在各个客户端平台的目录中,实现电量获取这个API。
uni.getBatteryInfo的插件和源码详见:
[
https://ext.dcloud.net.cn/plugin?id=9295
](
https://ext.dcloud.net.cn/plugin?id=9295
)
在app-android、app-ios目录,可以放置Android原生的aar、iOS原生的framework,也支持配置Android仓储和iOS的cocoapods。
uts插件开发的详细指南见:
[
https://doc.dcloud.net.cn/uni-app-x/plugin/uts-plugin.html
](
https://doc.dcloud.net.cn/uni-app-x/plugin/uts-plugin.html
)
## 使用 uni_modules 插件
### 下载uni_modules插件
1.
在
[
插件市场
](
https://ext.dcloud.net.cn/
)
查找uni_modules插件
2.
在插件详情页,右侧会标明该插件是否支持uni_modules,点击
`使用 HBuilderX 导入插件`

...
...
@@ -98,24 +126,24 @@ import {test} from '@/uni_modules/xx-yy/js_sdk/test.js'
-
如果要使用uni_modules中的页面,
[
见下
](
#pages-init
)
###
#
安装uni_modules插件依赖
### 安装uni_modules插件依赖
1.
导入插件时,HBuilderX会自动安装当前插件的所有三方依赖。
2.
您还可以在插件目录右键手动执行
`安装插件三方依赖`

###
#
更新uni_modules插件
### 更新uni_modules插件
1.
可以通过插件目录右键
`从插件市场更新`
,来检查更新当前所使用的插件

2.
对比插件,确认更新内容

###
#
卸载uni_modules插件
### 卸载uni_modules插件
uni_modules插件目录是独立存在的,如果您不再需要该插件,可以直接删除该插件目录。
**Tips**
-
导入uni_modules规范插件需要使用 3.1.0 以上版本的 HBuilderX
##
#
配置
###
#
package.json@package-json
## 配置
### package.json@package-json
package.json在每个
`uni_modules`
插件中都必须存在,包含了插件的基本信息。以下是package.json的详细配置说明
```
json
...
...
@@ -220,7 +248,7 @@ package.json在每个`uni_modules`插件中都必须存在,包含了插件的
###
#
uni_modules.config.json
### uni_modules.config.json
`uni_modules.config.json`
在项目根目录,可以配置插件更新后的触发脚本(通常用于执行自定义的自动化任务),插件uniCloud支持的服务空间。以下是
`uni_modules.config.json`
的详细配置说明
```
json
{
...
...
@@ -238,12 +266,12 @@ package.json在每个`uni_modules`插件中都必须存在,包含了插件的
```
**Tips**
-
当项目内仅关联了一个服务空间,此时
uni_modules
插件内的uniCloud相关资源会自动归属至该服务空间,无需在uni_modules.config.json中配置uniCloud所属服务空间
-
当项目内仅关联了一个服务空间,此时
`uni_modules`
插件内的uniCloud相关资源会自动归属至该服务空间,无需在uni_modules.config.json中配置uniCloud所属服务空间
-
当项目内关联了两个服务空间(阿里云和腾讯云同时存在)
*
若未在uni_modules.config.json中配置平台,则上传该插件uniCloud资源时,会提示上传至选择哪个服务空间
*
若已在uni_modules.config.json中配置平台,则上传时以配置为准,自动归属至指定的服务空间
###
#
npmignore@npmignore
### npmignore@npmignore
uni_modules插件发布到插件市场是通常需要忽略掉一些目录或文件,比如
`unpackage`
、
`.hbuilderx`
、
`node_modules`
等,这时可以通过npmignore文件来实现文件的忽略。
...
...
@@ -260,7 +288,7 @@ package-lock.json
-
项目根目录下的
`.npmignore`
对发布项目、插件模板生效。
`uni_modules/插件Id/.npmignore`
对发布插件生效
###
#
pages_init页面注册@pages-init
### pages_init页面注册@pages-init
> 新增于HBuilderX 3.5.0+
过去,插件作者提供页面类插件时,需要在文档中手动告知使用者在pages.json中注册哪些页面。如:
...
...
@@ -314,8 +342,8 @@ HBuilderX中合并路由界面效果图:
-
`pages_init.json`
暂不支持带注释(包括:条件编译)。
-
如果HBuilderX版本低于3.5,或插件作者并没有提供
`pages_init.json`
,那么仍然需要手动编辑pages.json注册页面。
##
#
开发 uni_modules 插件
###
#
新建uni_modules目录
## 开发 uni_modules 插件
### 新建uni_modules目录
在uni-app项目根目录下,创建uni_modules目录,在HBuilderX中可以项目右键菜单中点击
`新建uni_modules目录`

...
...
@@ -323,7 +351,7 @@ HBuilderX中合并路由界面效果图:
**Tips:**
-
如果是vue-cli项目,uni_modules目录,位于
`src`
下,即
`src/uni_modules`
###
#
新建uni_modules插件
### 新建uni_modules插件
1.
在HBuilderX中uni_modules目录右键点击
`新建uni_modules插件`

...
...
@@ -340,8 +368,8 @@ HBuilderX中合并路由界面效果图:
**Tips**
-
`uni_modules`
插件可以在package.json的
`uni_modules->dependencies`
节点配置三方依赖(依赖的插件也必须是
`uni_modules`
插件),如果是依赖了三方的npm插件,可以使用标准的dependencies节点配置。
通过 uni_modules->dependencies 配置三方
`uni_modules`
插件依赖
```
json
//
通过
uni_modules->dependencies
配置三方uni_modules插件依赖
{
"id"
:
"uni-badge"
,
"displayName"
:
"uni-badge 数字角标"
,
...
...
@@ -353,8 +381,8 @@ HBuilderX中合并路由界面效果图:
}
```
###
#
发布到插件市场
当您的插件开发完毕,可以直接发布到
[
插件市场
](
https://ext.dcloud.net.cn/
)
供其他人免费或付费使用,插件市场提供了变现、评价等机制,优秀的插件作者
,可以做到月入好几万
。
### 发布到插件市场
当您的插件开发完毕,可以直接发布到
[
插件市场
](
https://ext.dcloud.net.cn/
)
供其他人免费或付费使用,插件市场提供了变现、评价等机制,优秀的插件作者
可以做到月入数万元
。
发布流程:
...
...
@@ -365,7 +393,7 @@ HBuilderX中合并路由界面效果图:
**Tips**
-
如果需要发布为项目模板,请在项目根目录创建package.json,然后右键菜单发布到插件市场。
-
发布插件时,可以选择上传当前项目作为示例工程,完整的示例工程,可以方便用户快速上手。
###
#
修改插件基本信息
### 修改插件基本信息
当您的插件发布到插件市场后,如果需要调整插件市场上的一些基本信息,比如插件中文名称,描述,关键词,readme.md等,可以直接在插件目录右键
`修改插件基本信息`
1.
在HBuilderX中插件目录右键点击
`修改插件基本信息`
...
...
@@ -373,14 +401,14 @@ HBuilderX中合并路由界面效果图:
2.
修改插件基本信息

###
#
发布新版本
### 发布新版本
当您的插件增加了新的功能或修复了Bug,需要发布新版本时,操作与第一次发布一样,可以直接在插件目录右键
`发布到插件市场`
**Tips**
-
在发布窗口中填写的更新日志,会自动与根目录的changelog.md保持同步
##
#
已有插件迁移为 uni_modules 插件指南
## 已有插件迁移为 uni_modules 插件指南
1.
将插件内容迁移至您的uni-app示例项目根目录
`uni_modules`
下以插件ID命名的目录下,举例,若您已有的插件ID为
`xx-yy`
,则目录结构为:
`uni_modules/xx-yy`
2.
运行自己的示例项目,验证插件迁移目录后,所有功能是否正常
...
...
编辑
预览
Markdown
is supported
0%
请重试
或
添加新附件
.
添加附件
取消
You are about to add
0
people
to the discussion. Proceed with caution.
先完成此消息的编辑!
取消
想要评论请
注册
或
登录