QQ小程序 開發(fā)插件

開發(fā)插件前，請(qǐng)發(fā)郵件至 qq-miniprogram@tencent.com 申請(qǐng)插件開發(fā)權(quán)限，郵件內(nèi)容包括：

【標(biāo)題】QQ小程序插件開發(fā)申請(qǐng)
【內(nèi)容】
插件名稱：
Appid：
插件用途：

創(chuàng)建插件項(xiàng)目

開發(fā)小程序插件需要一個(gè)appid，申請(qǐng)步驟同小程序一致，添加項(xiàng)目的步驟也與小程序一致。 小程序插件目錄一般包括以下三個(gè)：

• miniprogram 目錄： 放置一個(gè)小程序項(xiàng)目，用于調(diào)試插件
• plugin 目錄： 插件源碼
• doc 目錄： 用于放置插件開發(fā)文檔
• miniprogram 目錄內(nèi)容可以當(dāng)成普通小程序來編寫，用于小程序插件調(diào)試和預(yù)覽。

插件目錄結(jié)構(gòu)

一個(gè)插件可以包含若干個(gè)自定義組件、頁面，和一組 js 接口。插件的目錄內(nèi)容如下：

plugin
├── components
│   ├── hello-component.js   // 插件提供的自定義組件（可以有多個(gè)）
│   ├── hello-component.json
│   ├── hello-component.wxml
│   └── hello-component.wxss
├── pages
│   ├── hello-page.js        // 插件提供的頁面（可以有多個(gè)）
│   ├── hello-page.json
│   ├── hello-page.wxml
│   └── hello-page.wxss
├── index.js                 // 插件的 js 接口
└── plugin.json              // 插件配置文件
插件配置文件

插件配置文件

向第三方小程序開放的所有自定義組件、頁面和 js 接口都必須在插件配置文件 plugin.json 列出，格式如下：

{
  "publicComponents": {
    "hello-component": "components/hello-component"
  },
  "pages": {
    "hello-page": "pages/hello-page"
  },
  "main": "index.js"
}

這個(gè)配置文件將向第三方小程序開放一個(gè)自定義組件 hello-component，一個(gè)頁面 hello-page 和 index.js 下導(dǎo)出的所有 js 接口。

進(jìn)行插件開發(fā)

請(qǐng)注意：在插件開發(fā)中，只有部分接口可以直接調(diào)用。

自定義組件

插件可以定義若干個(gè)自定義組件，這些自定義組件都可以在插件內(nèi)相互引用。但提供給第三方小程序使用的自定義組件必須在配置文件的 publicComponents 段中列出（參考上文）。

除去接口限制以外，自定義組件的編寫和組織方式與一般的自定義組件相同，每個(gè)自定義組件由 wxml, wxss, js 和 json 四個(gè)文件組成。具體可以參考自定義組件的文檔。

頁面 插件可以定義若干個(gè)插件頁面，可以從本插件的自定義組件、其他頁面中跳轉(zhuǎn)，或從第三方小程序中跳轉(zhuǎn)。所有頁面必須在配置文件的 pages 段中列出（參考上文）。 除去接口限制以外，插件的頁面編寫和組織方式與一般的頁面相同，每個(gè)頁面由 wxml, wxss, js 和 json 四個(gè)文件組成。具體可以參考其他關(guān)于頁面的文檔。 插件執(zhí)行頁面跳轉(zhuǎn)的時(shí)候，可以使用 navigator 組件。當(dāng)插件跳轉(zhuǎn)到自身頁面時(shí)， url 應(yīng)設(shè)置為這樣的形式：plugin-private://PLUGIN_APPID/PATH/TO/PAGE。需要跳轉(zhuǎn)到其他插件時(shí)，也可以這樣設(shè)置 url 。

<navigator url="plugin-private://qqidxxxxxxxxxxxxxx/pages/hello-page">
  Go to pages/hello-page!
</navigator>

在插件自身的頁面中，插件還可以調(diào)用 qq.navigateTo 來進(jìn)行頁面跳轉(zhuǎn)， url 格式與使用 navigator 組件時(shí)相仿。

接口

插件可以在接口文件（在配置文件中指定，詳情見上文）中 export 一些 js 接口，供插件的使用者調(diào)用，如：

module.exports = {
  hello: function() {
    console.log('Hello plugin!')
  }
}

預(yù)覽、上傳和發(fā)布

插件可以像小程序一樣預(yù)覽和上傳，但插件沒有體驗(yàn)版。 插件會(huì)同時(shí)有多個(gè)線上版本，由使用插件的小程序決定具體使用的版本號(hào)。 手機(jī)預(yù)覽和提審插件時(shí)，會(huì)使用一個(gè)特殊的小程序來套用項(xiàng)目中 miniprogram 文件夾下的小程序，從而預(yù)覽插件。

插件開發(fā)文檔

在第三方小程序使用插件時(shí)，插件代碼并不可見。因此，除了插件代碼，我們還支持插件開發(fā)者上傳一份插件開發(fā)文檔。這份開發(fā)文檔將展示在插件詳情頁，供其他開發(fā)者在瀏覽插件和使用插件時(shí)進(jìn)行閱讀和參考。插件開發(fā)者應(yīng)在插件開發(fā)文檔中對(duì)插件提供的自定義組件、頁面、接口等進(jìn)行必要的描述和解釋，方便第三方小程序正確使用插件。 插件開發(fā)文檔必須放置在插件項(xiàng)目根目錄中的 doc 目錄下，目錄結(jié)構(gòu)如下

doc
├── README.md   // 插件文檔，應(yīng)為 markdown 格式

編輯 README.md 之后，可以使用開發(fā)者工具打開 README.md，并在編輯器的右下角預(yù)覽插件文檔和單獨(dú)上傳插件文檔。上傳文檔后，立刻發(fā)布。

其他注意事項(xiàng)

插件間互相調(diào)用

插件不能直接引用其他插件。但如果小程序引用了多個(gè)插件，插件之間是可以互相調(diào)用的。 一個(gè)插件調(diào)用另一個(gè)插件的方法，與插件調(diào)用自身的方法類似?？梢允褂?plugin-private://APPID 訪問插件的自定義組件、頁面（暫不能使用 plugin:// ）。對(duì)于 js 接口，可使用 requirePlugin 。

插件請(qǐng)求簽名

插件在使用 qq.request 等 API 發(fā)送網(wǎng)絡(luò)請(qǐng)求時(shí)，將會(huì)額外攜帶一個(gè)簽名 HostSign ，用于驗(yàn)證請(qǐng)求來源于小程序插件。這個(gè)簽名位于請(qǐng)求頭中，形如：

X-WECHAT-HOSTSIGN: {"noncestr":"NONCESTR", "timestamp":"TIMESTAMP", "signature":"SIGNATURE"}

其中，NONCESTR 是一個(gè)隨機(jī)字符串，TIMESTAMP 是生成這個(gè)隨機(jī)字符串和 SIGNATURE 的 UNIX 時(shí)間戳。它們是用于計(jì)算簽名 SIGNATRUE 的參數(shù)，簽名算法為：

SIGNATURE = sha1([APPID, NONCESTR, TIMESTAMP, TOKEN].sort().join(''))

其中，APPID 是 所在小程序 的 AppId（可以從請(qǐng)求頭的 referrer 中獲得）；TOKEN 是插件 Token，可以在小程序插件基本設(shè)置中找到。 網(wǎng)絡(luò)請(qǐng)求的 referer 格式固定為 https://appservice.qq.com/{appid}/{version}/page-frame.html，其中 {appid} 為小程序的 appid，{version} 為小程序的版本號(hào)，版本號(hào)為 0 表示為開發(fā)版、體驗(yàn)版以及審核版本，版本號(hào)為 devtools 表示為開發(fā)者工具，其余為正式版本。 插件開發(fā)者可以在服務(wù)器上按以下步驟校驗(yàn)簽名：

1. sort 對(duì) APPID NONCESTR TIMESTAMP TOKEN 四個(gè)值表示成字符串形式，按照字典序排序（同 JavaScript 數(shù)組的 sort 方法）；
2. join 將排好序的四個(gè)字符串直接連接在一起；
3. 對(duì)連接結(jié)果使用 sha1 算法，其結(jié)果即 SIGNATURE 。 在小程序運(yùn)行期間，若網(wǎng)絡(luò)狀況正常， NONCESTR 和 TIMESTAMP 會(huì)每 10 分鐘變更一次。如有必要，可以通過判斷 TIMESTAMP 來確定當(dāng)前簽名是否依舊有效。