English
uni_modules
is the plug-in modular specification of uni-app (supported by HBuilderRX 3.1.0+), which is usually the encapsulation of a group of js sdk, components, pages, uniCloud cloud functions, public modules, etc. It is used for embedding in uni-app projects, and also supports direct encapsulation as project templates.
你可以简单理解,把一个项目的各种工程目录都挪到了一个uni_modules下,打包成了一个模块,这里面只要符合uni-app规范的文件都可以放。
Plug-in developers can write a uni_modules
plug-in just like developing a uni-app project, and upload it directly to the plug-in market in HBuilderX.
Plug-in users can find the uni_modules
plugin that meets their needs in Plugin Market, and use HBuilderX 3.1.0+ to directly import it into their uni-app project. You can also directly right-click in HBuilderX to upgrade the plug-in later.
Compared with ordinary plug-ins, the uni_modules
plug-in has stronger independence and independent directory structure, and can be released, updated and uninstalled more conveniently (HBuilderX 3.1.0+ provides a right-click menu for the uni_modules
plug-in, and supports publishing, updating, installation dependency, etc.)
Compared with node_modules (node.js module), the third party dependency of uni_modules
defaults to the latest version during installation. Plug-ins are directly installed in the uni_modules
directory without nesting. Of course, if developers want to fix a version of dependencies, they can include the third-party dependencies in their plug-in packages.
Why do we need to invent another uni_modules
wheel after having node_modules
?
node_modules
does not meet the needs of cloud integration. UniCloud's cloud functions, public modules, schema and various js_sdk, components, pages and projects in the front end cannot be effectively integrated in the node_modules
mode.uni_modules
is provided in the form of paid and commercial plug-ins, and the DCloud plug-in market provides copyright protection. But node_modules
does not support payment and copyright protection.node_modules
is a developer-friendly mode that affects the performance of end users. To save trouble, developers nested node_modules
layer by layer, resulting in an astonishing number of files. uni_modules
Module nesting is not supported, and developers are encouraged to optimize package’s sizeuni_modules
encourages developers to always use the latest version. And tools for version content comparison are provided in HBuilderXnode_modules
placing is also supported in uni_modules
, without forced rejection.与之前插件市场的普通插件相比,uni_modules
有何优势?
uni_modules
同时也是一种大型工程的模块分割方案。比如一个旅游应用,可以把机票、酒店、火车票、自由行等模块分拆成不同的uni_modules
,由不同的部门来开发。
If the uni_modules
plugin is a project type plugin, you only need to put a package.json that conforms to the uni_modules
specification in the root directory of the project.
Right-click on the package.json to update the project plugin or publish it to the plugin marketplace.
For example uni-admin, uni-starter , can be updated in this way.
If it is a plug-in of non-project type, such as component, js sdk, page template and cloud function, it needs to be placed in the uni_modules
directory of the project.
At this time, the directory structure under the uni_modules
directory is the same as the project structure of uni-app, as follows:
uni_modules 项目根目录下
└── [plugin_id] // 插件 ID
├── uniCloud 插件内的uniCloud内容会被虚拟合并到项目根目录的uniCloud中(注意:插件内的uniCloud目录,没有-aliyun,-tcb后缀)
├── components 符合vue组件规范的uni-app组件目录,支持easycom规范
├── utssdk 存放uts插件
├── hybrid 存放本地网页的目录,详见
├── pages 业务页面文件存放的目录
├── static 存放应用引用静态资源(如图片、视频等)的目录,注意:静态资源只能存放于此
├── wxcomponents 存放小程序组件的目录,详见
├── license.md 插件使用协议说明
├── package.json 插件配置,必选(除此之外均`可选`)
├── readme.md 插件文档
├── changelog.md 插件更新日志
├── menu.json 如果是uniCloud admin插件,可以通过menu.json注册动态菜单,详见 menu.json 配置
That is, the uni_modules
directory is equivalent to duplicating the project structure of uni-app.
Tips
pages_init.json
, which can easily register pages to the project's pages.json, see belowIn HBuilderX, if uni_modules
contains the contents of the uniCloud directory, it will be displayed in uniCloud in the root directory of the main project by way of reference. A shortcut arrow will appear in the lower left corner of the icon in front of the file.
As shown in the figure below, there is a uni_modules
named uni-config-center
in the project, which contains a public module named uni-config-center
. Therefore, under the common module directory common in the project root directory, there will also be an additional uni-config-center
.
Opening a file indicated by a reference icon in HBuilderX will open the original address.
使用 HBuilderX 导入插件
Tips
import {test} from '@/uni_modules/xx-yy/js_sdk/test.js'
安装插件三方依赖
从插件市场更新
,来检查更新当前所使用的插件
The uni_modules plug-in directory is standalone. If you no longer need the plug-in, you can delete it directly.
Tips
package.json must exist in every uni_modules
plug-in and contains the basic information of plug-ins. The following is a detailed configuration description of package.json
{
//Note that you cannot directly copy this code into the editor, and package.json currently does not support comments. The comments added in this paragraph are only used to explain the code.
"id": "作者ID-插件英文名称", // 必填,插件ID,格式为:'作者ID-插件英文名称',例如:'xx-yy',其中作者ID和插件名称只能包含英文、数字,作者ID不能使用'DCloud'、'uni'等关键字
"displayName": "插件显示名称", // 必填,用于展示在插件市场的显示名称
"version": "1.0.0", // 必填,插件版本
"description": "插件描述", // 必填,插件描述
"keywords": [], // 必填,插件标签关键词,最多5个
"repository": "github:user/repo", // 仓库地址
"engines": { // HBuilderX/cli 最低兼容版本
"HBuilderX": "^3.1.0"
},
"dcloudext": { // DCloud插件市场配置
"category": ["前端组件", "通用组件"], // 可选(HBuilderX低于3.6.0时必填), 插件市场分类
"type": "component-vue", // 必填(HBuilderX 3.6.0 以上支持),插件市场分类标识,分类标识可以参考下边列出的表格
"sale": { // 销售 (目前仅限uniCloud类插件)
"regular": { // 普通授权版价格,单位为元,如果为免费插件,设置普通授权版价格为 0 即可。
"price": "0.00"
},
"sourcecode": { // 源码授权版价格,单位为元
"price": "0.00"
}
},
"contact": { // 插件作者 QQ,方便管理员审核时与作者快速沟通。
"qq": ""
},
"declaration": { // 隐私、权限及商业化声明
"ads": "", // 必填,本插件是否包含广告,如包含需详细说明广告表达方式、展示频率,请如实填写,如不包含,可填“无”
"data": "", // 必填,本插件采集的数据、发送的服务器地址、以及数据用途说明,请如实填写,如不采集任何数据,可填写“插件不采集任何数据”,如果使用的三方SDK需要采集数据,可填写“插件使用的 XX SDK会采集数据,详情可参考:https://other-sdk.com/"
"permissions": "" // 必填,本插件需要申请的系统权限列表,请如实填写,如不需要任何权限,可填“无”
},
"npmurl":"" // npm 地址
},
"uni_modules": { // uni_modules配置
"scripts": {
"init": "node scripts/init.js" // 新增于 HBuilderX 3.6.7,初次安装此插件时执行,如果一次安装多个插件及依赖会在所有插件安装完毕执行
},
"dependencies": [], // 依赖的 uni_modules 插件ID列表
"encrypt": [ // 配置云函数,公共模块,clientDB Action加密
"uniCloud/cloudfunctions/uni-admin/controller/permission.js" // 注意这里是真实的文件路径,uni_modules下的uniCloud不带-aliyun、-tcb后缀,但是项目根目录下的uniCloud是带有后缀的
],
"platforms": { // 平台兼容性:y 表示 Yes,支持;n 表示 No,不支持;u 表示 Unknown,不确定;默认为 u
"cloud": { // 云端平台兼容性
"tcb": "y",
"aliyun": "y"
},
"client": { // 前端平台兼容性
"App": {
"app-vue": "y",
"app-nvue": "n"
},
"H5-mobile": {
"Safari": { // 当需要指定最小版本才支持时,可以配置minVersion
"minVersion": "14.0.2"
},
"Android Browser": "y",
"微信浏览器(Android)": "u",
"QQ浏览器(Android)": "u"
},
"H5-pc": {
"Chrome": "y",
"IE": "u",
"Edge": "u",
"Firefox": "u",
"Safari": "u"
},
"小程序": {
"微信": "y",
"阿里": "y",
"百度": "y",
"抖音": "y",
"QQ": "y"
},
"快应用": {
"华为": "u",
"联盟": "u"
}
}
}
}
}
Tips
Primary classification | Secondary classification | type |
---|---|---|
Front-end components | Common components | component-vue |
front-end components | MiniApp components | component-mp |
JS SDK | Universal SDK | sdk-js |
uts plugin | uts plugin | uts |
uni-app front-end template | front-end page template | uniapp-template-page |
uni-app front-end template | uni-app front-end project template | uniapp-template-project |
uniCloud | cloud function template | unicloud-template-function |
uniCloud | Cloud One Page Template | unicloud-template-page |
uniCloud | Cloud-integrated project template | unicloud-template-project |
uniCloud | Admin plugin | unicloud-admin |
uniCloud | DB Schema and validation functions | unicloud-database |
uni_modules.config.json
In the root directory of the project, you can configure the trigger script updated by the plug-in (usually used to perform customized automation tasks) and the service space supported by the plug-in uniCloud. The following is a detailed configuration description of uni_modules.config.json
{
"scripts": {
"postupdate": "node scripts/upgrade.js", // 更新插件后执行该脚本,可从process.env.UNI_MODULES_ID获取当前被更新的插件ID,如果存在多个,以,隔开
"preupload": "node scripts/preupload.js", // 上传插件之前执行该脚本,可从process.env.UNI_MODULES_ID获取当前被更新的插件ID,如果存在多个,以,隔开
"postupload": "node scripts/postupload.js" // 上传插件之后(无论上传成功还是失败)执行该脚本,可从process.env.UNI_MODULES_ID获取当前被更新的插件ID,如果存在多个,以,隔开
},
"uni_modules": {
"uni-id": { // 插件ID
"uniCloud": ["aliyun", "tcb"] // 当项目同时存在aliyun,tcb时可手动指定该插件所属的服务空间
}
}
}
Tips
When uni_modules plug-in is released to plug-in market, it is usually necessary to ignore some directories or files, such as unpackage
, .hbuilderx
, node_modules
and so on, then the file can be ignored by npmignore file.
File name: .npmignore. Note that there is a dot at the beginning. Contents of a typical npmignore file are as follows:
.hbuilderx
unpackage
node_modules
package-lock.json
Notice
.npmignore
in the project root directory is effective for publishing projects and plug-in templates. uni_modules/Plug-in Id/.npmignore
Effective for published plug-insAdded in HBuilderX 3.5.0+
In the past, when plugin authors provided page class plugins, they needed to manually inform users in the documentation which pages to register in pages.json. like:
{
"pages":[{
"path":"uni_modules/xx-yy/pages/demo/demo" // 按插件所在目录引入对应的页面
}]
}
pages_init.json
solves this annoyance.
When the pages_init.json
file exists in the root directory of the uni_modules plugin, when the plugin imports the project, a pages.json modification interface for merging page routes will pop up. Plug-in users click the Confirm button to complete the registration of the plug-in page to the project pages.json.
Example plugin: Problem Feedback Page Admin Template
The sample code is as follows:
{
"pages": [{
"path": "uni_modules/uni-feedback-admin/pages/uni-feedback-admin/add",
"style": {
"navigationBarTitleText": "新增"
}
},
{
"path": "uni_modules/uni-feedback-admin/pages/uni-feedback-admin/edit",
"style": {
"navigationBarTitleText": "编辑"
}
},
{
"path": "uni_modules/uni-feedback-admin/pages/uni-feedback-admin/list",
"style": {
"navigationBarTitleText": "列表"
}
}
]
}
Complete pages parameters details view
Notice
pages_init.json
file will not eventually be imported into the project.pages_init.json
does not support annotations (including: conditional compilation).pages_init.json
, you still need to manually edit the pages.json registration page.In the root directory of the uni-app project, create the uni_modules directory, and you can click Create uni_modules directory
on the right-click menu of the project.
Tips:
src
, which is src/uni_modules
Create uni_modules plug-in
Plugin ID naming specification:
Tips
uni_modules
plug-in can be configured with three-party dependencies in the uni_modules->dependencies
node of package.json (the dependent plug-in must also be the uni_modules
plug-in). If it is an npm plug-in that relies on three parties, you can use the standard dependencies node configuration.// 通过 uni_modules->dependencies 配置三方uni_modules插件依赖
{
"id": "uni-badge",
"displayName": "uni-badge 数字角标",
"version": "1.2.2",
"description": "数字角标(徽章)组件,在元素周围展示消息提醒,一般用于列表、九宫格、按钮等地方。",
"uni_modules": {
"dependencies": ["uni-scss"]
}
}
When your plug-in is developed, you can publish it directly to the plug-in market for free or paid use by others. The plug-in market provides mechanisms such as realization and evaluation. Excellent plug-in authors can earn tens of thousands of dollars a month.
Release process:
发布到插件市场
When your plug-in is released to the plug-in market, if you need to adjust some basic information in the plug-in market, such as Chinese name, description, keywords, and readme.md, you can right-click the Modify the plug-in basic information
directly in the plug-in directory.
修改插件基本信息
When your plug-in has added new functions or fixed bugs, and a new version needs to be released, the operation is the same as that of the first release, and you can right-click the Release to plug-in market
directly in the plug-in directory.
Tips
uni_modules
. For example, if your existing plug-in ID is xx-yy
, the directory structure is: uni_modules/xx-yy
{
"id":"您的插件ID"
}
Release to plug-in market
, select the classification, and fill in the plug-in information (consistent with the existing information in the plug-in market as much as possible)uni_modules
版本和非uni_modules
版本(仅保留最后一个非uni_modules
版本)