开发规范
基础组件
uni-app 为开发者提供了一系列基础组件，类似 HTML 里的基础标签元素。但 uni-app 的组件与 HTML 不同，而是与小程序相同，更适合手机端使用。
虽然不推荐使用 HTML 标签，但实际上如果开发者写了 div 等标签，在编译到非 H5 平台时也会被编译器转换为 view 标签，类似的还有 span 转 text、a 转 navigator 等，包括 css 里的元素选择器也会转。但为了管理方便、策略统一，新写代码时仍然建议使用 view 等组件。
Tips
- 所有组件与属性名都是小写，单词之间以连字符
-连接。 - 根节点为
<template>,这个<template>下只能且必须有一个根<view>组件。这是vue单文件组件规范。 - 平台差异说明若无特殊说明，则表示所有平台均支持。
属性类型
| 类型 | 描述 | 注解 |
|---|---|---|
| Boolean | 布尔值 | 组件写上该属性，不管该属性等于什么，其值都为 true，只有组件上没有写该属性时，属性值才为 false。如果属性值为变量，变量的值会被转换为 Boolean 类型。 |
| Number | 数字 | 1, 2.5 |
| String | 字符串 | "string" |
| Array | 数组 | [ 1, "string" ] |
| Object | 对象 | { key: value } |
| EventHandler | 事件处理函数名 | handlerName 是 methods 中定义的事件处理函数名 |
| Any | 任意属性 |
组件列表
基础组件分为以下八大类：
视图容器（View Container）：
| 组件名 | 说明 |
|---|---|
| view | 视图容器，类似于HTML中的div |
| scroll-view | 可滚动视图容器 |
| swiper | 滑块视图容器 |
基础内容（Basic Content）：
| 组件名 | 说明 |
|---|---|
| icon | 图标 |
| text | 文字 |
| rich-text | 富文本 |
| progress | 进度条 |
表单组件（Form）：
| 标签名 | 说明 |
|---|---|
| button | 按钮 |
| form | 表单 |
| input | 输入框 |
| checkbox | 多项选择器 |
| radio | 单项选择器 |
| picker | 弹出式列表选择器 |
| picker-view | 窗体内嵌式列表选择器 |
| slider | 滑动选择器 |
| switch | 开关选择器 |
| label | 标签 |
导航（Navigation）：
| 组件名 | 说明 |
|---|---|
| navigator | 页面链接。类似于HTML中的a标签 |
媒体组件（Media）：
| 组件名 | 说明 |
|---|---|
| audio | 音频 |
| camera | 相机 |
| image | 图片 |
| video | 视频 |
| live-player | 直播播放 |
| live-pusher | 实时音视频录制，也称直播推流 |
地图（Map）：
| 组件名 | 说明 |
|---|---|
| map | 地图 |
画布（Canvas）：
| 组件名 | 说明 |
|---|---|
| canvas | 画布 |
webview（Web-view）：
| 组件名 | 说明 |
|---|---|
| web-view | web浏览器组件 |
目录结构
一个uni-app工程，默认包含如下目录及文件：
┌─components uni-app组件目录
│ └─comp-a.vue 可复用的a组件
├─hybrid 存放本地网页的目录，详见
├─platforms 存放各平台专用页面的目录，详见
├─pages 业务页面文件存放的目录
│ ├─index
│ │ └─index.vue index页面
│ └─list
│ └─list.vue list页面
├─static 存放应用引用静态资源（如图片、视频等）的目录，注意：静态资源只能存放于此
├─wxcomponents 存放小程序组件的目录，详见
├─main.js Vue初始化入口文件
├─App.vue 应用配置，用来配置App全局样式以及监听 应用生命周期
├─manifest.json 配置应用名称、appid、logo、版本等打包信息，详见
└─pages.json 配置页面路由、导航条、选项卡等页面类信息，详见
资源路径说明
模板内引入静态资源
template内引入静态资源，如image、video等标签的src属性时，可以使用相对路径或者绝对路径，形式如下
<!-- 绝对路径，/static指根目录下的static目录，在cli项目中/static指src目录下的static目录 -->
<image class="logo" src="/static/logo.png"></image>
<image class="logo" src="@/static/logo.png"></image>
<!-- 相对路径 -->
<image class="logo" src="../../static/logo.png"></image>
注意
@开头的绝对路径以及相对路径会经过base64转换规则校验- 引入的静态资源在非h5平台，均不转为base64。
- H5平台，小于4kb的资源会被转换成base64，其余不转。
- 自
HBuilderX 2.6.6-alpha起template内支持@开头路径引入静态资源，旧版本不支持此方式 - App平台自
HBuilderX 2.6.9-alpha起template节点中引用静态资源文件时（如：图片），调整查找策略为【基于当前文件的路径搜索】，与其他平台保持一致 - 支付宝小程序组件内 image 标签不可使用相对路径
js文件引入
js文件或script标签内（包括renderjs等）引入js文件时，可以使用相对路径和绝对路径，形式如下
// 绝对路径，@指向项目根目录，在cli项目中@指向src目录
import add from '@/common/add.js'
// 相对路径
import add from '../../common/add.js'
注意
- js文件不支持使用
/开头的方式引入
css引入静态资源
css文件或style标签内引入css文件时（scss、less文件同理），只能使用相对路径
/* 绝对路径 */
@import url('/common/uni.css');
@import url('@/common/uni.css');
/* 相对路径 */
@import url('../../common/uni.css');
注意
- 自
HBuilderX 2.6.6-alpha起支持绝对路径引入静态资源，旧版本不支持此方式
css文件或style标签内引用的图片路径可以使用相对路径也可以使用绝对路径，需要注意的是，有些小程序端css文件不允许引用本地文件（请看注意事项）。
/* 绝对路径 */
background-image: url(/static/logo.png);
background-image: url(@/static/logo.png);
/* 相对路径 */
background-image: url(../../static/logo.png);
Tips
- 引入字体图标请参考，字体图标
@开头的绝对路径以及相对路径会经过base64转换规则校验- 不支持本地图片的平台，小于40kb，一定会转base64。（共四个平台mp-weixin, mp-qq, mp-toutiao, app v2）
- h5平台，小于4kb会转base64，超出4kb时不转。
- 其余平台不会转base64
页面样式与布局
尺寸单位
Tips
- 注意 rpx 是和宽度相关的单位，屏幕越宽，该值实际像素越大。如不想根据屏幕宽度缩放，则应该使用 px 单位。
- 如果开发者在字体或高度中也使用了 rpx ，那么需注意这样的写法意味着随着屏幕变宽，字体会变大、高度会变大。如果你需要固定高度，则应该使用 px 。
- 设计师可以用 iPhone6 作为视觉稿的标准。
- 如果设计稿不是750px，HBuilderX提供了自动换算的工具，详见：https://ask.dcloud.net.cn/article/35445。
- 早期 uni-app 提供了 upx ，目前已经推荐统一改为 rpx 了，详见
选择器
- 在
uni-app中不能使用*选择器。 page相当于body节点，例如：
<!-- 设置页面背景颜色 -->
page {
background-color:#ccc;
}
CSS变量
uni-app 提供内置 CSS 变量
| CSS变量 | 描述 | App | 小程序 | H5 |
|---|---|---|---|---|
| --status-bar-height | 系统状态栏高度 | 系统状态栏高度、nvue注意见下 | 25px | 0 |
| --window-top | 内容区域距离顶部的距离 | 0 | 0 | NavigationBar 的高度 |
| --window-bottom | 内容区域距离底部的距离 | 0 | 0 | TabBar 的高度 |
.status_bar {
height: var(--status-bar-height);
100%;
}
注意：
var(--status-bar-height)此变量在微信小程序环境为固定25px，在 App 里为手机实际状态栏高度。- 当设置
"navigationStyle":"custom"取消原生导航栏后，由于窗体为沉浸式，占据了状态栏位置。此时可以使用一个高度为var(--status-bar-height)的 view 放在页面顶部，避免页面内容出现在状态栏。 - 由于在H5端，不存在原生导航栏和tabbar，也是前端div模拟。如果设置了一个固定位置的居底view，在小程序和App端是在tabbar上方，但在H5端会与tabbar重叠。此时可使用
--window-bottom，不管在哪个端，都是固定在tabbar上方。 - 目前 nvue 在App端，还不支持
--status-bar-height变量，替代方案是在页面onLoad时通过uni.getSystemInfoSync().statusBarHeight获取状态栏高度，然后通过style绑定方式给占位view设定高度。下方提供了示例代码
背景图片
uni-app 支持使用在 css 里设置背景图片，使用方式与普通 web 项目大体相同，但需要注意以下几点：
-
支持 base64 格式图片。
-
支持网络路径图片。
-
小程序不支持在css中使用本地文件，包括本地的背景图和字体文件。需以base64方式方可使用。App端在v3模式以前，也有相同限制。v3编译模式起支持直接使用本地背景图和字体。
-
使用本地路径背景图片需注意：
-
为方便开发者，在背景图片小于 40kb 时，
uni-app编译到不支持本地背景图的平台时，会自动将其转化为 base64 格式； -
图片大于等于 40kb，会有性能问题，不建议使用太大的背景图，如开发者必须使用，则需自己将其转换为 base64 格式使用，或将其挪到服务器上，从网络地址引用。
-
本地背景图片的引用路径推荐使用以 ~@ 开头的绝对路径。
.test2 { background-image: url('~@/static/logo.png'); }
-
注意
微信小程序不支持相对路径（真机不支持，开发工具支持）
<template/>和<block/>
uni-app 支持在 template 模板中嵌套 和，用来进行 列表渲染 和 条件渲染。
和 并不是一个组件，它们仅仅是一个包装元素，不会在页面中做任何渲染，只接受控制属性。
<template/>官方用于条件判断<block/>官方用于做循环
Class 与 Style 绑定
为节约性能，我们将 Class 与 Style 的表达式通过 compiler 硬编码到 uni-app 中，支持语法和转换效果如下：
class 支持的语法:
<view :class="{ active: isActive }">111</view>
<view class="static" v-bind:class="{ active: isActive, 'text-danger': hasError }">222</view>
<view class="static" :class="[activeClass, errorClass]">333</view>
<view class="static" v-bind:class="[isActive ? activeClass : '', errorClass]">444</view>
<view class="static" v-bind:class="[{ active: isActive }, errorClass]">555</view>
style 支持的语法:
<view v-bind:style="{ color: activeColor, fontSize: fontSize + 'px' }">666</view>
<view v-bind:style="[{ color: activeColor, fontSize: fontSize + 'px' }]">777</view>
全局组件
uni-app 支持配置全局组件，需在 main.js 里进行全局注册，注册后就可在所有页面里使用该组件。
注意
Vue.component的第一个参数必须是静态的字符串。- nvue页面暂不支持全局组件
示例
main.js 里进行全局导入和注册
import Vue from 'vue'
import pageHead from './components/page-head.vue'
Vue.component('page-head',pageHead)