提交 893e48cb 编写于 作者: W wanganxp

更新uni_modules概念

上级 264f6852
# 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.js、manifest.json、uni.scss文件,如果需要插件使用者修改这些文件内容,请在插件文档(readme.md)中详细说明。
- 插件目录不支持pages.json、App.vue/uvue、main.js/uts、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 导入插件`
![](https://qiniu-web-assets.dcloud.net.cn/unidoc/zh/import_uni_modules.png)
......@@ -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. 您还可以在插件目录右键手动执行`安装插件三方依赖`
![](https://qiniu-web-assets.dcloud.net.cn/unidoc/zh/deps_uni_modules.png)
#### 更新uni_modules插件
### 更新uni_modules插件
1. 可以通过插件目录右键`从插件市场更新`,来检查更新当前所使用的插件
![](https://qiniu-web-assets.dcloud.net.cn/unidoc/zh/check_uni_modules.png)
2. 对比插件,确认更新内容
![](https://qiniu-web-assets.dcloud.net.cn/unidoc/zh/compare_uni_modules.png)
#### 卸载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目录`
![](https://qiniu-web-assets.dcloud.net.cn/unidoc/zh/mkdir_uni_modules.png)
......@@ -323,7 +351,7 @@ HBuilderX中合并路由界面效果图:
**Tips:**
- 如果是vue-cli项目,uni_modules目录,位于`src`下,即`src/uni_modules`
#### 新建uni_modules插件
### 新建uni_modules插件
1. 在HBuilderX中uni_modules目录右键点击`新建uni_modules插件`
![](https://qiniu-web-assets.dcloud.net.cn/unidoc/zh/create_uni_modules.png)
......@@ -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. 修改插件基本信息
![](https://qiniu-web-assets.dcloud.net.cn/unidoc/zh/update_uni_modules_dialog.png)
#### 发布新版本
### 发布新版本
当您的插件增加了新的功能或修复了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.
先完成此消息的编辑!
想要评论请 注册