前言
本文基於 HBuilderX 3.1.22 + 微信開發者工具 1.05.2106300為主要內容進行說明。
文件版本：1.0.0
更新時間：2021-09-03 15:32
一、準備
uni-app 是一個使用 Vue.js 開發所有前端應用的框架，開發者編寫一套程式碼，可釋出到iOS、Android、Web（響應式）、以及各種小程式（微信/支付寶/百度/頭條/QQ/快手/釘釘/淘寶）、快應用等多個平臺。
1.1 軟體安裝
建立uni-app有兩種，一個是通過 HBuilderX 視覺化介面，另一個是通過vue-cli命令列。本文件以HbuilderX為建立說明，以微信開發者工具進行執行專案和程式碼說明。
HbuilderX 下載地址：https://www.dcloud.io/hbuilderx.html
HbuilderX 文件地址：https://hx.dcloud.net.cn/Tutorial/startup
微信開發者工具下載地址：https://developers.weixin.qq.com/miniprogram/dev/devtools/download.html
HbuilderX安裝結束後，一般需要下載開發專案需要的外掛，選擇工具-->外掛安裝-->安裝或去市場外掛查詢下載，然後放到目錄下的uni_modules資料夾（安裝時候自動生成），如scss/sass編譯，App真機執行等。
微信開發者工具安裝結束後，在工具欄上選擇 設定-->通用設定-->安全-->開啟服務埠。
其次，在微信開發者平臺(https://open.weixin.qq.com/)註冊開發者賬號，找到自己的開發ID，AppId，並記錄好，為專案從HbuilderX執行到微信開發者工具做準備。接著配置開發者AppId，在微信開發者工具介面點選右上角詳情->基本資訊->AppId進行配置，開發環境下配置：點選右上角詳情->本地設定->打鉤"不校驗合法域名...."。
1.2 vue入門
由於uni-app是以vue為基礎的小程式開發，所以使用uni-app之前需要對vue有一定的瞭解。
vue 文件地址：https://vuejs.bootcss.com/guide/
二、基於HbuilderX 的uni-app專案搭建
2.1 建立專案
1.在點選工具欄裡的檔案 -> 新建 -> 專案：
2.選擇uni-app型別，輸入工程名，選擇模板，點選建立，即可成功建立。
uni-app自帶的模板有 Hello uni-app ，是官方的元件和API示例。還有一個重要模板是 uni ui專案模板，日常開發可以參考該模板，畢竟這個模板已內建大量常用元件。
然後在HBuilder X內工具欄點選 執行—>執行到小程式模擬器 -->微信開發者工具，便能初步看到執行成效。
2.2 目錄補充搭建
本次建立使用預設版本，建立後的目錄如下：
1 根據需要給專案搭建相應的目錄結構。尚未下載依賴和市場外掛之前，建立需要的資料夾和檔案：
2 如果要下載vue，vuex等依賴，在之前需要先安裝node.js，並且安裝好node的包管理器（npm,cnpm,yarn等，一個即可，本文件以npm為例）
node相關地址：http://nodejs.cn/
安裝教程：https://www.runoob.com/nodejs/nodejs-install-setup.html
A. 初始化package.json檔案
B.使用程式碼，其中注意最好加上--save
npm install vue --save
npm install uview-ui --save
下載vue和uview依賴。其中，vue是開發uni-app必要的依賴，uview則是uni-app生態的一個優秀的UI框架，本文件以uview作為前端UI開發框架為基礎進行開發搭建。執行下載後，專案會自動把依賴放進node_modules資料夾內，可在node_modules資料夾進行檢視。然後下載開發專案需要的市場外掛，市場外掛預設自行建立外掛所在資料夾uni_modules，並存放外掛於此。
vue相關地址：https://vuejs.bootcss.com/guide/
uview相關地址：https://www.uviewui.com/components/intro.html
最後，建立頁面和對應頁面的api檔案（本文件僅以登入頁面、主頁面和登入api檔案為例），這樣一個基本的結構接搭建好了，最終結構目錄大體如下：
其中.hbuilderx，unpackage資料夾是自動生成，不必自主建立。node_modules，uni_modules資料夾裡的檔案最好不必去改動。
C.目錄結構說明如下：
| 層級1 | 層級2 | 層級3 | 描述 |
|---|---|---|---|
| api | 各個模組介面資料夾 | ||
| login.js | 登入模組檔案 | ||
| common | 公共模組，包含公共基礎css等 | ||
| base.css | 公共基礎css | ||
| components | 符合vue元件規範的uni-app元件目錄 | ||
| node_modules | nodejs相關依賴包檔案目錄 | ||
| pages | 業務頁面檔案存放的目錄 | ||
| index | index資料夾 | ||
| index.vue | 主頁面 | ||
| login | login資料夾 | ||
| index.vue | 登入主頁面 | ||
| static | 存放應用引用的本地靜態資源（如圖片、視訊等）的目錄，注意：靜態資源只能存放於此，不要放css檔案 | ||
| store | vuex目錄，也是存放公共屬性方法的地方 | ||
| index.js | vuex的主檔案 | ||
| uni_modules | 外掛市場下載的第三方UI元件目錄，存放uni_module規範的外掛。 | ||
| unpackage | 打包目錄，這裡有各個平臺的打包檔案。 | ||
| utils | 全域性公共方法目錄 | ||
| common.js | 封裝的公共可複用的方法屬性檔案（針對當前專案） | ||
| request.js | 封裝的公共請求方法檔案 | ||
| utils.js | 封裝的公共可複用的方法屬性檔案（針對所有專案） | ||
| App.vue | 應用配置檔案，用來配置App全域性樣式以及監聽應用生命週期 | ||
| main.js | Vue初始化入口檔案 | ||
| manifest.json | 配置應用名稱、appid、logo、版本等打包資訊的檔案 | ||
| package.json | 專案配置資訊檔案，依賴模組的定義 | ||
| package-lock.json |
1.鎖定包的版本，確保再次下載時不會因為包版本不同而產生問題 2.加快下載速度，因為該檔案中已經記錄了專案所依賴第三方包的樹狀結構和包的下載地址,重新安裝時只需下載即可，不需要做額外的工作 |
||
| pages.json | 配置頁面路由、導航條、選項卡等頁面類資訊的檔案 | ||
| uni.scss | 自帶的公共的css修飾檔案 | ||
| README.md | 文件說明，可包含目錄檔名稱對比，注意事項，框架使用，技術架構，Git或SVN地址，賬號密碼等 |
由於在pages建立了登入頁面，所以需要到pages.json去配置相關路徑。
pages.json
"pages": [
{
"path": "pages/login/index",
"style": {
"navigationBarTitleText": "登入"
}
},
{
"path": "pages/index/index",
"style": {
"navigationBarTitleText": "首頁"
}
}
]
<!--注意：-->
編譯到任意平臺時，static 目錄下的檔案均會被完整打包進去，且不會編譯。
非 static 目錄下的檔案（vue、js、css 等）只有被引用到才會被打包編譯進去。static 目錄下的 js 檔案不會被編譯，如果裡面有 es6 的程式碼，不經過轉換直接執行，在手機裝置上會報錯。
css、less/scss 等資源不要放在 static 目錄下，建議這些公用的資源放在自建的 common 目錄下。
2.3 搭建目錄檔案程式碼
根據需要，我們寫一個簡單的登入，使用登入功能來闡述各個目錄檔案之間的聯絡。
首先，我們先把已建立的相關檔案進行掛載到全域性，即在main.js或者App.vue寫相關程式碼：
main.js
App.vue
然後在被引入的檔案寫必要的內容資訊：
base.css
.clearfix:before{content:" ";display:table}
.clearfix:after{content:" ";display:table;clear:both}
.fl{float:left}
.fr{float:right}
request.js
export default function request({
url,
method = "GET",
params = {},
header,
loadding = false,
loaddingText = "載入中..."
}) {
return new Promise((resolve, reject) => {
if (loadding) {
uni.showLoading({
title: loaddingText
})
}
setTimeout(() => {
uni.request({
url,
method,
data: params,
header,
success: (res) => {
if (res) {
resolve(res.data)
} else {
resolve(res)
}
if (loadding) {
uni.hideLoading()
}
},
fail: (res) => {
reject(res)
}
})
}, 1000)
}).catch(err => {
// 這裡既可以捕獲throw的異常也可以捕獲reject的異常
console.log("[Promise catch]:", err)
if (loadding) {
uni.hideLoading()
}
})
}
common.js
export default {
BASE_URL:""
}
然後我們開始寫登入頁面。登入頁面需要寫使用者名稱、密碼、登入按鈕三個元件，則需要使用uview建立。使用uview建立元件之前的幾個確保：
確保1 HBuilder X 是安裝了 scss/sass 編譯外掛
確保2 在根目錄下 uni.scss 檔案中引入 uview-ui/theme.scss
@import 'uview-ui/theme.scss';
確保3 在根目錄下 App.vue 檔案中的style程式碼塊新增 lang="scss"屬性 和 引入 uview-ui/index.scss
<style lang="scss">
@import "uview-ui/index.scss";
</style>
確保4 在根目錄下main.js檔案中 引入並使用uView的JS庫，注意這兩行要放在import Vue之後。
import uView from "uview-ui";
Vue.use(uView);
如果是不想書寫引入檔案程式碼，即我們每當引入一個UI元件，就需要新增
import xxx from "uView-ui/components/u-xxx/u-xxx.vue";
等相關程式碼。則需要確保5 在根目錄下pages.json檔案中 ，配置easycom元件模式
// pages.json
{
"easycom": {
"^u-(.*)": "uview-ui/components/u-$1/u-$1.vue"
}, // 此為本身已有的內容
"pages": [
// ......
]
}
接著我們在pages/login/index.vue，即登入頁面中，引入uview元件和書寫登入程式碼：
pages/login/index.vue
<template>
<view class="content">
<view class="inp">
<u-input v-model="username" type="text" :border="true" placeholder="請輸入使用者名稱" />
</view>
<view class="inp">
<u-input v-model="password" type="password" :border="true" placeholder="請輸入密碼" />
</view>
<view class="inp">
<u-button type="primary" shape="circle" style="margin-top: 40rpx;" @click="onLogin">登入</u-button>
</view>
</view>
</template> <script>
import {
login
} from '@/api/login.js'
export default {
data() {
return {
username: '',
password: ''
}
},
onLoad() { },
methods: {
onLogin() {
// #ifdef MP-WEIXIN
uni.login({
success: res0 => {
login({
params: {
username: this.username,
password: this.password,
code: res0.code
},
loadding: true,
loaddingText: "登入中..."
}).then(res => {
this.$store.state.userinfo = res
if (res) {
uni.reLaunch({
url: "../index/index"
})
} else {
uni.showToast({
title: "登入失敗",
duration: 1000,
icon: "none"
})
}
})
},
fail: err => {
console.log("fail:", err)
}
})
// #endif
// #ifdef H5
uni.reLaunch({
url: "../index/index"
})
// #endif
}
}
}
</script> <style scoped lang="scss">
.content {
padding: 20px; .inp {
margin: 10px;
}
}
</style>
以上程式碼為先進行獲取使用者登入憑證code，然後才正式登入。因為開發者需要在開發者伺服器後臺，使用 code 換取 openid 和 session_key 等資訊。然後使用得到的code，和使用者名稱密碼一起作為引數進行真正的登入請求。其中，樣式最好內聚在元件內，元件內部使用的樣式，儘量在style中新增scoped，編譯時會增加元件hash字首來防止樣式汙染。
login頁面 有請求資料，則需要寫login.js請求介面：
login.js
import common from '@/utils/common.js'
import request from '@/utils/request.js' // 登入
export async function login(payload) {
return await request({
url: common.BASE_URL + "http://rap2api.taobao.org/app/mock/229799/http://login",
method: "POST",
params: payload.params,
loadding: payload.loadding,
loaddingText: payload.loaddingText
})
}
介面文件地址： https://cloud.udi-link.com/cps_qlimp/swagger-ui.html
login頁面 有使用 this.$store.state，則需要對store/index.js寫程式碼：
store/index.js
import Vue from 'vue';
import Vuex from "vuex";
Vue.use(Vuex); export default new Vuex.Store({
state: {
userinfo: ""
},
actions: { },
mutations: { },
getters: { }
})
到此，直接點選工具欄上的執行-->執行到小程式模擬器-->微信開發者工具，結果如下圖所示：
然後如果要進行除錯，則需要開啟偵錯程式，點選偵錯程式介面的source選項，找到對應的程式碼檔案，進行斷點除錯，比如：
或者直接使用H5模式執行到瀏覽器，在移除相關會影響程式碼除錯的微信開發者工具方法或屬性後，在網頁上開啟控制檯進行除錯程式碼。需要注意的是，部分樣式在H5和微信小程式中顯示有區別，儘量以小程式顯示為主。
三、打包發行
使用hbuilderx進行打包發行小程式，點選工具欄的發行 --> 小程式-微信，然後它會自主開啟微信開發者工具介面，這時候我們點選右上角的上傳按鈕，填寫版本號、描述相關資訊 - 確定即可。
四、注意事項
事項1
@import "uview-ui/index.scss";
如果引入在除了App.vue之外的檔案，而App.vue本身沒有引入，可能會引起樣式不全修飾等問題，比如登入的密碼輸入框，當輸入密碼時候顯示清空按鈕，此時會讓密碼框下移。
事項2
打包微信小程式只有包小於2MB才能上傳。