建站
咨詢
售后
建站咨詢
新聞中心
插件功能頁
插件功能頁從小程序基礎庫版本 2.1.0 開始支持。
創(chuàng)新互聯(lián)建站主要從事網站制作、成都做網站、網頁設計、企業(yè)做網站、公司建網站等業(yè)務。立足成都服務門頭溝,10多年網站建設經驗,價格優(yōu)惠、服務專業(yè),歡迎來電咨詢建站服務:18982081108
某些接口不能在插件中直接調用（如 wx.login），但插件開發(fā)者可以使用插件功能頁的方式來實現(xiàn)功能。目前，插件功能頁包括：
- 獲取用戶信息，包括 openid 和昵稱等（相當于 wx.login 和 wx.getUserInfo 的功能），詳見用戶信息功能頁；
- 支付（相當于 wx.requestPayment），詳見支付功能頁；
- 獲取收貨地址（相當于 wx.chooseAddress），詳見收貨地址功能頁。
要使用插件功能頁，需要先激活功能頁特性，配置對應的功能頁函數(shù)，再使用 functional-page-navigator 組件跳轉到插件功能頁，從而實現(xiàn)對應的功能。詳情請參考下文。
插件所有者小程序
開始開發(fā)之前，我們需要知道，插件功能頁是指 插件所有者小程序 中的一個特殊頁面。
插件所有者小程序，指的是與插件 AppID 相同的小程序。例如，“小程序示例”小程序開發(fā)了一個“小程序示例插件”，那么無論這個插件被哪個小程序使用，這個插件的 插件所有者小程序 都是“小程序示例”。下文中會繼續(xù)使用 插件所有者小程序 這個說法。
插件所有者小程序開發(fā)方法
通常，在開始使用插件功能頁的時候，需要開啟兩個開發(fā)者工具窗口，其中一個打開插件項目，另一個打開插件所有者小程序的小程序項目。例如，一個打開“小程序示例插件”項目，另一個打開“小程序示例”項目。
這兩個窗口，前者用于編輯插件，后者用于編輯插件所有者小程序。下文中所有需要編輯插件所有者小程序的內容，都是在后者中進行。
激活功能頁特性
要在插件中調用插件功能頁，需要先激活插件所有者小程序的功能頁特性。具體來說，在插件所有者小程序的 app.json 文件中添加 functionalPages 定義段，并令其值為 true ，例如：
代碼示例：
{
"functionalPages": {
"independent": true
}
}
目前，兼容舊式寫法：
{
"functionalPages": true
}
舊式寫法將在未來將被移除支持，未來將不能編譯上傳。
這兩種寫法的區(qū)別在于，新式的寫法 "independent": true 會使得插件功能頁的代碼獨立于其他代碼，這意味著插件功能頁可以被獨立下載、加載，具有更好的性能表現(xiàn)。 但也同時使得插件功能頁目錄 functional-pages/ （支付功能頁會使用其中的文件）不能 require 這個目錄以外的文件（反之亦然：這個目錄以外的文件也不能調用這個目錄內的）。
注意，新增或改變這個字段時，需要這個小程序發(fā)布新版本，才能在正式環(huán)境中使用插件功能頁。
跳轉到功能頁
功能頁不能使用 wx.navigateTo 來進行跳轉，而是需要一個名為 functional-page-navigator 的組件。以獲取用戶信息為例，可以在插件中放置如下的 functional-page-navigator：
代碼示例：
用戶在點擊這個 navigator 時，會自動跳轉到插件所有者小程序的對應功能頁。功能頁會提示用戶進行登錄或其他相應的操作。操作結果會以組件事件的方式返回。
functional-page-navigator 的參數(shù)和詳細使用方法可以參考組件說明 。
從小程序基礎庫版本 2.4.0 開始，支持插件所有者小程序跳轉到自己的功能頁。在基礎庫版本低于 2.4.0 時，點擊跳轉到自己的功能頁的 functional-page-navigator 將沒有任何反應。
真機開發(fā)測試的常規(guī)步驟
目前，功能頁的跳轉目前不支持在開發(fā)者工具中調試，請在真機上測試。初次進行真機開發(fā)測試時，通常步驟如下：
- 在開發(fā)者工具上打開插件所有者小程序項目，并點擊“預覽”；
- 用測試用的真機掃一下預覽二維碼，此時會進入插件所有者小程序，進入后就可以直接退出這個小程序；
- 在開發(fā)者工具上打開插件項目，將插件中 functional-page-navigator 中的 version 屬性設置為 develop；
- 點擊預覽可以生成插件預覽二維碼，用測試用的真機掃碼即可預覽功能頁；如果更改了插件代碼，重新生成并掃描插件的預覽二維碼即可；
- 如果過了一段時間之后，跳轉功能頁時出現(xiàn)“開發(fā)版已過期”這樣的提示，從第1步開始重試一次。
注意：functional-page-navigator 的 version=develop 僅用于調試，因此在插件提審前，需要：
- 確保已發(fā)布設置了 "functionalPages": true 的插件所有者小程序；
- 確保所有的 functional-page-navigator 組件屬性設置為 version="release" 。
功能頁常見問題 FAQ
如何正確編輯插件所有者小程序？
- 應該在開發(fā)者工具的“小程序”類型項目中編輯，而不是在“插件”類型的項目中編輯。比如，“小程序示例插件”的所有者小程序是“小程序示例”，它們的 AppID 都是 wxidxxxxxxxxxxxxxx ，如果是初次開發(fā)“小程序示例”小程序，可以在開發(fā)者工具中創(chuàng)建一個小程序項目，其 AppID 為 wxidxxxxxxxxxxxxxx ；如果之前開發(fā)過“小程序示例”小程序，直接打開之前的小程序項目即可。
點擊 functional-page-navigator 之后沒有任何反應。
- 請檢查引用插件的小程序和插件本身是不是同一個 AppID ，如果是，跳轉到自己的功能頁需要基礎庫 2.4.0 支持，否則使用 functional-page-navigator 不會有任何反應。
點擊 functional-page-navigator 之后，展示了一個頁面提示“頁面不存在”。
- 這種情況是因為插件所有者小程序沒有正確設置 "functionalPages": true 。如果 functional-page-navigator 的 version="develop" ，這部手機需要掃碼并進入插件所有者小程序一次；如果 version="release" ，請確保包含 "functionalPages": true 的插件所有者小程序已被發(fā)布。
點擊 之后，彈窗提示“小程序開發(fā)版已過期”。
- 遇到這種情況，重新掃碼并進入插件所有者小程序一次即可。
點擊 之后，展示了一個頁面提示“該功能無法使用”。
- 在使用插件功能頁時，小程序不能是個人小程序，同時，插件也需要額外的步驟申請開通插件支付權限（位于 管理后臺 -> 小程序插件 -> 基本設置 -> 支付能力 ）。
點擊 之后，點擊頁面中的“支付”按鈕，立刻退出了支付功能頁。
- 這通常是因為沒有找到功能頁函數(shù) beforeRequestPayment ，請檢查插件所有者小程序的 functional-pages/request-payment.js 文件和其中的 beforeRequestPayment 函數(shù)是否存在。
點擊 functional-page-navigator 之后，展示了一個僅有返回按鈕的頁面。
- 請檢查 functional-page-navigator 的 name 屬性是否被正確設置。
開發(fā)版可以正常跳轉，但審核反饋不能跳轉。
- 請發(fā)布設置了 "functionalPages": true 的插件所有者小程序，且所有的 functional-page-navigator 組件屬性設置為 version="release" 。
Bugs & Tips
- 功能頁是插件所有者小程序中的一個特殊頁面，開發(fā)者不能自定義這個頁面的外觀。
- 插件所有者小程序本身也可以引用這個插件，此時，functional-page-navigator 組件的 version 屬性將不會生效，而是取決于當前運行的插件所有者小程序的版本。
- functional-page-navigator 可以在開發(fā)者工具中使用，但功能頁的跳轉目前不支持在開發(fā)者工具中調試，請在真機上測試。
- Bug：在微信版本 6.6.7 中，功能頁被拉起時會觸發(fā) App 的部分生命周期并使得功能頁啟動時間變得比較長。在后續(xù)的微信版本中這一行為會發(fā)生變更，使 App 生命周期不再被觸發(fā)。
用戶信息功能頁
用戶信息功能頁用于幫助插件獲取用戶信息，包括 openid 和昵稱等，相當于 wx.login 和 wx.getUserInfo 的功能。
此外，自基礎庫版本 2.3.1 起，用戶在這個功能頁中授權之后，插件就可以直接調用 wx.login 和 wx.getUserInfo 。無需再次進入功能頁獲取用戶信息。自基礎庫版本 2.6.3 起，可以使用 wx.getSetting 來查詢用戶是否授權過。
調用參數(shù)
用戶信息功能頁使用 functional-page-navigator 進行跳轉時，對應的參數(shù) name 應為固定值 loginAndGetUserInfo，其余參數(shù)與 wx.getUserInfo 相同，具體來說：
args參數(shù)說明：
| 參數(shù)名 | 類型 | 必填 | 說明 |
|---|---|---|---|
| withCredentials | Boolean | 否 | 是否帶上登錄態(tài)信息 |
| lang | String | 否 | 指定返回用戶信息的語言，zh_CN 簡體中文，zh_TW 繁體中文，en 英文。默認為en。 |
| timeout | Number | 否 | 超時時間，單位 ms |
注：當 withCredentials 為 true 時，返回的數(shù)據會包含 encryptedData, iv 等敏感信息。
bindsuccess返回參數(shù)說明：
| 參數(shù) | 類型 | 說明 |
|---|---|---|
| code | String | 同 wx.login 獲得的用戶登錄憑證（有效期五分鐘）。開發(fā)者需要在開發(fā)者服務器后臺調用 api，使用 code 換取 openid 和 session_key 等信息 |
| errMsg | String | 調用結果 |
| userInfo | OBJECT | 用戶信息對象，不包含 openid 等敏感信息 |
| rawData | String | 不包括敏感信息的原始數(shù)據字符串，用于計算簽名。 |
| signature | String | 使用 sha1( rawData + sessionkey ) 得到字符串，用于校驗用戶信息，參考文檔 signature。 |
| encryptedData | String | 包括敏感數(shù)據在內的完整用戶信息的加密數(shù)據，詳細見加密數(shù)據解密算法 |
| iv | String | 加密算法的初始向量，詳細見加密數(shù)據解密算法 |
userInfo參數(shù)說明：
| 參數(shù) | 類型 | 說明 |
|---|---|---|
| nickName | String | 用戶昵稱 |
| avatarUrl | String | 用戶頭像，最后一個數(shù)值代表正方形頭像大?。ㄓ?、46、64、96、132數(shù)值可選，0代表132*132正方形頭像），用戶沒有頭像時該項為空。若用戶更換頭像，原有頭像URL將失效。 |
| gender | String | 用戶的性別，值為1時是男性，值為2時是女性，值為0時是未知 |
| city | String | 用戶所在城市 |
| province | String | 用戶所在省份 |
| country | String | 用戶所在國家 |
| language | String | 用戶的語言，簡體中文為zh_CN |
代碼示例：
// plugin/components/hello-component.js
Component({
properties: {},
data: {
args: {
withCredentials: true,
lang: 'zh_CN'
}
},
methods: {
loginSuccess: function (res) {
console.log(res.detail);
},
loginFail: function (res) {
console.log(res);
}
}
});
用戶點擊該 navigator 后，將跳轉到如下的用戶信息功能頁：
在微信開發(fā)者工具中查看示例：
- 由于插件需要 appid 才能工作，請?zhí)钊胍粋€ appid；
- 由于當前代碼片段的限制，打開該示例后請 手動將 appid 填寫到 miniprogram/app.json 中（如下圖）使示例正常運行。
支付功能頁
支付功能頁用于幫助插件完成支付，相當于 wx.requestPayment 的功能。
需要注意的是：插件使用支付功能，需要進行額外的權限申請，申請位置位于管理后臺的“小程序插件 -> 基本設置 -> 支付能力”設置項中。另外，無論是否通過申請，主體為個人小程序在使用插件時，都無法正常使用插件里的支付功能。
調用參數(shù)
支付功能頁使用 functional-page-navigator 進行跳轉時，對應的參數(shù) name 應為固定值 requestPayment，其他參數(shù)如下：
args參數(shù)說明：
| 參數(shù)名 | 類型 | 必填 | 說明 |
|---|---|---|---|
| fee | Number | 是 | 需要顯示在頁面中的金額，單位為分 |
| paymentArgs | Object | 否 | 任意數(shù)據，傳遞給功能頁中的響應函數(shù) |
| currencyType | String | 否 | 需要顯示在頁面中的貨幣符號的代碼，默認為 CNY |
currencyType 的合法值：
| 值 | 說明 | 最低版本 |
|---|---|---|
| CNY | 貨幣符號 ￥ | |
| USD | 貨幣符號 US$ | |
| JPY | 貨幣符號 J￥ | |
| EUR | 貨幣符號 € | |
| HKD | 貨幣符號 HK$ | |
| GBP | 貨幣符號 ￡ | |
| AUD | 貨幣符號 A$ | |
| MOP | 貨幣符號 MOP$ | |
| KRW | 貨幣符號 ? |
代碼示例：
// plugin/components/pay.js
Component({
data: {
args: {
fee: 1, // 支付金額，單位為分
paymentArgs: 'A', // 將傳遞到功能頁函數(shù)的自定義參數(shù)
currencyType: 'USD' // 貨幣符號，頁面顯示貨幣簡寫 US$
}
},
methods: {
// 支付成功的回調接口
paymentSuccess: function (e) {
console.log(e);
e.detail.extraData.timeStamp // 用 extraData 傳遞數(shù)據，詳見下面功能頁函數(shù)代碼
},
// 支付失敗的回調接口
paymentFailed: function (e) {
console.log(e);
}
}
})
用戶點擊該 navigator 后，將跳轉到如下的支付功能頁：
配置功能頁函數(shù)
支付功能頁需要插件開發(fā)者在插件所有者小程序中提供一個函數(shù)來響應插件中的支付調用。即，在插件中跳轉到支付功能頁時，這個函數(shù)就會在合適的時機被調用，來幫助完成支付。如果不提供功能頁函數(shù)，功能頁調用將通過 fail 事件返回失敗。
支付功能頁函數(shù)應以導出函數(shù)的形式提供在插件所有者小程序的根目錄下的 functional-pages/request-payment.js 文件中，名為 beforeRequestPayment。該函數(shù)應接收兩個參數(shù)：
| 參數(shù)名 | 類型 | 說明 |
|---|---|---|
| paymentArgs | Object | 即通過 functional-page-navigator 的 arg 參數(shù)中的 paymentArgs 字段傳遞到功能頁的自定義數(shù)據 |
| callback | Function | 回調函數(shù)，調用該函數(shù)后，小程序將發(fā)起支付（類似于 wx.requestPayment） |
callback函數(shù)的參數(shù)：
| 參數(shù)名 | 類型 | 說明 |
|---|---|---|
| error | Object | 失敗信息，若無失敗，應返回 null |
| requestPaymentArgs | Object | 支付參數(shù)，用于調用 wx.requestPayment，參數(shù)如下 |
reqeustPaymentArgs 的參數(shù)：
用于發(fā)起支付，和 wx.requestPayment 的參數(shù)相同，但沒有回調函數(shù)（success, fail, complete）：
| 參數(shù) | 類型 | 必填 | 說明 |
|---|---|---|---|
| timeStamp | String | 是 | 時間戳從1970年1月1日00:00:00至今的秒數(shù),即當前的時間 |
| nonceStr | String | 是 | 隨機字符串，長度為32個字符以下。 |
| package | String | 是 | 統(tǒng)一下單接口返回的 prepay_id 參數(shù)值，提交格式如：prepay_id=*** |
| signType | String | 是 | 簽名算法，暫支持 MD5 |
| paySign | String | 是 | 簽名,具體簽名方案參見小程序支付接口文檔; |
| extraData | any | 否 | 由開發(fā)者決定的自定義數(shù)據段，該字段將被無修改地透傳到支付成功的回調參數(shù)中，具體見代碼示例中的使用方法?；A庫 2.9.1 開始支持 |
了解更多信息，請查看微信支付接口文檔
功能頁函數(shù)代碼示例：
// functional-pages/request-payment.js
exports.beforeRequestPayment = function (paymentArgs, callback) {
// 注意：
// 功能頁函數(shù)（這個函數(shù)）不應 require 其他非 functional-pages 目錄中的文件，
// 其他非 functional-pages 目錄中的文件也不應 require 這個目錄中的文件，
// 這樣的 require 調用在未來將不被支持。
//
// 同在 functional-pages 中的文件可以 require
var getOpenIdURL = require('./URL').getOpenIdURL;
var paymentURL = require('./URL').paymentURL;
// 自定義的參數(shù)，此處應為從插件傳遞過來的 'A'
var customArgument = paymentArgs.customArgument;
// 第一步：調用 wx.login 方法獲取 code，然后在服務端調用微信接口使用 code 換取下單用戶的 openId
// 具體文檔參考 https://mp.weixin.qq.com/debug/wxadoc/dev/api/api-login.html?t=20161230#wxloginobject
wx.login({
success: function (data) {
wx.request({
url: getOpenIdURL,
data: { code: data.code },
success: function (res) {
// 拉取用戶 openid 成功
// 第二步：在服務端調用支付統(tǒng)一下單，返回支付參數(shù)。這里的開發(fā)和普通的 wx.requestPayment 相同
// 文檔可以參考 https://pay.weixin.qq.com/wiki/doc/api/wxa/wxa_api.php?chapter=7_4&index=3
wx.request({
url: paymentURL,
data: { openid: res.data.openid },
method: 'POST',
success: function (res) {
console.log('unified order success, response is:', res);
var payargs = res.data.payargs;
// 第三步：調用回調函數(shù) callback 進行支付
// 在 callback 中需要返回兩個參數(shù)： err 和 requestPaymentArgs：
// err 應為 null （或者一些失敗信息）；
// requestPaymentArgs 將被用于調用 wx.requestPayment，除了 success/fail/complete 不被支持外，
// 應與 wx.requestPayment 參數(shù)相同。
var error = null;
var requestPaymentArgs = {
timeStamp: payargs.timeStamp,
nonceStr: payargs.nonceStr,
package: payargs.package,
signType: payargs.signType,
paySign: payargs.paySign,
extraData: { // 用 extraData 傳遞自定義數(shù)據
timeStamp: payargs.timeStamp
},
};
callback(error, requestPaymentArgs);
}
});
},
fail: function (res) {
console.log('拉取用戶openid失敗，將無法正常使用開放接口等服務', res);
// callback 第一個參數(shù)為錯誤信息，返回錯誤信息
callback(res);
}
});
},
fail: function (err) {
console.log('wx.login 接口調用失敗，將無法正常使用開放接口等服務', err)
// callback 第一個參數(shù)為錯誤信息，返回錯誤信息
callback(err);
}
});
}
注意：功能頁函數(shù)不應 require 其他非 functional-pages 目錄中的文件，其他非 functional-pages 目錄中的文件也不應 require 這個目錄中的文件。這樣的 require 調用在未來將不被支持。
這個目錄和文件應當被放置在插件所有者小程序代碼中（而非插件代碼中），它是插件所有者小程序的一部分（而非插件的一部分）。 如果需要新增或更改這段代碼，需要發(fā)布插件所有者小程序，才能在正式版中生效；需要重新預覽插件所有者小程序，才能在開發(fā)版中生效。
收貨地址功能頁
收貨地址功能頁用于展示用戶的收貨地址列表，用戶可以選擇其中的收貨地址。自基礎庫版本 2.4.0 開始支持。
調用參數(shù)
用戶信息功能頁使用 functional-page-navigator 進行跳轉時，對應的參數(shù) name 應為固定值 chooseAddress ，返回參數(shù)與 wx.chooseAddress 相同。
bindsuccess返回參數(shù)說明：
| 屬性 | 類型 | 說明 | 最低版本 |
|---|---|---|---|
| userName | string | 收貨人姓名 | |
| postalCode | string | 郵編 | |
| provinceName | string | 國標收貨地址第一級地址 | |
| cityName | string | 國標收貨地址第一級地址 | |
| countyName | string | 國標收貨地址第一級地址 | |
| detailInfo | string | 詳細收貨地址信息 | |
| nationalCode | string | 收貨地址國家碼 | |
| telNumber | string | 收貨人手機號碼 | |
| errMsg | string | 錯誤信息 |
代碼示例：
// plugin/components/hello-component.js
Component({
methods: {
onSuccess: function (res) {
console.log(res.detail);
},
onFail: function (res) {
console.log(res);
}
}
});
分享題目：創(chuàng)新互聯(lián)小程序教程：微信小程序插件功能頁
標題來源：http://www.5511xx.com/article/dhjgoch.html
