# 使用插件

# 添加插件

在使用插件前，首先要在小程序管理后臺首頁的“小程序信息設(shè)置頁-第三方設(shè)置-插件管理”中添加插件。開發(fā)者可登錄小程序管理后臺，通過 appid 查找插件并添加。如果插件無需申請，添加后可直接使用；否則需要申請并等待插件開發(fā)者通過后，方可在小程序中使用相應(yīng)的插件。

# 引入插件代碼包

使用插件前，使用者要在 app.json 中聲明需要使用的插件，例如：

代碼示例：

{
  "plugins": {
    "myPlugin": {
      "version": "1.0.0",
      "provider": "wxidxxxxxxxxxxxxxxxx"
    }
  }
}

如上例所示， plugins 定義段中可以包含多個插件聲明，每個插件聲明以一個使用者自定義的插件引用名作為標(biāo)識，并指明插件的 appid 和需要使用的版本號。其中，引用名（如上例中的 myPlugin）由使用者自定義，無需和插件開發(fā)者保持一致或與開發(fā)者協(xié)調(diào)。在后續(xù)的插件使用中，該引用名將被用于表示該插件。

# 在分包內(nèi)引入插件代碼包

如果插件只在一個分包內(nèi)用到，可以將插件僅放在這個分包內(nèi)，例如：

{
  "subpackages": [
    {
      "root": "packageA",
      "pages": [
        "pages/cat",
        "pages/dog"
      ],
      "plugins": {
        "myPlugin": {
          "version": "1.0.0",
          "provider": "wxidxxxxxxxxxxxxxxxx"
        }
      }
    }
  ]
}

在分包內(nèi)使用插件有如下限制：

• 默認(rèn)情況下，僅能在這個分包內(nèi)使用該插件，除非通過 分包異步化 進(jìn)行異步的跨分包引用；
• 同一個插件不能被多個分包同時引用；
• 如果基礎(chǔ)庫版本低于 2.9.0 ，不能從分包外的頁面直接跳入分包內(nèi)的插件頁面，需要先跳入分包內(nèi)的非插件頁面、再跳入同一分包內(nèi)的插件頁面。

# 使用插件

使用插件時，插件的代碼對于使用者來說是不可見的。為了正確使用插件，使用者應(yīng)查看插件詳情頁面中的“開發(fā)文檔”一節(jié)，閱讀由插件開發(fā)者提供的插件開發(fā)文檔，通過文檔來明確插件提供的自定義組件、頁面名稱及提供的 js 接口規(guī)范等。

# 自定義組件

使用插件提供的自定義組件，和 使用普通自定義組件 的方式相仿。在 json 文件定義需要引入的自定義組件時，使用 plugin:// 協(xié)議指明插件的引用名和自定義組件名，例如：

代碼示例：

{
  "usingComponents": {
    "hello-component": "plugin://myPlugin/hello-component"
  }
}

出于對插件的保護(hù)，插件提供的自定義組件在使用上有一定的限制：

• 默認(rèn)情況下，小程序和其他插件的 this.selectComponent 接口無法獲得插件的自定義組件實(shí)例對象，同樣插件的 this.selectComponent 也無法獲得小程序和其他插件的；
  • 這個限制可以通過 自定義的組件實(shí)例獲取結(jié)果 來去除
• wx.createSelectorQuery 等接口的 >>> 選擇器無法選入插件內(nèi)部。

# 頁面

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

需要跳轉(zhuǎn)到插件頁面時，url 使用 plugin:// 前綴，形如 plugin://PLUGIN_NAME/PLUGIN_PAGE， 如：

代碼示例：

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

# js 接口

使用插件的 js 接口時，可以使用 requirePlugin 方法。例如，插件提供一個名為 hello 的方法和一個名為 world 的變量，則可以像下面這樣調(diào)用：

var myPluginInterface = requirePlugin('myPlugin');

myPluginInterface.hello();
var myWorld = myPluginInterface.world;

基礎(chǔ)庫 2.14.0 起，也可以通過插件的 AppID 來獲取接口，如：

var myPluginInterface = requirePlugin('wxidxxxxxxxxxxxxxxxx');

# 導(dǎo)出到插件

在開發(fā)者工具中預(yù)覽效果，需要手動填寫一下 miniprogram/app.json 中的插件 AppID

從基礎(chǔ)庫 2.11.1 起，使用插件的小程序可以導(dǎo)出一些內(nèi)容，供插件獲取。具體來說，在聲明使用插件時，可以通過 export 字段來指定一個文件，如：

{
  "myPlugin": {
    "version": "1.0.0",
    "provider": "wxidxxxxxxxxxxxxxxxx",
    "export": "index.js"
  }
}

則該文件（上面的例子里是 index.js）導(dǎo)出的內(nèi)容可以被這個插件用全局函數(shù)獲得。例如，在上面的文件中，使用插件的小程序做了如下導(dǎo)出：

// index.js
module.exports = { whoami: 'Wechat MiniProgram' }

那么插件就可以獲得上面導(dǎo)出的內(nèi)容：

// plugin
requireMiniProgram().whoami // 'Wechat MiniProgram'

具體導(dǎo)出什么內(nèi)容，可以閱讀插件開發(fā)文檔，和插件的開發(fā)者做好約定。

當(dāng)插件在分包中時，這個特性也可以使用，但指定的文件的路徑是相對于分包的。例如在 root: packageA 的分包中指定了 export: exports/plugin.js，那么被指定的文件在文件系統(tǒng)上應(yīng)該是 /packageA/exports/plugin.js。

使用的多個插件的導(dǎo)出互不影響，兩個插件可以導(dǎo)出同一個文件，也可以是不同的文件。但導(dǎo)出同一個文件時，如果一個插件對導(dǎo)出內(nèi)容做了修改，那么另一個插件也會被影響，請注意這一點(diǎn)。

請謹(jǐn)慎導(dǎo)出 wx 對象或某個具體的 wx API，這將使插件可以以使用者小程序的身份調(diào)用 API。

另外也可以 # 為插件提供自定義組件

在開發(fā)者工具中預(yù)覽效果，需要手動填寫一下 miniprogram/app.json 中的插件 AppID

有時，插件可能會在頁面或者自定義組件中，將一部分區(qū)域交給使用的小程序來渲染，因此需要使用的小程序提供一個自定義組件。但由于插件中不能直接指定小程序的自定義組件路徑，因此需要通過為插件指定 抽象節(jié)點(diǎn)（generics） 的方式來提供。

如果是插件的自定義組件需要指定抽象節(jié)點(diǎn)實(shí)現(xiàn)，可以在引用時指定：

<!-- miniprogram/page/index.wxml -->
<plugin-view generic:mp-view="comp-from-miniprogram" />

從基礎(chǔ)庫 2.12.2 起，可以通過配置項(xiàng)為插件頁面指定抽象組件實(shí)現(xiàn)。例如，要給插件名為 plugin-index 的頁面中的抽象節(jié)點(diǎn) mp-view 指定小程序的自定義組件 components/comp-from-miniprogram 作為實(shí)現(xiàn)的話：

{
  "myPlugin": {
    "provider": "wxAPPID",
    "version": "1.0.0",
    "genericsImplementation": {
      "plugin-index": {
        "mp-view": "components/comp-from-miniprogram"
      }
    }
  }
}

另外也可以 參考開發(fā)插件的相關(guān)文檔