學習小程序時,一個很有價值的練習是嘗試把現有元件二次封裝,讓日後開發能快速 reuse。本文示範一個實際案例:picker 的 selector 模式只支援一級下拉,那能否用三個 picker 湊出三級聯動的地址選擇器,並封裝成可重複引入其他頁面的模板?答案是可以的。
整體思路有三點:
1、使用 template 模板語法封裝,資料由呼叫頁面傳入。
2、picker 的 range 只能是一組陣列,但我們需要每個地區的唯一碼來觸發下一級聯動。做法是透過一個物件裡的兩組資料分別存放中文名與唯一碼,格式為 province: { code: ['110000', '220000'...], name: ['北京市', '天津市'...] }。這個格式固定,需由後端配合回傳。
3、透過 picker 的 bindchange 事件取得下一級資料,每個方法都寫成函數再暴露出來供頁面呼叫。
demo 目錄結構
common
-net.js // wx.request 請求介面的二次整合
-cityTemplate.js // 三級聯動方法
page
-demo
-demo.js
-demo.wxml
template
-cityTemplate.wxml
app.js
app.json
app.wxss
測試時用 phpstudy 搭了一個簡單的後端提供資料。若不想處理後端,也可以把資料直接寫在 demo.js 裡測試。
後端腳本(areas.php)
回傳格式遵循下方的 retArr 規範:
<?php
header("Content-type: text/html; charset=utf-8");
$type = $_REQUEST["type"]; // 取得省市區的標志
$fcode = $_GET["fcode"];
$retArr = [
"status" => true,
"data" => [],
"msg" => ""
];
if ($type != "province" && $type != "city" && $type != "county") {
$retArr["status"] = false;
$retArr["msg"] = "獲取地區類型錯誤,請檢查";
echo json_encode($retArr);
exit;
}
function getProvince(){
$province = [];
$code = ["110000", "350000", "710000"];
$province["code"] = $code;
$name = ["北京市", "福建省", "台灣省"];
$province["name"] = $name;
$fcode = ["0", "0", "0"];
$province["fcode"] = $fcode;
return $province;
}
function getCity($P_fcode){
$city = [];
$code = []; $name = []; $fcode = [];
if ($P_fcode == "110000") {
$code = ["110100"];
$name = ["北京市"];
$fcode = $P_fcode;
}
if ($P_fcode == "350000") {
$code = ["350100", "350200", "350300", "350400", "350500",
"350600", "350700", "350800", "350900"];
$name = ["福州市", "廈門市", "莆田市", "三明市", "泉州市",
"漳州市", "南平市", "龍巖市", "寧德市"];
$fcode = $P_fcode;
}
if ($P_fcode == "710000") {
}
$city = ["code" => $code, "name" => $name, "fcode" => $fcode];
return $city;
}
function getCounty($P_fcode){
$county = [];
$code = []; $name = []; $fcode = [];
if ($P_fcode == "110100") {
$code = ["110101", "110102", "110103", "110104",
"110105", "110106", "110107"];
$name = ["東城區", "西城區", "崇文區", "宣武區",
"朝陽區", "豐台區", "石景山區"];
$fcode = $P_fcode;
}
if ($P_fcode == "350100") {
$code = ["350102", "350103", "350104"];
$name = ["鼓樓區", "台江區", "蒼山區"];
$fcode = $P_fcode;
}
if ($P_fcode == "350200") {
$code = ["350203", "350205", "350206"];
$name = ["思明區", "海滄區", "湖裡區"];
$fcode = $P_fcode;
}
$county = ["code" => $code, "name" => $name, "fcode" => $fcode];
return $county;
}
if ($type == "province") {
$retArr["data"] = getProvince();
} else if ($type == "city") {
$retArr["data"] = getCity($fcode);
} else if ($type = "county") {
$retArr["data"] = getCounty($fcode);
}
echo json_encode($retArr);
?>
這裡要指出一個 bug:最後一個條件寫成 $type = "county"(單等號,指派而非比較)。這會使該條件永遠成立,導致任何請求都跑到 county 分支。應改為 $type == "county"。這類錯誤在 PHP 中不會報錯,卻會造成難以察覺的邏輯錯誤。
cityTemplate.wxml
<template name="city">
<view class="areas">
<view class="province">
<picker bindchange="provincePickerChange"
value="{{provinceIndex}}"
range="{{province.name}}"
data-city-url="{{cityUrl}}">
<text class="select-item">{{province.name[provinceIndex]}}</text>
</picker>
</view>
<view class="city">
<block wx:if="{{!city.name.length}}">
--二級市區--
</block>
<block wx:if="{{city.name.length>0}}">
<picker bindchange="cityPickerChange"
value="{{cityIndex}}"
range="{{city.name}}"
data-county-url="{{countyUrl}}">
<text class="select-item">{{city.name[cityIndex]}}</text>
</picker>
</block>
</view>
<view class="county">
<block wx:if="{{!county.name.length}}">
--三級地區--
</block>
<block wx:if="{{county.name.length>0}}">
<picker bindchange="countyPickerChange"
value="{{countyIndex}}"
range="{{county.name}}">
<text class="select-item">{{county.name[countyIndex]}}</text>
</picker>
</block>
</view>
</view>
</template>
注意每個 picker 都用 range="{{xxx.name}}" 只取中文名陣列來顯示,而 code 陣列則在事件處理中對應索引取出,用於請求下一級。這正是前述「name 與 code 並存」設計的價值:畫面用 name,邏輯用 code,兩者靠索引對齊。
另外每層都有 wx:if 的空值判斷,當上一層尚未選擇時,下一層不顯示 picker 而是顯示提示文字,避免使用者點到無效的選項。
cityTemplate.js
/**
* 取得三級聯動的三個函數
* that: 註冊頁面的 this 實例(必填)
* p_url: 一級省份 url(必填)
* p_data: 一級省份參數(選填)
*/
var net = require("net"); // 引入 request 方法
var g_url, g_datd, g_cbSuccess, g_cbSuccessErr,
g_cbFail, g_cbComplete, g_header, g_method;
function initCityFun(that, p_url, p_data) {
// 取得一級省份數據
g_cbSuccess = function(res) {
that.setData({ 'city.province': res });
};
net.r(p_url, p_data, g_cbSuccess, g_cbSuccessErr,
g_cbFail, g_cbComplete, g_header, g_method);
// 點擊一級 picker 觸發事件並取得市區方法
var changeProvince = function(e) {
that.setData({ 'city.provinceIndex': e.detail.value });
var _fcode = that.data.city.province.code[e.detail.value];
if (!_fcode) { _fcode = 0; }
var _cityUrl = e.target.dataset.cityUrl;
g_url = _cityUrl + _fcode;
g_cbSuccess = function(res) {
that.setData({ 'city.city': res });
};
net.r(g_url, g_datd, g_cbSuccess, g_cbSuccessErr,
g_cbFail, g_cbComplete, g_header, g_method);
};
that["provincePickerChange"] = changeProvince;
// 點擊二級 picker 觸發事件並取得地區方法
var changeCity = function(e) {
that.setData({ 'city.cityIndex': e.detail.value });
var _fcode = that.data.city.city.code[e.detail.value];
if (!_fcode) { _fcode = 0; }
var _countyUrl = e.target.dataset.countyUrl;
g_url = _countyUrl + _fcode;
g_cbSuccess = function(res) {
that.setData({ 'city.county': res });
};
net.r(g_url, g_datd, g_cbSuccess, g_cbSuccessErr,
g_cbFail, g_cbComplete, g_header, g_method);
};
that["cityPickerChange"] = changeCity;
// 點擊三級 picker 觸發事件
var changeCounty = function(e) {
that.setData({ 'city.countyIndex': e.detail.value });
};
that["countyPickerChange"] = changeCounty;
}
function getProvinceFun(that, p_url, p_data) {
g_cbSuccess = function(res) {
that.setData({ 'city.province': res });
};
net.r(p_url, p_data, g_cbSuccess, g_cbSuccessErr,
g_cbFail, g_cbComplete, g_header, g_method);
}
module.exports = {
initCityFun: initCityFun,
getProvinceFun: getProvinceFun
}
這個模組的關鍵設計是:把事件處理函數動態掛到傳入的 that 頁面實例上(that["provincePickerChange"] = ...)。因為 wxml 中的 bindchange 必須綁定頁面實例上的方法,而 template 無法直接引用外部模組的函數,這個技巧就把邏輯抽離到可重複使用的模組中,同時讓 template 保持通用。
net.js 網路請求封裝
/**
* 網絡發送 http 請求,預設返回類型為 json
*
* url: 必須,其他參數非必須 —— 介面地址
* data: 請求的參數,Object 或 String
* successFun(dts): 成功返回的回調函數,已自動過濾微信端添加的數據,
* 按介面約定回傳成功後的 data 數據,過濾掉 msg 和 status
* successErrorFun(msg): 成功執行請求,但服務端認為業務錯誤時執行,
* 預設彈出系統提示資訊
* failFun: 介面調用失敗的回調函數
* completeFun: 介面調用結束的回調函數(成功、失敗都會執行)
* header: object,設置請求的 header,header 中不能設置 Referer
* method: 預設為 GET,有效值:OPTIONS, GET, HEAD, POST,
* PUT, DELETE, TRACE, CONNECT
*/
function r(url, data, successFun, successErrorFun,
failFun, completeFun, header, method) {
var reqObj = {};
reqObj.url = url;
reqObj.data = data;
// 預設 header 為 json
reqObj.header = { 'Content-Type': 'application/json' };
if (header) {
reqObj.header = header; // 覆蓋 header
}
if (method) {
reqObj.method = method;
}
reqObj.success = function(res) {
var returnData = res.data;
var status = returnData.status;
// 按介面約定,status 為 true 時才呼叫成功函數
if (status == true) {
if (successFun) {
var dts = returnData.data;
successFun(dts); // 回調,相當於取到 data 後直接在回調裡處理賦值
}
} else if (status == false) {
var msg = returnData.msg;
if (!successErrorFun) {
console.log(msg);
} else {
successErrorFun(msg);
}
} else {
console.log("服務端沒有按照介面約定格式返回數據");
}
};
reqObj.fail = function(res) {
if (failFun) { failFun(res); }
};
reqObj.complete = function(res) {
if (completeFun) { completeFun(res); }
};
wx.request(reqObj);
}
module.exports = { r: r }
這層封裝的價值在於統一了「業務成功」與「請求成功」兩個概念:HTTP 請求成功不代表業務成功,因此才需要 status 欄位做二次判斷,並把兩種情況分派到不同的回呼函數。這是前後端分離架構下相當常見的處理方式。
demo.wxml
<import src="../../template/cityTemplate.wxml"/>
<template is="city" data="{{...city}}" />
demo.js
var city = require('../../common/cityTemplate');
Page({
data: {},
onLoad: function(options) {
var _that = this;
// 建立三級聯動資料物件
// 這個 city 物件是固定的,只有請求的 url 需依各自後端位址更改
_that.setData({
city: {
province: {}, // 格式 province: {code: ["110000", "120000"],
// name: ["北京市", "上海市"]},
// 只能固定是 name 和 code,因為模板需要依這兩個參數顯示
city: {},
county: {},
provinceIndex: 0,
cityIndex: 0,
countyIndex: 0,
cityUrl: "https://localhost:8282/phpserver/areas.php?type=city&fcode=",
// type 表示獲取地區,fcode 是一級 code 碼,
// 具體依後端請求參數修改
countyUrl: "https://localhost:8282/phpserver/areas.php?type=county&fcode="
}
});
var _url = "https://localhost:8282/phpserver/areas.php";
var _data = { 'type': 'province', 'fcode': '0' };
city.initCityFun(_that, _url, _data);
}
})
最終測試結果

已知問題與改進方向
實作中發現一個問題:開啟下拉刷新後,picker 的下拉層會與之重疊,不確定是開發工具的問題還是尚未修正的 bug,只能等官方後續更新。
此外有幾處可以再加強。第一,net.js 未處理請求失敗(fail)的預設提示,網路異常時使用者得不到任何回饋。第二,正式環境的介面位址應改用 HTTPS,並在小程序後台設定合法網域,否则請求會被攔下。第三,initCityFun 中的 g_url、g_cbSuccess 等變數屬於模組層級,多個頁面同時使用時會互相覆寫;若專案中會在多處使用,應改為函數內的區域變數或封裝成類別。這是最值得優先修正的一點。