UniApp 入門學習

一、UniAPP 介紹

（1）什麼是 UniAPP ？

uni-app 是一個使用 Vue.js 開發所有前端應用的框架，開發者編寫一套代碼，可發佈到 iOS、Android、H5，以及各種小程序（微信/支付寶/百度/頭條/ QQ /釘釘）等多個平臺，方便開發者快速交付，不需要轉換開發思維，不需要更改開發習慣。

（2）爲什麼要選擇 UniAPP ？

開發者/案例數量更多

幾十萬應用、uni 統計月活12億、70+ 微信 / QQ羣

平臺能力不受限

在跨端的同時，通過條件編譯 + 平臺特有 API 調用，可以優雅的爲某平臺寫個性化代碼，調用專有能力而不影響其他平臺

性能體驗優秀

加載新頁面速度更快、自動 diff 更新數據，App 端支持原生渲染支撐更流暢的用戶體驗，小程序端的性能優於市場其他框架

周邊生態豐富

插件市場數千款插件，支持 NPM、支持小程序組件和SDK，微信生態的各種 sdk 可直接用於跨平臺 APP

學習成本低

基於通用的前端技術棧，採用 vue 語法+微信小程序 api，無額外學習成本

（3）UniAPP 功能框架

[圖片上傳失敗...(image-eeee4f-1659686671880)]

（4）UniAPP 開發環境搭建

下載開發工具 HBuilderX

HBuilderX 是通用的前端開發工具，但爲uni-app做了特別強化。

下載 App 開發版，可開箱即用；如下載標準版，在運行或發行uni-app時，會提示安裝uni-app插件，插件下載完成後方可使用

創建 uni-app 項目

選擇uni-app類型，輸入工程名，選擇模板，點擊創建，即可成功創建。

uni-app自帶的模板有 Hello uni-app ，是官方的組件和API示例。

還有一個重要模板是 uni ui項目模板，日常開發推薦使用該模板，已內置大量常用組件。

運行 uni-app

主要包括：瀏覽器運行、真機運行、小程序運行等

發佈 uni-app

主要包括：雲端原生 APP 、離線原生 APP、H5、各種小程序

二、UniAPP 初始化相關配置

（1）工程目錄結構

┌─components            uni-app組件目錄
│  └─comp-a.vue        可複用的a組件
├─hybrid                存放本地網頁的目錄（自建）
├─platforms             存放各平臺專用頁面的目錄（自建）
├─pages                 業務頁面文件存放的目錄
│  ├─index
│  │  └─index.vue      index頁面
│  └─list
│     └─list.vue        list頁面
├─static                存放應用引用靜態資源（如圖片、視頻等）的目錄，注意：靜態資源只能存放於此
├─wxcomponents          存放小程序組件的目錄（自建）
├─common                公共資源（自建）
├─api                   請求封裝（自建）
├─store                 狀態管理（自建）
├─main.js               Vue初始化入口文件
├─App.vue               應用配置，用來配置App全局樣式以及監聽 應用生命週期
├─manifest.json         配置應用名稱、appid、logo、版本等打包信息
└─pages.json            配置頁面路由、導航條、選項卡等頁面類信息

提示

static下目錄的 js 文件不會被 webpack 編譯，裏面如果有 es6 的代碼，不經過轉換直接運行，在手機設備上會報錯。

所以less、scss等資源同樣不要放在 static目錄下，建議這些公共的資源放在common目錄下

（2）應用配置 manifest.json

manifest.json 文件是應用的配置文件，用於指定應用的名稱、圖標、權限等，我們也可以在這裏爲 Vue 爲H5 設置跨域攔截處理器

（3）編譯配置 vue.config.js

vue.config.js 是一個可選的配置文件，如果項目的根目錄中存在這個文件，那麼它會被自動加載，一般用於配置 webpack 等編譯選項。官方文檔

（4）全局配置 page.json

pages.json 文件用來對 uni-app 進行全局配置，決定頁面文件的路徑、窗口樣式、原生的導航欄、底部的原生tabbar 等。它類似微信小程序中app.json的頁面管理部分。

官方文檔

屬性類型必填描述

globalStyle Object 否設置默認頁面的窗口表現

pages Object Array 是設置頁面路徑及窗口表現

easycom Object 否組件自動引入規則

tabBar Object 否設置底部 tab 的表現

condition Object 否啓動模式配置

subPackages Object Array 否分包加載配置

preloadRule Object 否分包預下載規則

屬性	類型	必填	描述
globalStyle	Object	否	設置默認頁面的窗口表現
pages	Object Array	是	設置頁面路徑及窗口表現
easycom	Object	否	組件自動引入規則
tabBar	Object	否	設置底部 tab 的表現
condition	Object	否	啓動模式配置
subPackages	Object Array	否	分包加載配置
preloadRule	Object	否	分包預下載規則

（5）全局樣式 uni.scss

uni.scss文件的用途是爲了方便整體控制應用的風格。比如按鈕顏色、邊框風格，uni.scss文件裏預置了一批scss變量預置。官方文檔

uni-app 官方擴展插件（uni ui）及插件市場上很多三方插件均使用了這些樣式變量，如果你是插件開發者，建議你使用 scss 預處理，並在插件代碼中直接使用這些變量（無需 import 這個文件），方便用戶通過搭積木的方式開發整體風格一致的App。

uni.scss是一個特殊文件，在代碼中無需 import 這個文件即可在scss代碼中使用這裏的樣式變量。uni-app的編譯器在webpack配置中特殊處理了這個 uni.scss，使得每個 scss 文件都被注入這個uni.scss，達到全局可用的效果。如果開發者想要less、stylus的全局使用，需要在vue.config.js中自行配置webpack策略。

（6）主組件 App.vue

App.vue是uni-app的主組件，所有頁面都是在App.vue下進行切換的，是頁面入口文件。但App.vue本身不是頁面，這裏不能編寫視圖元素。

這個文件的作用包括：調用應用生命週期函數、配置全局樣式、配置全局的存儲globalData

應用生命週期僅可在App.vue中監聽，在頁面監聽無效。

（7）入口文件 main.js

main.js是uni-app的入口文件，主要作用是初始化vue實例、定義全局組件、使用需要的插件如vuex。

官方文檔

（8）UniAPP 開發規範及資源路徑

開發規範約定

頁面文件嚮導 Vue單文件組件（SFC）規範

組件標籤靠近小程序規範，詳見 uni-app 組件規範

互連能力（JS API）靠近微信小程序規範，但需要將替換替換 wx 爲 uni ，詳見uni-app接口規範

數據綁定及事件處理同 Vue.js 規範，同時補充了 App 和頁面的生命週期

爲兼容多端運行，建議使用 flex 佈局進行開發

資源路徑說明

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，其餘不轉

js 文件或 script 標籤內，可以使用相對路徑和絕對路徑，形式如下：

// 絕對路徑，@指向項目根目錄，在cli項目中@指向src目錄
import add from '@/common/add.js'
// 相對路徑
import add from '../../common/add.js'

css 文件或 style 標籤內，可以使用相對路徑和絕對路徑，形式如下：

/* 絕對路徑 */
@import url('/common/uni.css');
@import url('@/common/uni.css');
/* 相對路徑 */
@import url('../../common/uni.css');

css 文件或 style 標籤內引用的圖片路徑，可以使用相對路徑也可以使用絕對路徑，形式如下：

/* 絕對路徑 */
background-image: url(/static/logo.png);
background-image: url(@/static/logo.png);
/* 相對路徑 */
background-image: url(../../static/logo.png);

三、UniAPP 生命週期

學習一個工具的目的核心是什麼？是爲了解決核心業務邏輯問題，業務邏輯很多時候簡單的解釋一句話：“在合適的時機幹合適的事情”，OK！什麼是合適的時機呢？簡單的說，頁面運行過程中，各個階段的回調函數就是頁面中的時機，我們也叫這個爲“生命週期鉤子函數”，當然，業務中我們也會寫到很多「回調」的邏輯，這些回調其實也是咱們自定義的時機，UniAPP 的生命週期鉤子函數回調函數有哪些呢？我們來理解一下！

uni-app 完整支持 Vue 實例的生命週期，同時還新增應用生命週期及頁面生命週期。

（1）應用生命週期

函數名	說明
onLaunch	當`uni-app` 初始化完成時觸發（全局只觸發一次）
onShow	當 `uni-app` 啓動，或從後臺進入前臺顯示
onHide	當 `uni-app` 從前臺進入後臺
onError	當 `uni-app` 報錯時觸發
onUniNViewMessage	對 `nvue` 頁面發送的數據進行監聽，可參考 nvue 向 vue 通訊
onUnhandledRejection	對未處理的 Promise 拒絕事件監聽函數（2.8.1+）
onPageNotFound	頁面不存在監聽函數
onThemeChange	監聽系統主題變化

（2）頁面生命週期

函數名	說明
onLoad	監聽頁面加載，其參數爲上個頁面傳遞的數據，參數類型爲Object（用於頁面傳參），參考示例
onShow	監聽頁面顯示。頁面每次出現在屏幕上都觸發，包括從下級頁面點返回露出當前頁面
onReady	監聽頁面初次渲染完成。注意如果渲染速度快，會在頁面進入動畫完成前觸發
onHide	監聽頁面隱藏
onUnload	監聽頁面卸載
onResize	監聽窗口尺寸變化
onPullDownRefresh	監聽用戶下拉動作，一般用於下拉刷新，參考示例
onReachBottom	頁面滾動到底部的事件（不是scroll-view滾到底），常用於下拉下一頁數據。具體見下方注意事項
onTabItemTap	點擊 tab 時觸發，參數爲Object，具體見下方注意事項
onShareAppMessage	用戶點擊右上角分享
onPageScroll	監聽頁面滾動，參數爲Object
onNavigationBarButtonTap	監聽原生標題欄按鈕點擊事件，參數爲Object
onBackPress	監聽頁面返回
onNavigationBarSearchInputChanged	監聽原生標題欄搜索輸入框輸入內容變化事件
onNavigationBarSearchInputConfirmed	監聽原生標題欄搜索輸入框搜索事件，用戶點擊軟鍵盤上的“搜索”按鈕時觸發。
onNavigationBarSearchInputClicked	監聽原生標題欄搜索輸入框點擊事件
onShareTimeline	監聽用戶點擊右上角轉發到朋友圈
onAddToFavorites	監聽用戶點擊右上角收藏

四、UniAPP 路由配置及頁面跳轉

（1）路由配置

uni-app 頁面路由全部交給框架統一管理，開發者需要在pages.json裏配置每個路由頁面的路徑及頁面樣式（類似小程序在 app.json 中配置頁面路由）。

"pages": [
        {
            "path": "pages/index",
            "style": {
                "navigationBarTitleText": "路由配置",
                "navigationBarBackgroundColor": "#FFFFFF",
                "navigationBarTextStyle": "black",
                "backgroundColor": "#FFFFFF",
                "enablePullDownRefresh": true
            }
        },
        {
            "path": "pages/user",
            "style": {
                "navigationBarTitleText": "路由配置",
                "navigationBarBackgroundColor": "#FFFFFF",
                "navigationBarTextStyle": "black",
                "backgroundColor": "#FFFFFF",
                "enablePullDownRefresh": true
            }
        }
]

（2）路由跳轉

uni-app 有兩種頁面路由跳轉方式：使用navigator組件跳轉（標籤式導航）、調用API跳轉（編程式導航）

框架以棧的形式管理當前所有頁面，當發生路由切換的時候，頁面棧的表現如下：

路由方式	頁面棧表現	觸發時機
初始化	新頁面入棧	uni-app 打開的第一個頁面
打開新頁面	新頁面入棧	調用 API `uni.navigateTo`、<br />使用組件 `<navigator open-type="navigate" />`
頁面重定向	當前頁面出棧，新頁面入棧	調用 API uni.redirectTo 、<br />使用組件
頁面返回	頁面不斷出棧，直到目標返回頁	調用 API uni.navigateBack 、<br />使用組件、<br />用戶按左上角返回按鈕、安卓用戶點擊物理back按鍵
Tab 切換	頁面全部出棧，只留下新的 Tab 頁面	調用 API uni.switchTab 、<br />使用組件、<br />用戶切換 Tab
重加載	頁面全部出棧，只留下新的頁面	�調用 API uni.reLaunch 、<br />使用組件

（3）獲取當前頁面棧

getCurrentPages() 函數用於獲取當前頁面棧的實例，以數組形式按棧的順序給出，第一個元素爲首頁，最後一個元素爲當前頁面。

注意： getCurrentPages() 僅用於展示頁面棧的情況，請勿修改頁面棧，以免造成頁面狀態錯誤。

（4）路由傳參與接收

說明：頁面生命週期的 onLoad(）監聽頁面加載，其參數爲上個頁面傳遞的數據，如：

//頁面跳轉並傳遞參數
uni.navigateTo({
    url: 'page2?name=liy&message=Hello'
});

url爲將要跳轉的頁面路徑，路徑後可以帶參數。參數與路徑之間使用?分隔，參數鍵與參數值用=相連，不同參數用&分隔。如 'path?key1=value2&key2=value2'，path爲下一個頁面的路徑，下一個頁面的onLoad函數可得到傳遞的參數。

// 頁面 2 接收參數
onLoad: function (option) { //option爲object類型，會序列化上個頁面傳遞的參數
    console.log(option.name); //打印出上個頁面傳遞的參數。
    console.log(option.message); //打印出上個頁面傳遞的參數。
}

注意：url 有長度限制，太長的字符串會傳遞失敗，並且不規範的字符格式也可能導致傳遞失敗，所以對於複雜參數建議使用 encodeURI、decodeURI 進行處理後傳遞

（5）小程序路由分包配置

因小程序有體積和資源加載限制，各家小程序平臺提供了分包方式，優化小程序的下載和啓動速度。

所謂的主包，即放置默認啓動頁面及 TabBar 頁面，而分包則是根據 pages.json 的配置進行劃分。

在小程序啓動時，默認會下載主包並啓動主包內頁面，當用戶進入分包內某個頁面時，會把對應分包自動下載下來，下載完成後再進行展示，此時終端界面會有等待提示。

"subPackages": [
    {
            "root": "news",
            "pages": [{
                    "path": "index",
                    "style": {
                        "navigationBarTitleText": "新聞中心",
                        "navigationBarBackgroundColor": "#FFFFFF",
                        "navigationBarTextStyle": "black",
                        "backgroundColor": "#FFFFFF"
                    }
                }
            ]
        }
    ... 
]，
// 預下載分包設置
"preloadRule": {
        "pages/index": {
            "network": "all",
            "packages": ["activities"]
        }
}

五、UniAPP 常用組件簡介

uni-app 爲開發者提供了一系列基礎組件，類似 HTML 裏的基礎標籤元素，但 uni-app 的組件與 HTML 不同，而是與小程序相同，更適合手機端使用。

雖然不推薦使用 HTML 標籤，但實際上如果開發者寫了div等標籤，在編譯到非H5平臺時也會被編譯器轉換爲 view 標籤，類似的還有 span 轉 text、a 轉navigator等，包括 css 裏的元素選擇器也會轉，但爲了管理方便、策略統一，新寫代碼時仍然建議使用view等組件。

開發者可以通過組合這些基礎組件進行快速開發，基於內置的基礎組件，可以開發各種擴展組件，組件規範與vue組件相同。

案例：知心姐姐佈局實現

六、UniAPP 常用 API 簡介

uni-app的 js 代碼，h5 端運行於瀏覽器中，非 h5 端 Android 平臺運行在 v8 引擎中，iOS 平臺運行在 iOS 自帶的 jscore 引擎中。所以，uni-app的 jsAPI 由標準 ECMAScript 的 js API 和 uni 擴展 API 這兩部分組成。

ECMAScript 由 Ecma 國際管理，是基礎 js 語法。瀏覽器基於標準 js 擴充了window、document 等 js API；Node.js 基於標準 js 擴充了 fs 等模塊；小程序也基於標準 js 擴展了各種 wx.xx、my.xx、swan.xx 的 API。

標準 ecmascript 的 API 非常多，比如：console、settimeout等等。

非 H5 端，雖然不支持 window、document、navigator 等瀏覽器的 js API，但也支持標準 ECMAScript。

開發者不要把瀏覽器裏的 js 等價於標準 js。

所以 uni-app 的非 H5 端，一樣支持標準 js，支持 if、for 等語法，支持字符串、數組、時間等變量及各種處理方法，僅僅是不支持瀏覽器專用對象。

案例：知心姐姐聊天功能

七、UniAPP 自定義組件與通信

（1）自定義組件概念

組件是 vue 技術中非常重要的部分，組件使得與ui相關的輪子可以方便的製造和共享，進而使得vue使用者的開發效率大幅提升，在項目的component目錄下存放組件，uni-app 只支持 vue 單文件組件（.vue 組件）

組件可以使用「全局註冊」和「頁面引入」兩種方式進行使用，使用分爲三步：

導入 import xxx from 'xxx'

註冊 Vue.use('xx',xx) components:{ xxx }

使用 <xx />

（2）父子組件通信

父組件通過自定義屬性向子組件傳遞數據

子組件通過 props 接收父組件傳遞的數據

父組件通過自定義事件標籤向子組件傳遞事件

子組件通過觸發父組件定義事件方式修改父組件數據

（3）slot 數據分發與作用域插槽

父組件通過調用子組件內部嵌套 html 內容作爲slot分發給子組件

子組件通過在 slot 標籤上添加屬性，向父組件通信數據，作用域插槽

（4）全局事件定義及通信

在整個應用的任何地方均可以使用uni.$on創建一個全局事件

在整個應用的任何地方也均可以使用 uni.$emit 來觸發全局事件，實現多組件見的數據通信

八、UniAPP Vuex 狀態管理

概念

Vuex 是一個專爲 Vue.js 應用程序開發的狀態管理模式。它採用集中式存儲管理應用的所有組件的狀態，並以相應的規則保證狀態以一種可預測的方式發生變化。

應用場景

Vue多個組件之間需要共享數據或狀態。

關鍵規則

State：存儲狀態數據

Getter：從狀態數據派生數據，相當於 State 的計算屬性

Mutation：存儲用於同步更改狀態數據的方法，默認傳入的參數爲 state

Action：存儲用於異步更改狀態數據，但不是直接更改，而是通過觸發 Mutation 方法實現，默認參數爲context

Module：Vuex 模塊化

交互關係

[圖片上傳失敗...(image-b3239f-1659686671882)]

使用方式

import {
      mapState,
      mapActions
} from 'vuex'
export default {
      computed: {
          ...mapState(['loginState', 'userInfo'])
      },
      methods: {
          ...mapActions(['userLoginAction', 'userLogoutAction']),
      }
}

體驗案例：模擬用戶登陸邏輯實現

注意：配合使用 Storage 來實現刷新頁面後狀態持續保持的業務需求

九、運行環境判斷與跨端兼容

（1）開發環境和生產環境

uni-app 可通過 process.env.NODE_ENV 判斷當前環境是開發環境還是生產環境，一般用於連接測試服務器或生產服務器的動態切換。

在HBuilderX 中，點擊「運行」編譯出來的代碼是開發環境，點擊「發行」編譯出來的代碼是生產環境

if(process.env.NODE_ENV === 'development'){
    console.log('開發環境')
}else{
    console.log('生產環境')
}

（2）判斷平臺

平臺判斷有2種場景，一種是在編譯期判斷，一種是在運行期判斷。

編譯期判斷編譯期判斷，即條件編譯，不同平臺在編譯出包後已經是不同的代碼，
// #ifdef H5
 alert("只有h5平臺纔有alert方法")
// #endif
// 如上代碼只會編譯到H5的發行包裏，其他平臺的包不會包含如上代碼。

運行期判斷運行期判斷是指代碼已經打入包中，仍然需要在運行期判斷平臺，此時可使用 uni.getSystemInfoSync().platform 判斷客戶端環境是 Android、iOS 還是小程序開發工具
switch(uni.getSystemInfoSync().platform){
   case 'android':
      console.log('運行Android上')
      break;
   case 'iOS':
      console.log('運行iOS上')
      break;
   default:
      console.log('運行在開發者工具上')
      break;
}

（3）跨端兼容

uni-app 已將常用的組件、JS API 封裝到框架中，開發者按照 uni-app 規範開發即可保證多平臺兼容，大部分業務均可直接滿足，但每個平臺有自己的一些特性，因此會存在一些無法跨平臺的情況。

大量寫 if else，會造成代碼執行性能低下和管理混亂。

編譯到不同的工程後二次修改，會讓後續升級變的很麻煩。

在 C 語言中，通過 #ifdef、#ifndef 的方式，爲 windows、mac 等不同 os 編譯不同的代碼。 uni-app 參考這個思路，爲 uni-app 提供了條件編譯手段，在一個工程裏優雅的完成了平臺個性化實現。

條件編譯是用特殊的註釋作爲標記，在編譯時根據這些特殊的註釋，將註釋裏面的代碼編譯到不同平臺。

寫法：以 #ifdef 或 #ifndef 加 %PLATFORM% 開頭，以 #endif 結尾。

\#ifdef：if defined 僅在某平臺存在

\#ifndef：if not defined 除了某平臺均存在

%PLATFORM%：平臺名稱

%PLATFORM% 可取值如下：

值	平臺
APP-PLUS	App
APP-PLUS-NVUE	App nvue
H5	H5
MP-WEIXIN	微信小程序
MP-ALIPAY	支付寶小程序
MP-BAIDU	百度小程序
MP-TOUTIAO	字節跳動小程序
MP-QQ	QQ小程序
MP-360	360小程序
MP	微信小程序/支付寶小程序/百度小程序/字節跳動小程序/QQ小程序/360小程序
QUICKAPP-WEBVIEW	快應用通用(包含聯盟、華爲)
QUICKAPP-WEBVIEW-UNION	快應用聯盟
QUICKAPP-WEBVIEW-HUAWEI	快應用華爲