uniapp框架教程

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。

#编译器

• 编译器运行在电脑开发环境。一般是内置在HBuilderX工具中，也可以使用独立的cli版。
• 开发者按uni-app规范编写代码，由编译器将开发者的代码编译生成每个平台支持的特有代码
  • 在web平台，将.vue文件编译为js代码。与普通的vue cli项目类似
  • 在微信小程序平台，编译器将.vue文件拆分生成wxml、wxss、js等代码
  • 在app平台，将.vue文件编译为js代码。进一步，如果涉及uts代码：
    • 在Android平台，将.uts文件编译为kotlin代码
    • 在iOS平台，将.uts文件编译为swift代码
• 编译器分vue2版和vue3版
  • vue2版：基于webpack实现
  • vue3版：基于Vite实现，性能更快
• 编译器支持条件编译，即可以指定某部分代码只编译到特定的终端平台。从而将公用和个性化融合在一个工程中。

// #ifdef  App
console.log("这段代码只有在App平台才会被编译进去。非App平台编译后没有这段代码")
// #endif

复制代码

更多编译器介绍参见：编译器

#运行时（runtime）

runtime不是运行在电脑开发环境，而是运行在真正的终端上。

uni-app在每个平台（Web、Android App、iOS App、各家小程序）都有各自的runtime。这是一个比较庞大的工程。

• 在小程序端，uni-app的runtime，主要是一个小程序版的vue runtime，页面路由、组件、api等方面基本都是转义。
• 在web端，uni-app的runtime相比普通的vue项目，多了一套ui库、页面路由框架、和uni对象（即常见API封装）
• 在App端，uni-app的runtime更复杂，可以先简单理解为DCloud也有一套小程序引擎，打包app时将开发者的代码和DCloud的小程序打包成了apk或ipa。当然，事实上DCloud确实有小程序引擎产品，供原生应用实现小程序化，详见

uni-app runtime包括3部分：基础框架、组件、API。

1. 基础框架：
   • 包括语法、数据驱动、全局文件、应用管理、页面管理、js引擎、渲染和排版引擎等
   • 在web和小程序上，不需要uni-app提供js引擎和排版引擎，直接使用浏览器和小程序的即可。但app上需要uni-app提供
   • App的js引擎：App-Android上，uni-app的js引擎是v8，App-iOS是jscore
   • App的渲染引擎：同时提供了2套渲染引擎，.vue页面文件由webview渲染，原理与小程序相同；.nvue页面文件由原生渲染，原理与react native相同。开发者可以根据需要自主选择渲染引擎。
2. 组件：
   • runtime中包括的组件只有基础组件，如<view>、<button>等。扩展组件不包含在uni-app的runtime中，而是下载到用户的项目代码中。（这些组件都是vue组件）
   • 为了降低开发者的学习成本，uni-app的内置基础组件命名规范与小程序基本相同。
   • 这几十个组件不管在哪个平台，已被处理为均有一致表现。
   • 在小程序端，uni-app基础组件会直接转义为小程序自己的内置组件。在小程序的runtime中不占体积。
   • 在web和android、iOS端，这几十个组件都在uni-app的runtime中，会占用一定体积，相当于内置了一套ui库。
   • 组件的扩展：
     • 有了几十个基础组件，大多数扩展组件也都是基于这些基础组件封装的。比如官方提供的扩展ui库uni ui。
     • 在web平台，for web的各种ui库（如elementUI）也可以使用，但这些库由于操作了dom，无法跨端在app和小程序中使用。
     • 在App平台，uni-app也支持使用原生编程语言来自行扩展原生组件，比如原生的地图、ar等。
     • uni-app同时支持将微信自定义组件运行到微信小程序、web、app这3个平台。注意微信自定义组件不是vue组件。
3. API：
   • uni-app runtime内置了大量常见的、跨端的 API，比如联网(uni.request)、读取存储(uni.getStorage)
   • 同时uni-app不限制各端原生平台的API调用。开发者可以在uni-app框架中无限制的调用该平台所有能使用的API。即，在小程序平台，小程序的所有API都可以使用；在web平台，浏览器的所有API都可使用；在iOS和Android平台，os的所有API都可以使用。
   • 也就是说，使用uni-app的标准API，可以跨端使用。但对于不跨端的部分，仍可以调用该端的专有API。由于常见的API都已经被封装内置，所以日常开发时，开发者只需关注uni标准API，当需要调用特色端能力时在条件编译里编写特色API调用代码。
   • ext API：web和app的runtime体积不小，如果把小程序的所有API等内置进去会让开发者的最终应用体积变大。所以有部分不常用的API被剥离为ext API。虽然仍然是uni.开头，但需要单独下载插件到项目下
   • 小程序平台：uni对象会转为小程序的自有对象，比如在微信小程序平台，编写uni.request等同于wx.request。那么所有wx.的API都可以这样使用。
   • web平台：window、dom等浏览器专用API仍可以使用
   • app平台：除了uni.的API，还可以使用plus.的API、Native.js，以及通过uts编写原生插件，或者使用java和objectC编写原生插件。这些原生插件调用os的API并封装给js使用。
   • 由于历史沿革，DCloud在开发app时有：5+App、wap2app、uni-app等3种模式。这3种方式的runtime在底层能力上是公用的，所有uni-app可以调用5+（也就是plus.xxx）的API。虽然都可以使用5+的系统能力，但uni-app的逻辑层运行在js层，渲染层是webview和原生nvue双选。而5+不区分逻辑层和渲染层，全部运行在webview里，在性能上5+不及uni-app。

DCloud还提供了插件市场，大多数用得着的组件和API都已经有现成的插件。

#逻辑层和渲染层分离

在web平台，逻辑层（js）和渲染层（html、css），都运行在统一的webview里。

但在小程序和app端，逻辑层和渲染层被分离了。

分离的核心原因是性能。过去很多开发者吐槽基于webview的app性能不佳，很大原因是js运算和界面渲染抢资源导致的卡顿。

不管小程序还是app，逻辑层都独立为了单独的js引擎，渲染层仍然是webview（app上也支持纯原生渲染）。

所以注意小程序和app的逻辑层都不支持浏览器专用的window、dom等API。app只能在渲染层操作window、dom，即renderjs。

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.json ：

{
	"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