uni-app x 插件生态开发指南uni_modules 包管理、uts 插件与插件市场全解析【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-appuni-app x 通过一套开放、兼容的插件系统将前端组件、uts SDK、页面模板、项目模板与原生能力封装统一纳入官方插件市场与uni_modules包管理规范。本文以仓库 docs/plugin/README.md 为骨架结合 uni_modules 规范、uts 插件开发、插件发布与变现 等配套文档及仓库源码系统讲解 uni-app x 插件生态的构成、跨平台原生能力的封装方式以及插件从开发、发布到商业化的完整链路帮助读者快速上手插件开发与生态接入。一、uni-app x 插件生态总览uni-app x 积极拥抱社区创建了开放、兼容的插件系统。整个生态围绕两条主线展开官方插件市场uni-app x 官方插件生态集中地支持前端组件、uts SDK、页面模板、项目模板、uts 插件等多种类型。uni_modules 包管理方案海纳百川式的大一统包管理设计可同时容纳 npm、Android 仓储、iOS 的 CocoaPods、鸿蒙的 ohpm 等各类库方便封装跨平台插件。生态建设有一条明确的设计原则把常用的部分 uni 化不常用的各平台特色不限制使用都可以在条件编译里调用。这意味着 uni-app x 在统一多端开发体验的同时并不封锁平台独有的能力而是提供统一与个性化之间的平衡点。各平台生态接入方式根据编译目标平台的不同插件生态的接入方式如下编译目标可调用的生态能力Web浏览器全部 API可混合使用 JS可使用 web 生态的各种库含 npm小程序小程序全部 API可混合使用 JS小程序自定义组件生态如 wxml 组件、小程序 npm 库AndroidAndroid OS 全部 API可混合使用 Kotlin、Java可使用所有适配 Android 的 SDK含 so 库、gradle 仓储iOSiOS 全部 API可混合使用 SwiftObjective-C 需封装为库后使用不能直接使用 OC 源码可使用所有适配 iOS 的 SDK含 CocoaPodsHarmony鸿蒙全部 API可混合使用 ArkTS可使用所有适配鸿蒙的 SDK含 ohpm在非 Web 平台使用 Web 生态当编译到不支持 web 的平台时如需使用 web 生态内容官方提供了三种途径在 uni-app x 的web-view组件内使用 web 库uni-app x 提供了 web-view 组件内 js 和 uts 的通信机制集成 uni 小程序 SDK或集成 v8/quickjs 等库来调用 js 生态内容从蒸汽模式起app 平台兼容 js/ts 生态npm 上很多流行库可以直接使用。二、插件市场插件分类与付费机制插件市场按7 大类、20 多个子类对插件进行分类具体体系如下插件市场一级分类二级分类DCloud 市场前端组件通用组件、nvue 组件、小程序组件、DataCom 组件JS SDK通用 SDK、微信小程序 SDK、Native.jsuts 插件API 插件、组件插件uni-app 前端模板前端页面模板、nvue 页面模板、uni-app 前端项目模板App 原生插件App 原生插件web 项目web 项目模板uniCloud云函数模板、云端一体页面模板、云端一体项目模板、Admin 插件、DB Schema 及验证函数HBuilderXHBuilderX、语言包市场还提供优秀作者及热门插件排行榜并支持对 uniCloud 插件、uts/原生插件设置付费销售对免费插件设置先看广告后下载的广告解锁机制。付费插件版本机制付费插件支持普通授权版与源码授权版两种形式两者功能完全一致本质是同一套代码区别在于代码可见性与授权范围版本名称代码保护授权交易方式普通授权版部分源码不可见基于该项目和/或该服务空间的使用权、未加密部分的二次开发权买方自助下单即买即用买方实名信息对卖方保密源码授权版所有代码源码可见完整的二次开发权、完整可控的基于源码审查的安全性签署带数字签名的三方电子协议先签协议后付款获取源码插件作者上传插件时可仅选择普通授权版源码授权版为可选项也可拒绝与特定买家签订源码授权版的电子合同。加密文件的清单由插件作者配置无论试用还是购买普通授权版都看不到加密文件源码。各类型付费插件的试用机制uts 插件针对项目申请试用插件内容对试用者不可见只能用于打包自定义基座不能用于正式发布无有效期限制App 原生插件针对项目申请试用插件不下载只能用于云端打包自定义基座uniCloud 插件针对服务空间申请试用加密云函数试用期一般 7 天结束后自动删除前端组件针对项目申请试用只能用于本地运行或打包自定义基座。详细机制可参阅 插件市场介绍 与 插件变现指南。三、uni_modules大一统的包管理方案什么是 uni_modules主流语言/平台都有自己的包管理方案——js 有 npm/yarn/pnpmAndroid 有仓储iOS 有 CocoaPods鸿蒙有 ohpm。而 uni-app 是大一统开发涵盖客户端与 uniCloud 服务器客户端又包括 web、Android、iOS 与各家小程序。因此 uni-app 需要一个大一统的包管理方案这就是uni_modulesHBuilderX 3.1.0 支持。它是一个海纳百川型的设计不管是 js/uts 库、组件、页面、uniCloud 云函数、公共模块甚至是整个项目都可以封装成一个uni_modules类似 Android 的 aar不管是 npm、Android 仓储、iOS 的 CocoaPods、鸿蒙的 ohpm都可以纳入uni_modules中。可以简单理解把一个项目符合 uni-app 规范的工程目录整体挪到一个uni_modules下打包成一个模块。与 node_modules 的对比既然已有node_modules为何还需要uni_modulesnode_modules不满足全平台包管理需求无法容纳 Android 仓储、iOS 的 CocoaPods、鸿蒙的 ohpmnode_modules不满足云端一体需求uniCloud 的云函数、公共模块、schema 与前端部分无法有效融合uni_modules支持付费与商业插件DCloud 插件市场提供版权保护而node_modules不支持node_modules层层嵌套造成海量文件数uni_modules支持依赖但不支持 module 嵌套鼓励优化包体积uni_modules在 js 支持的平台同样容纳node_modules没有排斥。除发布插件外uni_modules也是大型工程的模块分割方案。例如旅游应用可以把机票、酒店、火车票等模块分拆为不同的uni_modules由不同团队并行开发。目录结构非项目类型插件组件、js sdk、页面模板、云函数需放置在项目的uni_modules目录下其目录结构与 uni-app 项目结构一致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注册动态菜单注意事项插件目录不支持pages.json、App.vue/uvue、main.js/uts、manifest.json、uni.scss文件如需使用者修改这些内容请在 readme.md 中说明插件目录支持pages_init.json可方便地注册页面到项目的 pages.json插件内引用资源、跳转页面尽量使用相对路径插件内 components 目录支持 easycom 规范与项目内组件冲突时编译会提示可通过修改组件目录及文件名解决。在 HBuilderX 中uni_modules下包含的 uniCloud 目录内容会以引用方式显示在主项目根目录的 uniCloud 中文件图标左下角显示快捷方式箭头。仓库 src/uni_modules 下提供了大量可参考的插件实例例如 uni-getbatteryinfo含 package.json、readme.md、changelog.md 与 utssdk 目录、uni-storage、uni-network、uni-payment 等。package.json 插件配置package.json在每个uni_modules插件中必须存在包含插件基本信息。以 HBuilderX 4.71 为分界平台兼容性规范有所不同。HBuilderX 4.71 之前版本规范节选{ id: 作者ID-插件英文名称, // 必填格式如xx-yy作者ID和插件名称只能包含英文、数字 displayName: 插件显示名称, // 必填 version: 1.0.0, // 必填 description: 插件描述, // 必填 keywords: [], // 必填最多5个 repository: github:user/repo, // 仓库地址 engines: { // HBuilderX/cli 最低兼容版本 HBuilderX: ^3.1.0 }, dcloudext: { // DCloud插件市场配置 category: [前端组件, 通用组件], type: component-vue, // 插件市场分类标识 sale: { // 销售目前仅限uniCloud类插件 regular: { price: 0.00 }, sourcecode: { price: 0.00 } }, contact: { qq: }, declaration: { // 隐私、权限及商业化声明 ads: , data: , permissions: }, npmurl: }, uni_modules: { scripts: { init: node scripts/init.js }, dependencies: [], // 依赖的 uni_modules 插件ID列表 encrypt: [ // 配置云函数、公共模块、clientDB Action加密 uniCloud/cloudfunctions/uni-admin/controller/permission.js ], platforms: { // 平台兼容性y 支持 / n 不支持 / u 不确定默认为 u cloud: { tcb: y, aliyun: y }, client: { ... } }, treeShaking: { // 摇树配置 app: { android: true, ios: true, harmony: false }, web: false } } }HBuilderX 4.71 起平台兼容性改版平台兼容性针对 uni-app 与 uni-app x 两个维度拆分兼容性标记由 y/n/u 调整为√支持、x不支持、-不确定默认值新增多语言、暗黑模式、宽屏模式定义client 节点下增加uni-app、uni-app-x两个子节点分别维护兼容性数据。使用旧版 HBuilderX 发布时插件市场会自动转换为新版规范为获得准确兼容性设置建议升级到 HBuilderX 4.71 发布。完整配置示例见 uni_modules 文档。摇树配置treeShakingtrue表示项目代码中使用到该模块时才打包false表示即使未使用也包含默认值为true。可全局配置布尔值也可按平台分别配置。uni_modules.config.json 与 .npmignoreuni_modules.config.json位于项目根目录用于配置插件更新后的触发脚本如 postupdate、preupload、postupload可通过process.env.UNI_MODULES_ID获取被更新的插件 ID以及插件 uniCloud 所属的服务空间。当项目同时关联阿里云与腾讯云两个服务空间时可通过该文件手动指定归属仅关联一个服务空间时无需配置。.npmignore用于发布时忽略目录或文件典型内容.hbuilderx unpackage node_modules package-lock.json注意项目根目录的.npmignore对发布项目、插件模板生效uni_modules/插件Id/.npmignore对发布插件生效。pages_init.json 页面注册pages_init.jsonHBuilderX 3.5.0解决插件页面注册问题。当 uni_modules 插件根目录存在该文件时导入工程会弹出合并页面路由的 pages.json 修改界面点击确认即完成页面注册{ pages: [{ path: uni_modules/uni-feedback-admin/pages/uni-feedback-admin/add, style: { navigationBarTitleText: 新增 } } ] }注意pages_init.json最终不会导入工程暂不支持注释包括条件编译HBuilderX 低于 3.5 时仍需手动编辑 pages.json 注册页面。HBuilderX 中的日常操作下载插件详情页点击使用 HBuilderX 导入插件选择目标 uni-app 项目即可支持 easycom 组件直接使用其他资源按目录结构引入如import {test} from /uni_modules/xx-yy/js_sdk/test.js安装依赖导入时 HBuilderX 自动安装所有三方依赖也可在插件目录右键手动执行安装插件三方依赖更新插件目录右键从插件市场更新并可对比新旧代码确认更新内容卸载直接删除插件目录即可。四、uts 插件用一门语言封装全部原生能力uts 语言与 uts 插件utsuni type script是统一、强类型的脚本语言可编译为不同平台语言web 平台编译为 JavaScriptAndroid 平台编译为 KotliniOS 平台编译为 SwiftHX 3.6.7harmonyOS 平台编译为 ArkTSHX 4.22。它采用与 ts 基本一致的语法规范支持绝大部分 ES6 API。uts 语言既可用于开发独立 Appuni-app x也可用于开发插件。uts 插件利用 uts 语法操作原生 API手机 OS API 或三方 SDK封装成 uni_modules 插件供前端调用uni-app 中由 js 调用 uts 插件HBuilderX 3.6 支持 vue3 编译器3.6.8 支持 vue2uni-app x 中由 uts 调用 uts 插件HBuilderX 3.9 支持。一个 uts 插件可同时支持 uni-app 与 uni-app x并分目录编写所有平台代码同时支持 App、web、小程序。uts 插件分两类API 插件扩展 API 能力在 script 里调用即便涉及 UI 也多为全屏窗口或弹出窗口组件插件扩展界面组件在 template 里调用内嵌在页面中。仓库中 src/uni_modules/uni-getbatteryinfo 即为官方电量插件的完整示例uni-app x 版本其utssdk目录下按平台拆分实现。uts 插件目录结构├─static // 静态资源 ├─utssdk │ ├─app-android //Android平台目录 │ │ ├─assets //Android原生assets资源目录可选 │ │ ├─libs //Android原生库目录jar/aar/so可选 │ │ ├─res //Android原生res资源目录可选 │ │ ├─AndroidManifest.xml //Android原生应用清单文件可选 │ │ ├─config.json //Android原生配置文件 │ │ ├─hybrid.kt //Android混编的kt文件 │ │ └─index.uts //Android原生插件能力实现 │ ├─app-ios //iOS平台目录 │ │ ├─Frameworks //三方 framework/xcframework 依赖库可选 │ │ ├─Libs //三方 .a 依赖库可选 │ │ ├─Resources //合并到应用Main Bundle的资源可选 │ │ ├─EmbedResources //合并到动态库Framework Bundle的资源HBuilderX5.08可选 │ │ ├─info.plist //合并到主 info.plist 的配置可选 │ │ ├─UTS.entitlements //合并到主工程 entitlements 的配置可选 │ │ ├─config.json //iOS原生配置文件 │ │ ├─hybrid.swift //iOS混编的swift文件 │ │ ├─interceptor.js //js调用插件代码的拦截器 │ │ └─index.uts //iOS原生插件能力实现 │ ├─web //web平台目录 │ │ ├─package.json //web平台插件依赖配置 │ │ └─index.uts │ ├─mp-weixin / mp-alipay / mp-baidu ... //各小程序平台目录可选 │ ├─interface.uts //声明插件对外暴露的API必需 │ ├─unierror.uts //定义插件对外暴露的错误信息可选 │ └─index.uts //跨平台插件入口可选 └─package.json //插件清单文件必需入口规则根目录index.uts是程序主入口分平台目录存在index.uts时优先使用分平台实现否则回退到根目录。代码组织有三种方式根目录 index.uts 写条件编译简单业务一个文件搞定根目录 index.uts 写条件编译并 import 分平台文件不写根目录 index.uts直接在分平台目录写实现仅做单端插件时更简单。interface.uts与index.uts是声明与实现的关系在 interface.uts 中声明的类型HBuilderX 会自动识别并给出语法提示。平台原生配置Androidapp-android 目录目录/文件用途assets原生 assets 资源目录建议只放插件内置资源libs三方 jar/aar/so 库目录本地调试不支持直接使用 so需封装为 AAR 或分别集成 so 与 jarres原生 res 资源目录AndroidManifest.xml原生应用清单文件config.json原生配置文件index.uts主入口interface.uts 声明能力在 Android 下的实现config.json支持配置abisNDK so 库支持的 CPU 类型armeabi-v7a、arm64-v8a、x86、x86_64、dependencies仓储依赖字符串项按implementation方式、JSON 对象项按 source 字段作为 gradle 源码合并进 build.gradle、minSdkVersionuni-app 最低 19/Android 4.4.2uni-app x 最低 21/Android 5.0以及projectgradle 插件白名单com.google.gms.google-services、com.huawei.agconnect、com.hihonor.mcs.asplugin等。完整配置示例见 uts-plugin.md。iOSapp-ios 目录目录/文件用途Frameworks三方 framework/xcframework 依赖库支持静态库与动态库Libs三方 .a 依赖库HBuilderX 3.7.2Resources合并到应用 Main Bundle 的资源EmbedResources合并到动态库 Framework Bundle 的资源HBuilderX 5.08Info.plist合并到原生工程 Info.plist 的配置PrivacyInfo.xcprivacyiOS 隐私清单文件UTS.entitlements合并到原生工程 entitlements 的配置config.json原生配置文件index.uts主入口实现iOSconfig.json支持frameworks依赖系统库、deploymentTarget最低 iOS 版本默认 12.0、identifier插件 Bundle Identifier、validArchitecturesCPU 架构默认 arm64、dependencies-pods依赖 pod 库HBuilderX 3.8.5与dependencies-pod-resourcespod 资源存放位置HBuilderX 5.25uni-app 默认 alluni-app x 默认 framework。iOS Extension 支持详见文档中iOS Extension章节。鸿蒙app-harmony 目录主要包含 index.uts为主入口、interface.uts 声明能力在 harmony 平台下的实现。开发一个 API 插件示例以官方文档的uts-api为例流程为在uni_modules目录右键新建 uni_modules 插件 → 编写 interface.uts → 编写 unierror.uts → 在分平台 index.uts 实现。interface.uts统一定义对外暴露的 API 类型、参数类型、返回值类型与错误码类型export type MyApiOptions { paramA : boolean success ?: (res : MyApiResult) void fail ?: (res : MyApiFail) void complete ?: (res : any) void } export type MyApiResult { fieldA : number, fieldB : boolean, fieldC : string } // 错误码遵循uni错误规范建议以90开头 export type MyApiErrorCode 9010001 | 9010002; export interface MyApiFail extends IUniError { errCode : MyApiErrorCode }; export type MyApi (options : MyApiOptions) void export type MyApiSync (paramA : boolean) MyApiResultunierror.uts实现错误主题、错误信息映射与错误对象import { MyApiErrorCode, MyApiFail } from ./interface.uts export const UniErrorSubject uts-api; export const UTSApiUniErrors : MapMyApiErrorCode, string new Map([ [9010001, custom error mseeage1], [9010002, custom error mseeage2], ]); export class MyApiFailImpl extends UniError implements MyApiFail { override errCode: MyApiErrorCode constructor(errCode : MyApiErrorCode) { super(); this.errSubject UniErrorSubject; this.errCode errCode; this.errMsg UTSApiUniErrors.get(errCode) ?? ; } }随后在app-android/index.uts等平台目录实现业务逻辑异步方法 myApi 与同步方法 myApiSync前端在 uvue 中按如下方式使用import { myApi, myApiSync, MyApiOptions } from /uni_modules/uts-api; let options { paramA: false, complete: (res : any) { console.log(res) } } as MyApiOptions; myApi(options); console.log(myApiSync(true))注意import uts 插件只能到插件根目录不能引入内部文件uvue 中禁止直接导入 utssdk 目录下的 uts 文件。获取电量插件完整示例文档以获取电量为完整案例。Android 平台实现import Context from android.content.Context; import BatteryManager from android.os.BatteryManager; import { UTSAndroid } from io.dcloud.uts; export function getBatteryCapacity(): string { const context UTSAndroid.getAppContext(); if (context ! null) { const manager context.getSystemService( Context.BATTERY_SERVICE ) as BatteryManager; const currentLevel: number manager.getIntProperty( BatteryManager.BATTERY_PROPERTY_CAPACITY ); return currentLevel %; } return 0%; }iOS 平台通过UIDevice实现import { UIDevice } from UIKit; export function getBatteryLevel():number { UIDevice.current.isBatteryMonitoringEnabled true let level Number(UIDevice.current.batteryLevel * 100) return level }鸿蒙平台通过ohos.batteryInfo实现。前端调用显性引用import { getBatteryCapacity } from /uni_modules/uts-getbatteryinfo; console.log(getBatteryCapacity())亦支持泛型引用import * as UTSHello from /uni_modules/uts-osapi。该电量插件在仓库中的 uni-app x 版本可参考 src/uni_modules/uni-getbatteryinfo。应用生命周期监听与数据交互iOS自定义 class 遵循UTSiOSHookProxy协议即可监听应用生命周期需 export 才会参与编译自动注册可监听启动、远程/本地通知、url scheme 唤起、前后台切换、Universal Link 等回调。协议定义见 UTSiOSHookProxy。Android实现UTSAndroidHookProxy接口的onCreate(application)可在 Application 初始化时执行三方 SDK 初始化。注意初始化早于 uni不支持调用 uni api不支持调用 UTSAndroid 的 getAppContext/getAppActivity一个插件只允许实现一个该接口的 class建议判断隐私合规同意后再初始化。接口定义见 UTSAndroidHookProxy。鸿蒙暂不支持此能力。UTS 与 uni-app 环境数据交互UTS 向 uni-app 传值支持 TS 基本数据类型与 UTSJSONObjectuni-app 向 UTS 传值支持基本类型、type 类型与 UTSJSONObject声明为 any 时 Object 也会被转换为 UTSJSONObject。复杂参数含对象数组目前需将成员声明为 any 数组再通过new UTSJSONObject(item)包装访问。UTSJSONObject 的完整用法见 contenteditable="false">【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考