微信小程序 插件功能頁

插件功能頁

插件功能頁從小程序基礎(chǔ)庫版本 2.1.0 開始支持。

某些接口不能在插件中直接調(diào)用（如 wx.login），但插件開發(fā)者可以使用插件功能頁的方式來實現(xiàn)功能。目前，插件功能頁包括：

• 獲取用戶信息，包括 openid 和昵稱等（相當于 wx.login 和 wx.getUserInfo 的功能），詳見用戶信息功能頁；
• 支付（相當于 wx.requestPayment），詳見支付功能頁；
• 獲取收貨地址（相當于 wx.chooseAddress），詳見收貨地址功能頁。

要使用插件功能頁，需要先激活功能頁特性，配置對應(yīng)的功能頁函數(shù)，再使用 functional-page-navigator 組件跳轉(zhuǎn)到插件功能頁，從而實現(xiàn)對應(yīng)的功能。詳情請參考下文。

插件所有者小程序

開始開發(fā)之前，我們需要知道，插件功能頁是指 插件所有者小程序 中的一個特殊頁面。

插件所有者小程序，指的是與插件 AppID 相同的小程序。例如，“小程序示例”小程序開發(fā)了一個“小程序示例插件”，那么無論這個插件被哪個小程序使用，這個插件的 插件所有者小程序 都是“小程序示例”。下文中會繼續(xù)使用 插件所有者小程序 這個說法。

插件所有者小程序開發(fā)方法

通常，在開始使用插件功能頁的時候，需要開啟兩個開發(fā)者工具窗口，其中一個打開插件項目，另一個打開插件所有者小程序的小程序項目。例如，一個打開“小程序示例插件”項目，另一個打開“小程序示例”項目。

這兩個窗口，前者用于編輯插件，后者用于編輯插件所有者小程序。下文中所有需要編輯插件所有者小程序的內(nèi)容，都是在后者中進行。

激活功能頁特性

要在插件中調(diào)用插件功能頁，需要先激活插件所有者小程序的功能頁特性。具體來說，在插件所有者小程序的 app.json 文件中添加 functionalPages 定義段，并令其值為 true ，例如：

代碼示例：

{
  "functionalPages": {
    "independent": true
  }
}

目前，兼容舊式寫法：

{
  "functionalPages": true
}

舊式寫法將在未來將被移除支持，未來將不能編譯上傳。

這兩種寫法的區(qū)別在于，新式的寫法 "independent": true 會使得插件功能頁的代碼獨立于其他代碼，這意味著插件功能頁可以被獨立下載、加載，具有更好的性能表現(xiàn)。 但也同時使得插件功能頁目錄 functional-pages/ （支付功能頁會使用其中的文件）不能 require 這個目錄以外的文件（反之亦然：這個目錄以外的文件也不能調(diào)用這個目錄內(nèi)的）。

注意，新增或改變這個字段時，需要這個小程序發(fā)布新版本，才能在正式環(huán)境中使用插件功能頁。

跳轉(zhuǎn)到功能頁

功能頁不能使用 wx.navigateTo 來進行跳轉(zhuǎn)，而是需要一個名為 functional-page-navigator 的組件。以獲取用戶信息為例，可以在插件中放置如下的 functional-page-navigator：

代碼示例：

<functional-page-navigator name="loginAndGetUserInfo" args="" version="develop" bind:success="loginSuccess">
  <button>登錄到插件</button>
</functional-page-navigator>

用戶在點擊這個 navigator 時，會自動跳轉(zhuǎn)到插件所有者小程序的對應(yīng)功能頁。功能頁會提示用戶進行登錄或其他相應(yīng)的操作。操作結(jié)果會以組件事件的方式返回。

functional-page-navigator 的參數(shù)和詳細使用方法可以參考組件說明 。

從小程序基礎(chǔ)庫版本 2.4.0 開始，支持插件所有者小程序跳轉(zhuǎn)到自己的功能頁。在基礎(chǔ)庫版本低于 2.4.0 時，點擊跳轉(zhuǎn)到自己的功能頁的 functional-page-navigator 將沒有任何反應(yīng)。

真機開發(fā)測試的常規(guī)步驟

目前，功能頁的跳轉(zhuǎn)目前不支持在開發(fā)者工具中調(diào)試，請在真機上測試。初次進行真機開發(fā)測試時，通常步驟如下：

1. 在開發(fā)者工具上打開插件所有者小程序項目，并點擊“預覽”；
2. 用測試用的真機掃一下預覽二維碼，此時會進入插件所有者小程序，進入后就可以直接退出這個小程序；
3. 在開發(fā)者工具上打開插件項目，將插件中 functional-page-navigator 中的 version 屬性設(shè)置為 develop；
4. 點擊預覽可以生成插件預覽二維碼，用測試用的真機掃碼即可預覽功能頁；如果更改了插件代碼，重新生成并掃描插件的預覽二維碼即可；
5. 如果過了一段時間之后，跳轉(zhuǎn)功能頁時出現(xiàn)“開發(fā)版已過期”這樣的提示，從第1步開始重試一次。

注意：functional-page-navigator 的 version=develop 僅用于調(diào)試，因此在插件提審前，需要：

1. 確保已發(fā)布設(shè)置了 "functionalPages": true 的插件所有者小程序；
2. 確保所有的 functional-page-navigator 組件屬性設(shè)置為 version="release" 。

功能頁常見問題 FAQ

如何正確編輯插件所有者小程序？

• 應(yīng)該在開發(fā)者工具的“小程序”類型項目中編輯，而不是在“插件”類型的項目中編輯。比如，“小程序示例插件”的所有者小程序是“小程序示例”，它們的 AppID 都是 wxidxxxxxxxxxxxxxx ，如果是初次開發(fā)“小程序示例”小程序，可以在開發(fā)者工具中創(chuàng)建一個小程序項目，其 AppID 為 wxidxxxxxxxxxxxxxx ；如果之前開發(fā)過“小程序示例”小程序，直接打開之前的小程序項目即可。

點擊 functional-page-navigator 之后沒有任何反應(yīng)。

• 請檢查引用插件的小程序和插件本身是不是同一個 AppID ，如果是，跳轉(zhuǎn)到自己的功能頁需要基礎(chǔ)庫 2.4.0 支持，否則使用 functional-page-navigator 不會有任何反應(yīng)。

點擊 functional-page-navigator 之后，展示了一個頁面提示“頁面不存在”。

• 這種情況是因為插件所有者小程序沒有正確設(shè)置 "functionalPages": true 。如果 functional-page-navigator 的 version="develop" ，這部手機需要掃碼并進入插件所有者小程序一次；如果 version="release" ，請確保包含 "functionalPages": true 的插件所有者小程序已被發(fā)布。

點擊 <functional-page-navigator version="develop"> 之后，彈窗提示“小程序開發(fā)版已過期”。

• 遇到這種情況，重新掃碼并進入插件所有者小程序一次即可。

點擊 <functional-page-navigator name="requestPayment"> 之后，展示了一個頁面提示“該功能無法使用”。

• 在使用插件功能頁時，小程序不能是個人小程序，同時，插件也需要額外的步驟申請開通插件支付權(quán)限（位于 管理后臺 -> 小程序插件 -> 基本設(shè)置 -> 支付能力 ）。

點擊 <functional-page-navigator name="requestPayment"> 之后，點擊頁面中的“支付”按鈕，立刻退出了支付功能頁。

• 這通常是因為沒有找到功能頁函數(shù) beforeRequestPayment ，請檢查插件所有者小程序的 functional-pages/request-payment.js 文件和其中的 beforeRequestPayment 函數(shù)是否存在。

點擊 functional-page-navigator 之后，展示了一個僅有返回按鈕的頁面。

• 請檢查 functional-page-navigator 的 name 屬性是否被正確設(shè)置。

開發(fā)版可以正常跳轉(zhuǎn)，但審核反饋不能跳轉(zhuǎn)。

• 請發(fā)布設(shè)置了 "functionalPages": true 的插件所有者小程序，且所有的 functional-page-navigator 組件屬性設(shè)置為 version="release" 。

Bugs & Tips

• 功能頁是插件所有者小程序中的一個特殊頁面，開發(fā)者不能自定義這個頁面的外觀。
• 插件所有者小程序本身也可以引用這個插件，此時，functional-page-navigator 組件的 version 屬性將不會生效，而是取決于當前運行的插件所有者小程序的版本。
• functional-page-navigator 可以在開發(fā)者工具中使用，但功能頁的跳轉(zhuǎn)目前不支持在開發(fā)者工具中調(diào)試，請在真機上測試。
• Bug：在微信版本 6.6.7 中，功能頁被拉起時會觸發(fā) App 的部分生命周期并使得功能頁啟動時間變得比較長。在后續(xù)的微信版本中這一行為會發(fā)生變更，使 App 生命周期不再被觸發(fā)。

用戶信息功能頁

用戶信息功能頁用于幫助插件獲取用戶信息，包括 openid 和昵稱等，相當于 wx.login 和 wx.getUserInfo 的功能。

此外，自基礎(chǔ)庫版本 2.3.1 起，用戶在這個功能頁中授權(quán)之后，插件就可以直接調(diào)用 wx.login 和 wx.getUserInfo 。無需再次進入功能頁獲取用戶信息。自基礎(chǔ)庫版本 2.6.3 起，可以使用 wx.getSetting 來查詢用戶是否授權(quán)過。

調(diào)用參數(shù)

用戶信息功能頁使用 functional-page-navigator 進行跳轉(zhuǎn)時，對應(yīng)的參數(shù) name 應(yīng)為固定值 loginAndGetUserInfo，其余參數(shù)與 wx.getUserInfo 相同，具體來說：

args參數(shù)說明：

注：當 withCredentials 為 true 時，返回的數(shù)據(jù)會包含 encryptedData, iv 等敏感信息。

bindsuccess返回參數(shù)說明：

userInfo參數(shù)說明：

代碼示例：

<!--plugin/components/hello-component.wxml-->
  <functional-page-navigator
    name="loginAndGetUserInfo"
    args="{{ args }}"
    version="develop"
    bind:success="loginSuccess"
    bind:fail="loginFail"
  >
    <button class="login">登錄到插件</button>
  </functional-page-navigator>

// 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 后，將跳轉(zhuǎn)到如下的用戶信息功能頁：

在微信開發(fā)者工具中查看示例：

1. 由于插件需要 appid 才能工作，請?zhí)钊胍粋€ appid；
2. 由于當前代碼片段的限制，打開該示例后請 手動將 appid 填寫到 miniprogram/app.json 中（如下圖）使示例正常運行。

支付功能頁

支付功能頁用于幫助插件完成支付，相當于 wx.requestPayment 的功能。

需要注意的是：插件使用支付功能，需要進行額外的權(quán)限申請，申請位置位于管理后臺的“小程序插件 -> 基本設(shè)置 -> 支付能力”設(shè)置項中。另外，無論是否通過申請，主體為個人小程序在使用插件時，都無法正常使用插件里的支付功能。

調(diào)用參數(shù)

支付功能頁使用 functional-page-navigator 進行跳轉(zhuǎn)時，對應(yīng)的參數(shù) name 應(yīng)為固定值 requestPayment，其他參數(shù)如下：

args參數(shù)說明：

currencyType 的合法值：

代碼示例：

<!-- plugin/components/pay.wxml -->
<!-- 上線時，version 應(yīng)改為 "release"，并確保插件所有者小程序已經(jīng)發(fā)布 -->
<functional-page-navigator
  version="develop"
  name="requestPayment"
  args="{{ args }}"
  bind:success="paymentSuccess"
  bind:fail="paymentFailed"
>
  <button class="payment-button">支付 0.01 元</button>
</functional-page-navigator>

// plugin/components/pay.js
Component({
  data: {
    args: {
      fee: 1,             // 支付金額，單位為分
      paymentArgs: 'A', // 將傳遞到功能頁函數(shù)的自定義參數(shù)
      currencyType: 'USD' // 貨幣符號，頁面顯示貨幣簡寫 US$ 
    }
  },
  methods: {
    // 支付成功的回調(diào)接口
    paymentSuccess: function (e) {
      console.log(e);
      e.detail.extraData.timeStamp // 用 extraData 傳遞數(shù)據(jù)，詳見下面功能頁函數(shù)代碼
    },
    // 支付失敗的回調(diào)接口
    paymentFailed: function (e) {
      console.log(e);
    }
  }
})

用戶點擊該 navigator 后，將跳轉(zhuǎn)到如下的支付功能頁：

配置功能頁函數(shù)

支付功能頁需要插件開發(fā)者在插件所有者小程序中提供一個函數(shù)來響應(yīng)插件中的支付調(diào)用。即，在插件中跳轉(zhuǎn)到支付功能頁時，這個函數(shù)就會在合適的時機被調(diào)用，來幫助完成支付。如果不提供功能頁函數(shù)，功能頁調(diào)用將通過 fail 事件返回失敗。

支付功能頁函數(shù)應(yīng)以導出函數(shù)的形式提供在插件所有者小程序的根目錄下的 functional-pages/request-payment.js 文件中，名為 beforeRequestPayment。該函數(shù)應(yīng)接收兩個參數(shù)：

callback函數(shù)的參數(shù)：

reqeustPaymentArgs 的參數(shù)：

用于發(fā)起支付，和 wx.requestPayment 的參數(shù)相同，但沒有回調(diào)函數(shù)（success, fail, complete）：

了解更多信息，請查看微信支付接口文檔

功能頁函數(shù)代碼示例：

// functional-pages/request-payment.js
exports.beforeRequestPayment = function (paymentArgs, callback) {
  // 注意：
  // 功能頁函數(shù)（這個函數(shù)）不應(yīng) require 其他非 functional-pages 目錄中的文件，
  // 其他非 functional-pages 目錄中的文件也不應(yīng) require 這個目錄中的文件，
  // 這樣的 require 調(diào)用在未來將不被支持。
  //
  // 同在 functional-pages 中的文件可以 require
  var getOpenIdURL = require('./URL').getOpenIdURL;
  var paymentURL = require('./URL').paymentURL;

  // 自定義的參數(shù)，此處應(yīng)為從插件傳遞過來的 'A'
  var customArgument = paymentArgs.customArgument;

  // 第一步：調(diào)用 wx.login 方法獲取 code，然后在服務(wù)端調(diào)用微信接口使用 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 成功
          // 第二步：在服務(wù)端調(diào)用支付統(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;
              // 第三步：調(diào)用回調(diào)函數(shù) callback 進行支付
              // 在 callback 中需要返回兩個參數(shù)： err 和 requestPaymentArgs：
              // err 應(yīng)為 null （或者一些失敗信息）；
              // requestPaymentArgs 將被用于調(diào)用 wx.requestPayment，除了 success/fail/complete 不被支持外，
              // 應(yīng)與 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ù)據(jù)
                  timeStamp: payargs.timeStamp
                },
              };
              callback(error, requestPaymentArgs);
            }
          });
        },
        fail: function (res) {
          console.log('拉取用戶openid失敗，將無法正常使用開放接口等服務(wù)', res);
          // callback 第一個參數(shù)為錯誤信息，返回錯誤信息
          callback(res);
        }
      });
    },
    fail: function (err) {
      console.log('wx.login 接口調(diào)用失敗，將無法正常使用開放接口等服務(wù)', err)
      // callback 第一個參數(shù)為錯誤信息，返回錯誤信息
      callback(err);
    }
  });
}

注意：功能頁函數(shù)不應(yīng) require 其他非 functional-pages 目錄中的文件，其他非 functional-pages 目錄中的文件也不應(yīng) require 這個目錄中的文件。這樣的 require 調(diào)用在未來將不被支持。

這個目錄和文件應(yīng)當被放置在插件所有者小程序代碼中（而非插件代碼中），它是插件所有者小程序的一部分（而非插件的一部分）。 如果需要新增或更改這段代碼，需要發(fā)布插件所有者小程序，才能在正式版中生效；需要重新預覽插件所有者小程序，才能在開發(fā)版中生效。

收貨地址功能頁

收貨地址功能頁用于展示用戶的收貨地址列表，用戶可以選擇其中的收貨地址。自基礎(chǔ)庫版本 2.4.0 開始支持。

調(diào)用參數(shù)

用戶信息功能頁使用 functional-page-navigator 進行跳轉(zhuǎn)時，對應(yīng)的參數(shù) name 應(yīng)為固定值 chooseAddress ，返回參數(shù)與 wx.chooseAddress 相同。

bindsuccess返回參數(shù)說明：

代碼示例：

<!--plugin/components/hello-component.wxml-->
  <functional-page-navigator
    name="chooseAddress"
    version="develop"
    bind:success="onSuccess"
    bind:fail="onFail"
  >
    <button>選擇收貨地址</button>
  </functional-page-navigator>

// plugin/components/hello-component.js
Component({
  methods: {
    onSuccess: function (res) {
      console.log(res.detail);
    },
    onFail: function (res) {
      console.log(res);
    }
  }
});