覃苗宇
覃苗宇

uniapp学习总结

目录

uniapp介绍

uni-app组成和跨端原理

什么是编译器

pages.json 页面路由

配置项列表

globalStyle

#基础组件

#扩展组件的意义

#组件的类别

#easycom组件规范

#uni_module规范

#uniCloud组件

#原生组件和原生插件

#datacom

#如何封装组件

#扩展组件（uni-ui）

组件

API

uniapp介绍

uni-app 是一个使用 Vue.js 开发所有前端应用的框架，开发者编写一套代码，可发布到iOS、Android、Web（响应式）、以及各种小程序（微信/支付宝/百度/头条/飞书/QQ/快手/钉钉/淘宝）、快应用等多个平台。uni-app组成和跨端原理

uni-app组成和跨端原理

基本语言和开发规范

uni-app代码编写，基本语言包括js、vue、css。以及ts、scss等css预编译器。

在app端，还支持原生渲染的nvue，以及可以编译为kotlin和swift的uts。

DCloud还提供了使用js编写服务器代码的uniCloud云引擎。所以只需掌握js，你可以开发web、Android、iOS、各家小程序以及服务器等全栈应用。

为了实现多端兼容，综合考虑编译速度、运行性能等因素，uni-app 约定了如下开发规范：

  • 页面文件遵循 Vue 单文件组件 (SFC) 规范，即每个页面是一个.vue文件
  • 组件标签靠近小程序规范，详见uni-app 组件规范
  • 接口能力（JS API）靠近小程序规范，但需将前缀 wx、my 等替换为 uni，详见uni-app接口规范
  • 数据绑定及事件处理同 Vue.js 规范，同时补充了应用生命周期及页面的生命周期
  • 如需兼容app-nvue平台，建议使用flex布局进行开发

uni-app分编译器和运行时（runtime）。uni-app能实现一套代码、多端运行，是通过这2部分配合完成的。

编译器将开发者的代码进行编译，编译的输出物由各个终端的runtime进行解析，每个平台（Web、Android App、iOS App、各家小程序）都有各自的runtime。

什么是编译器

uni-app能实现一套代码、多端运行，核心是通过编译器 + 运行时实现的：

  • 编译器：将uni-app统一代码编译生成每个平台支持的特有代码；如在小程序平台，编译器将.vue文件拆分生成wxml、wxss、js等代码。
  • 运行时：动态处理数据绑定、事件代理，保证Vue和平台宿主数据的一致性；

uni-app项目根据所依赖的Vue版本不同，编译器的实现也不同：

  • vue2：uni-app编译器基于wepback实现
  • vue3：uni-app编译器基于Vite实现，编译速度更快，详见：vue3和vite双向加持，uni-app性能再次提升

uni-app项目根据创建方式的不同，编译器在使用上也有差异：

  • cli 方式创建的项目，编译器安装在项目下。编译器不会跟随HBuilderX升级。如需升级编译器，可以参考：更新依赖到指定版本。
  • HBuilderX可视化界面创建的项目，编译器在HBuilderX的安装目录下的plugin目录，随着HBuilderX的升级会自动升级编译器。
  • 已经使用cli创建的项目，如果想继续在HBuilderX里使用，可以把工程拖到HBuilderX中。注意如果是把整个项目拖入HBuilderX，则编译时走的是项目下的编译器。如果是把src目录拖入到HBuilderX中，则走的是HBuilderX安装目录下plugin目录下的编译器。

pages.json 页面路由

pages.json 文件用来对 uni-app 进行全局配置，决定页面文件的路径、窗口样式、原生的导航栏、底部的原生tabbar 等。

它类似微信小程序中app.json的页面管理部分。注意定位权限申请等原属于app.json的内容，在uni-app中是在manifest中配置。

配置项列表

属性 类型 必填 描述 平台兼容
globalStyle Object 否 设置默认页面的窗口表现
pages Object Array 是 设置页面路径及窗口表现
easycom Object 否 组件自动引入规则 2.5.5+
tabBar Object 否 设置底部 tab 的表现
condition Object 否 启动模式配置
subPackages Object Array 否 分包加载配置
preloadRule Object 否 分包预下载规则 微信小程序
workers String 否 Worker 代码放置的目录 微信小程序
leftWindow Object 否 大屏左侧窗口 H5
topWindow Object 否 大屏顶部窗口 H5
rightWindow Object 否 大屏右侧窗口 H5
uniIdRouter Object 否 自动跳转相关配置，新增于HBuilderX 3.5.0
entryPagePath String 否 默认启动首页，新增于HBuilderX 3.7.0 微信小程序、支付宝小程序 

{
	"pages": [{
		"path": "pages/component/index",
		"style": {
			"navigationBarTitleText": "组件"
		}
	}, {
		"path": "pages/API/index",
		"style": {
			"navigationBarTitleText": "接口"
		}
	}, {
		"path": "pages/component/view/index",
		"style": {
			"navigationBarTitleText": "view"
		}
	}],
	"condition": { //模式配置，仅开发期间生效
		"current": 0, //当前激活的模式（list 的索引项）
		"list": [{
			"name": "test", //模式名称
			"path": "pages/component/view/index" //启动页面，必选
		}]
	},
	"globalStyle": {
		"navigationBarTextStyle": "black",
		"navigationBarTitleText": "演示",
		"navigationBarBackgroundColor": "#F8F8F8",
		"backgroundColor": "#F8F8F8",
		"usingComponents":{
			"collapse-tree-item":"/components/collapse-tree-item"
		},
		"renderingMode": "seperated", // 仅微信小程序，webrtc 无法正常时尝试强制关闭同层渲染
		"pageOrientation": "portrait", //横屏配置，全局屏幕旋转设置(仅 APP/微信/QQ小程序)，支持 auto / portrait / landscape
		"rpxCalcMaxDeviceWidth": 960,
		"rpxCalcBaseDeviceWidth": 375,
		"rpxCalcIncludeWidth": 750
	},
	"tabBar": {
		"color": "#7A7E83",
		"selectedColor": "#3cc51f",
		"borderStyle": "black",
		"backgroundColor": "#ffffff",
		"height": "50px",
		"fontSize": "10px",
		"iconWidth": "24px",
		"spacing": "3px",
    	"iconfontSrc":"static/iconfont.ttf", // app tabbar 字体.ttf文件路径 app 3.4.4+
		"list": [{
			"pagePath": "pages/component/index",
			"iconPath": "static/image/icon_component.png",
			"selectedIconPath": "static/image/icon_component_HL.png",
			"text": "组件",
      		"iconfont": { // 优先级高于 iconPath，该属性依赖 tabbar 根节点的 iconfontSrc
       			"text": "\ue102",
        		"selectedText": "\ue103",
        		"fontSize": "17px",
        		"color": "#000000",
        		"selectedColor": "#0000ff"
      		}
		}, {
			"pagePath": "pages/API/index",
			"iconPath": "static/image/icon_API.png",
			"selectedIconPath": "static/image/icon_API_HL.png",
			"text": "接口"
		}],
		"midButton": {
			"width": "80px",
			"height": "50px",
			"text": "文字",
			"iconPath": "static/image/midButton_iconPath.png",
			"iconWidth": "24px",
			"backgroundImage": "static/image/midButton_backgroundImage.png"
		}
	},
  "easycom": {
    "autoscan": true, //是否自动扫描组件
    "custom": {//自定义扫描规则
      "^uni-(.*)": "@/components/uni-$1.vue"
    }
  },
  "topWindow": {
    "path": "responsive/top-window.vue",
    "style": {
      "height": "44px"
    }
  },
  "leftWindow": {
    "path": "responsive/left-window.vue",
    "style": {
      "width": "300px"
    }
  },
  "rightWindow": {
    "path": "responsive/right-window.vue",
    "style": {
      "width": "300px"
    },
    "matchMedia": {
      "minWidth": 768
    }
  }
}

globalStyle

用于设置应用的状态栏、导航条、标题、窗口背景色等。

属性 类型 默认值 描述 平台差异说明
navigationBarBackgroundColor HexColor #F8F8F8 导航栏背景颜色（同状态栏背景色） APP与H5为#F8F8F8，小程序平台请参考相应小程序文档
navigationBarTextStyle String black 导航栏标题颜色及状态栏前景颜色，仅支持 black/white 支付宝小程序不支持，请使用 my.setNavigationBar
navigationBarTitleText String 导航栏标题文字内容
navigationStyle String default 导航栏样式，仅支持 default/custom。custom即取消默认的原生导航栏，需看使用注意 微信小程序 7.0+、百度小程序、H5、App（2.0.3+）
backgroundColor HexColor #ffffff 下拉显示出来的窗口的背景色 微信小程序
backgroundTextStyle String dark 下拉 loading 的样式，仅支持 dark / light 微信小程序
enablePullDownRefresh Boolean false 是否开启下拉刷新，详见页面生命周期。
onReachBottomDistance Number 50 页面上拉触底事件触发时距页面底部距离，单位只支持px，详见页面生命周期
backgroundColorTop HexColor #ffffff 顶部窗口的背景色（bounce回弹区域） 仅 iOS 平台
backgroundColorBottom HexColor #ffffff 底部窗口的背景色（bounce回弹区域） 仅 iOS 平台
titleImage String 导航栏图片地址（替换当前文字标题），支付宝小程序内必须使用https的图片链接地址 支付宝小程序、H5、APP
transparentTitle String none 导航栏整体（前景、背景）透明设置。支持 always 一直透明 / auto 滑动自适应 / none 不透明 支付宝小程序、H5、APP
titlePenetrate String NO 导航栏点击穿透 支付宝小程序、H5
pageOrientation String portrait 横屏配置，屏幕旋转设置，仅支持 auto / portrait / landscape 详见 响应显示区域变化 App 2.4.7+、微信小程序、QQ小程序
animationType String pop-in 窗口显示的动画效果，详见：窗口动画 App
animationDuration Number 300 窗口显示动画的持续时间，单位为 ms App
app-plus Object 设置编译到 App 平台的特定样式，配置项参考下方 app-plus App
h5 Object 设置编译到 H5 平台的特定样式，配置项参考下方 H5 H5
mp-alipay Object 设置编译到 mp-alipay 平台的特定样式，配置项参考下方 MP-ALIPAY 支付宝小程序
mp-weixin Object 设置编译到 mp-weixin 平台的特定样式，配置项参考下方 MP-WEIXIN 微信小程序
mp-baidu Object 设置编译到 mp-baidu 平台的特定样式，配置项参考下方 MP-BAIDU 百度小程序
mp-toutiao Object 设置编译到 mp-toutiao 平台的特定样式 抖音小程序
mp-lark Object 设置编译到 mp-lark 平台的特定样式 飞书小程序
mp-qq Object 设置编译到 mp-qq 平台的特定样式 QQ小程序
mp-kuaishou Object 设置编译到 mp-kuaishou 平台的特定样式 快手小程序
mp-jd Object 设置编译到 mp-jd 平台的特定样式 京东小程序
usingComponents Object 引用小程序组件，参考 小程序组件
renderingMode String 同层渲染，webrtc(实时音视频) 无法正常时尝试配置 seperated 强制关掉同层 微信小程序
leftWindow Boolean true 当存在 leftWindow 时，默认是否显示 leftWindow H5
topWindow Boolean true 当存在 topWindow 时，默认是否显示 topWindow H5
rightWindow Boolean true 当存在 rightWindow 时，默认是否显示 rightWindow H5
rpxCalcMaxDeviceWidth Number 960 rpx 计算所支持的最大设备宽度，单位 px App（vue2 且不含 nvue）、H5（2.8.12+）
rpxCalcBaseDeviceWidth Number 375 rpx 计算使用的基准设备宽度，设备实际宽度超出 rpx 计算所支持的最大设备宽度时将按基准宽度计算，单位 px App（vue2 且不含 nvue）、H5（2.8.12+）
rpxCalcIncludeWidth Number 750 rpx 计算特殊处理的值，始终按实际的设备宽度计算，单位 rpx App（vue2 且不含 nvue）、H5（2.8.12+）
dynamicRpx Boolean false 动态 rpx，屏幕大小变化会重新渲染 rpx App-nvue（vue3 固定值为 true） 3.2.13+
maxWidth Number 单位px，当浏览器可见区域宽度大于maxWidth时，两侧留白，当小于等于maxWidth时，页面铺满；不同页面支持配置不同的maxWidth；maxWidth = leftWindow(可选)+page(页面主体)+rightWindow(可选) H5（2.9.9+）

注意

每个组件，包括如下几个部分：以组件名称为标记的开始标签和结束标签、组件内容、组件属性、组件属性值。

注意：所有组件与属性名都是小写，单词之间以连字符-连接。


	content

复制代码

下面是一个基本组件的实例，在一个vue页面的根组件下插入一个