uni-app入門學習

1. 什么是 uni-app

   1 uni-app 是一個使用 Vue.js 開發跨平台應用的前端框架，開發者編寫一套代碼，可編譯到iOS、Android、H5、小程序等多個平台。 官方的體驗例子：

   

   2 uni-app在跨端數量、擴展能力、性能體驗、周邊生態、學習成本、開發成本等6大關鍵指標上擁有極強的競爭優勢 。

• 跨端數量更多
• 平台能力不受限
• 性能體驗更優秀
• 周邊生態豐富
• 學習成本低
• 開發成本低

3 功能框架

1. 使用 uni-app 的前置條件

   2.1 規范

       為了更好的跨端開發，我們最好還是制定下開發規范，以免過量的解決各端兼容問題

           * 頁面組件我們要遵循Vue 單文件組件 (SFC) 規范

           * 組件標簽靠近微信小程序規范

           * 接口能力（JS API）靠近微信小程序規范

           * 數據綁定及事件處理靠近 Vue.js 規范，同時補充了App及頁面的生命周期

           * 為兼容多端運行，建議使用flex布局進行開發

               ...

    

   2.2 開發工具

           

   推薦使用官方提供的HBulderX編輯器（畢竟是人家的框架，用人家的東西集成提示等高些）

           下載地址：https://www.dcloud.io/hbuilderx.html

   

    

   如果不習慣可以在頂部選項欄更改下習慣的：

   

    

   2.3 使用Vue.js

   2.3.1 相關資料

   相比Web平台， Vue.js 在 uni-app 中使用差異主要集中在兩個方面：

• 新增：uni-app除了支持Vue實例的生命周期，還支持應用啟動、頁面顯示等生命周期
• 受限：相比web平台，部分功能受限，比如 v-html 指令，具體見下。（受限部分僅在App和小程序端受限，H5版不受限）

 

詳細查看官方文檔： https://uniapp.dcloud.io/use

 

 

    2.3.2 實踐建議(還有很多待踩)

* 盡量別用html的標簽，用uni-app提供的組件（感覺和微信小程序好像）

 

* 盡量使用組件提供的屬性和方法

 

* ref就h5支持，所以盡量用id代替

 

* 用v-if別用v-show 在非h5端不支持

 

* 非h5端不支持組件按需加載（如下）

 

* 推薦組件之間通訊借助vuex，不然在非h5端的話，會出現props數據改變，但子組件的沒對應改變

 

* 用vuex時 除了h5端 別的端得設置Vue.prototype.$store = store;（注意框架內置了vuex,不用你額外下載npm）

 

 

更多坑: https://segmentfault.com/a/1190000016156607

 

2.4 小程序

目前國內的小程序類型有： 微信，支付寶，百度，頭條

 

當然如果要開發小程序，不可避免的，我們肯定是要知道不同平台下的小程序規范的 。當然知道了這些規范之后，我們開發起來就比較簡單了。 uni-app 給我們把不同平台的小程序 API 幾乎都封裝了 ，只需要將前綴替換為 uni 即可 舉例說明：

 

我們調用微信小程序的 request 請求

wx.request({

url: 'https://www.example.com/request', //僅為示例，並非真實接口地址

data: {

text: 'uni.request'

},

header: {

'custom-header': 'hello' //自定義請求頭信息

},

success: (res) => {

console.log(res.data);

this.text = 'request success';

}

});

 

我們使用 uni-app 的 request 請求

uni.request({

url: 'https://www.example.com/request', //僅為示例，並非真實接口地址

data: {

text: 'uni.request'

},

header: {

'custom-header': 'hello' //自定義請求頭信息

},

success: (res) => {

console.log(res.data);

this.text = 'request success';

}

});

有沒有發現什么不一樣的？對了，除了前綴 wx替換為uni之外，其他的地方一摸一樣，是不是這樣開發起來就很一賊了呢 。

 

 

 

2.5 App

uni-app感覺就是個大雜燴。不僅可以使用絕大多數的小程序相關的 API，同時也可以使用 5+API 很好的補足了小程序上一些還沒有實現的功能，是不是很美好。

 

2.5.1 weex/nvue

uni-app App端內置 weex 引擎，提供了原生渲染能力。

 

uni-app 里可以使用所有 weex 的內置組件和內置模塊，編寫頁面時頁面后綴名為 .nvue(native vue)，.nvue 只會編譯到 App端，不支持在 Chrome 或小程序開發工具中預覽，也不支持手機模擬器預覽，需使用真機測試運行。

 

nvue 相當於在 weex 引擎上實現了 uni-app api的解析，並通過引入 HTML5Plus 的眾多 API 來彌補 weex 在 js api 上的不足。

 

nvue 的開發遵循 weex 開發規范，並有所擴展。本頁面僅介紹 weex 在 uni-app 里的擴展使用方式及開發注意事項 ，詳細的頁面開發及功能實現請參考 weex 官方文檔 。

 

詳情參考官方介紹： https://uniapp.dcloud.io/use-weex

2.5.2 HTML5+API

uni-app App 端內置 HTML5+ 引擎，讓 js 可以直接調用豐富的原生能力。

詳情參考官方介紹： https://uniapp.dcloud.io/use-html5plus

 

 

1. 快速上手

   3.1 hello word!

   uni-app支持通過 HBuilderX可視化界面、vue-cli命令行兩種方式快速創建項目。(推薦使用HBuilderX)

    

   3.1.1 創建hello word項目

   下載安裝HBuilderX。打開HBuilderX

   點擊工具欄里的文件 -> 新建 -> 項目：

   

   選擇uni-app，輸入工程名，如：hello-uniapp，點擊創建，即可成功創建 uni-app。

   

    

   剩下的自己發揮！

    

   3.1.2 運行項目

   1，瀏覽器運行：進入hello-uniapp項目，點擊工具欄的運行 -> 運行到瀏覽器 -> 選擇瀏覽器，即可在瀏覽器里面體驗uni-app 的 H5 版。

   

    

2. 真機運行：連接手機， 在手機的設置開發者選項里開啟USB調試，進入hello-uniapp項目，點擊工具欄的運行 -> 真機運行 -> 選擇運行的設備，即可在該設備里面體驗uni-app。

   

   如果手機無法識別，請點擊菜單運行-運行到手機或模擬器-真機運行常見故障排查指南。

    

3. 在微信開發者工具里運行：進入hello-uniapp項目，點擊工具欄的運行 -> 運行到小程序模擬器 -> 微信開發者工具，即可在微信開發者工具里面體驗uni-app。

   

   注意：如果是第一次使用，需要先配置小程序ide的相關路徑，才能運行成功。如下圖，需在輸入框輸入微信開發者工具的安裝路徑。 若HBuilderX不能正常啟動微信開發者工具，需要開發者手動啟動，然后將uni-app生成小程序工程的路徑拷貝到微信開發者工具里面，在HBuilderX里面開發，在微信開發者工具里面就可看到實時的效果。

    

   uni-app默認把項目編譯到根目錄的unpackage目錄。

   

    

    

    

    

   別的小程序等等等，查看官方文檔

   https://uniapp.dcloud.io/quickstart?id=%E8%BF%90%E8%A1%8Cuni-app

   3.1.3 發布

   打包為原生App（雲端）

   在HBuilderX工具欄，點擊發行，選擇原生app-雲端打包，如下圖：

   

    

   出現如下界面，點擊打包即可。

   

    

   打包為原生App（離線）

   uni-app 支持離線打包，在 HBuilderX 生成離線打包資源，然后參考 離線打包（或參考其他用戶寫的 離線打包日記），即可進行離線打包。

   在HBuilderX工具欄，點擊發行，選擇本地打包，如下圖，點擊即可生成離線打包資源。

   

    

    

   發布為H5

   1. 在 manifest.json 的可視化界面，進行如下配置（發行在網站根目錄可不配置應用基本路徑），此時發行網站路徑是 www.xxx.com/h5，如： https://uniapp.dcloud.io/h5。

      

    

   1. 在HBuilderX工具欄，點擊發行，選擇網站-H5手機版，如下圖，點擊即可生成 H5 的相關資源文件，保存於 unpackage 目錄。

   

   注意：history 模式發行需要后台配置支持，詳見：history 模式的后端配置

    

   發布為微信小程序：

   1. 申請微信小程序AppID，參考： 微信教程。
   2. 在HBuilderX中頂部菜單依次點擊 "發行" => "小程序-微信"，輸入小程序名稱和appid點擊發行即可在 unpackage/dist/build/mp-weixin 生成微信小程序項目代碼 。

      

   在微信開小程序發者工具中，導入生成的微信小程序項目，測試項目代碼運行正常后，點擊"上傳"按鈕，之后按照 "提交審核" => "發布" 小程序標准流程，逐步操作即可，詳細查看：微信官方教程。

    

    

    

   到此，相信一個小小的hello world都出來了。

    

   我寫的todoList（h5,app,微信小程序）的demo :

   git clone https://gitee.com/feng_dance/uniapp_demo.git 切換到vuex分支

    

    

4. 如何實現跨端

   雖說是跨端，但是肯定是有情況是不支持的，比如遇到有些平台特有的 API 怎么辦 ？

   不用擔心，這些問題 uni-app 都為你想到了 那就是使用條件編譯 。

    

    

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

   條件編譯是利用注釋實現的，在不同語法里注釋寫法不一樣，js使用 // 注釋、css 使用 /* 注釋 */、vue/nvue 模板里使用 <!-- 注釋 -->。

   舉個例子：

   // #ifdef %PLATFORM%

   平台特有的API實現

   // #endif

    

   // #ifndef H5

   // 表示只有 h5 不使用這個 api

   uni.createAnimation(OBJECT)

   // #endif

    

    

    

   <!-- #ifdef %PLATFORM% -->

   平台特有的組件

   <!-- #endif -->

    

   <!-- #ifdef MP-WEIXIN -->

   <!-- 只在小程序中生效 -->

   <view>我是微信小程序</view>

   <!-- #endif -->

    

   <!-- #ifdef APP-PLUS -->

   <!-- 只在 app 中生效 -->

   <view>我是 app </view>

   <!-- #endif -->

    

    

   /* #ifdef %PLATFORM% */

   平台特有樣式

   /* #endif */

    

   /* #ifdef MP-WEIXIN */

   /* 只在小程序中生效 */

   .header {

       color:red

   }

   /* #endif */

    

   /* #ifdef APP-PLUS */

   /* 只在 app 中生效 */

   .header {

       color:blue

   }

   <!-- #endif */

   詳細官方文檔： https://uniapp.dcloud.io/platform

    

    

5. 注意事項

   4.1 JS注意

   非H5端，不能使用瀏覽器自帶對象，比如document、window、localstorage、cookie等，更不能使用jquery等依賴這些瀏覽器對象的框架。因為各家小程序快應用都不支持這些對象。

   沒有這些瀏覽器自帶對象並不影響業務開發，uni提供的api足夠完成業務。

   uni的api在編譯到web平台運行時，其實也會轉為瀏覽器的js api。

   uni的api是多端可用的。在條件編譯區，每個平台的專有api也可以使用，比如wx.、plus.等api可以分別在微信下和app下使用。

   出於降低小程序向uni-app遷移成本的考慮，wx的api在app里也可以直接運行，比如寫wx.requst和uni.requst是一樣的，但仍然建議僅在微信的條件編譯區使用wx的api。

    

   4.2 Tag注意

   uni-app的tag同小程序的tag，和HTML的tag不一樣，比如div要改成view，span要改成text、a要改成navigator。

   出於降低h5應用向uni-app遷移成本的考慮，寫成div、span也可以運行在app和小程序上，因為uni-app編譯器會把這些HTML標簽編譯為小程序標簽。但仍然建議養成新習慣。

    

   4.3 Css注意

   雖然大部分css樣式在微信小程序和app中都可以支持，但推薦使用flex布局模型，這種布局更靈活高效且支持更多平台(比如nvue、快應用只支持flex布局)

   單位方面，uni-app默認為upx。這是一種可跨端的通用單位 詳見

   如果使用rpx，為了兼容，在發布到微信和App時也可以使用，但無法再跨更多平台了

    

   4.4工程目錄注意

   每個要顯示的頁面，都要放到pages目錄下，新建一個頁面所在的目錄，然后放同名目錄的vue文件，比如project/pages/lista/lista.vue，並且在pages.json里配置。這與小程序的策略相同。

   自定義組件，放到component目錄

   靜態資源如圖片，固定放到static目錄下。這是webpack、mpvue的規則

    

   4.5 數據綁定方式的注意

   uni-app 基於Vue 2.0實現，開發者需注意Vue 1.0 -> 2.0 的使用差異，詳見從 Vue 1.x 遷移

    

   每個頁面支持使用原生title，首頁支持使用原生底部tab，這些是要在pages.json里配置，這些並不是vue頁面的一部分。當然vue里的js api也可以動態修改原生title

    

   雖然使用vue，但在app和小程序里，不是spa而是mpa

    

   位置坐標系統一為國測局坐標系gcj02，這種坐標系可以被多端支持。老版5+的百度定位和百度地圖使用的是百度私有坐標系bd09ll，這種坐標系需要轉換。新版uni-app里的百度地圖已經默認改為gcj02。高德地圖不受影響，一直是gcj02

    

    

   4.6 H5 開發注意

   框架不支持Vue-router 默認增加頁面及路由和微信小程序類似

    

   H5 發布到服務器注意：

    

   1. 配置發行后的路徑（發行在網站根目錄可不配置），比如發行網站路徑是 www.xxx.com/html5，在 manifest.json 文件內編輯 h5 節點，router 下增加 base 屬性為 html5

   

   1. 點擊菜單 發行-> H5
   2. 在當下項目下的 unpackage/dist/build/h5 目錄找到出的資源，部署服務器（或者使用本地服務器預覽）

   引用第三方 js 的方式：

   通過 npm 引入（通過條件編譯，只有是 h5 平台是才 import 相應的庫）

   在 manifest.json 文件編輯 h5 節點的 template 屬性，填寫 html 模版路徑，在 html 模版里面可以使用 script 的方式引入三方的 js，如下示例是加了百度統計的 html 模板部分代碼，模版全部代碼可參考：自定義模板

    

   ...

   <body>

   <noscript>

   <strong>Please enable JavaScript to continue.</strong>

   </noscript>

   <div id="app"></div>

   <!-- built files will be auto injected -->

   <script>

   var _hmt = _hmt || [];

   (function() {

   var hm = document.createElement("script");

   hm.src = "https://hm.baidu.com/hm.js?xxxxxx";

   var s = document.getElementsByTagName("script")[0];

   s.parentNode.insertBefore(hm, s);

   })();

   </script>

   </body>

   ...

    

    

    

    

   組件方面：支持 mpvue 組件、支持普通 vue 組件、不支持小程序自定義組件、不支持 nvue。

    

   H5 版 uni-app 全支持 vue 語法，所以可能造成部分寫法在 H5 端生效，在小程序或 App 端不生效。

    

   H5 校驗了更嚴格的 vue 語法，有些寫法不規范會報警，比如： data 后面寫對象會報警，必須寫 function；不能修改 props 的值；組件最外層 template 節點下不允許包含多個節點等。

    

   編譯為 H5 版后生成的是單頁應用（SPA）。

    

   如果遇到了白屏或網絡不給力的提示，一般是跨域問題，網絡請求（request、uploadFile、downloadFile等）在瀏覽器存在跨域限制，需服務端配合才能跨域。解決方案有2種：

    

   服務器打開跨域限制；

   本地瀏覽器安裝跨域插件，參考：Chrome 跨域插件免翻牆安裝 或 firefox跨域插件。

   APP 和小程序的導航欄和 tabbar 均是原生控件，元素區域坐標是不包含原生導航欄和 tabbar 的；而 H5 里導航欄和 tabbar 是 div 模擬實現的，所以元素坐標會包含導航欄和tabbar的高度。為了優雅的解決多端高度定位問題，uni-app 新增了2個css變量：--window-top 和 --window-bottom，這代表了頁面的內容區域距離頂部和底部的距離。舉個實例，如果你想在原生tabbar 上方懸浮一個菜單，之前寫 bottom:0。這樣的寫法編譯到 h5 后，這個菜單會和 tabbar 重疊，位於屏幕底部。而改為使用 bottom:var(--window-bottom)，則不管在 app 下還是在h5下，這個菜單都是懸浮在 tabbar 上浮的。這就避免了寫條件編譯代碼。當然仍然也可以使用 H5 的條件編譯處理界面的不同。

    

    

   CSS 內使用 vh 單位的時候注意 100vh 包含導航欄，使用時需要減去導航欄和 tabBar 高度，部分瀏覽器還包含瀏覽器操作欄高度，使用時請注意。

    

   正常支持 upx，px 是真實物理像素。暫不支持通過設 manifest.json 的 "transformPx" : true，把 px 當動態單位使用。

    

   使用羅盤、地理位置、加速計等相關接口需要使用 https 協議，本地預覽（localhost）可以使用 http 協議。

    

   PC 端 Chrome 瀏覽器模擬器設備測試的時候，獲取位置 API 需要連接谷歌服務器。

    

   組件內（頁面除外）不支持 onLoad、onShow 等頁面生命周期。

    

   為避免和內置組件沖突，自定義組件請加上前綴（但不能是 u 和 uni）。比如可使用的自定義組件名稱：my-view、m-input、we-icon，例如不可使用的自定義組件名稱：u-view、uni-input，如果已有項目使用了可能造成沖突的名稱，請修改名稱，另外微信小程序下自定義組件名稱不能以 wx 開頭。

    

   更多注意事項： https://uniapp.dcloud.io/matter

    

    

    

   參考資料

    

   https://segmentfault.com/a/1190000016156607 Dcloud,hbuilderX開發uni-app第一天踩坑記錄

   https://juejin.im/post/5c6f6e62f265da2d8c7dca9c uni-app 入坑指南

    

   https://uniapp.dcloud.io/quickstart?id=%e9%80%9a%e8%bf%87-hbuilderx-%e5%8f%af%e8%a7%86%e5%8c%96%e7%95%8c%e9%9d%a2  官方文檔