開發規范
基礎組件
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);
width: 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)