# Development plug-in

Before you develop plugins, read about Mini Program plug-in access guide Understand the opening process and opening scope, and open plug-in functions. If the plugin function is not enabled, the plugin will not be uploaded.

# Creating a Plugin Project

Plug-in type projects can be created directly in Developer Tools.details

创建插件

After you create a new project of the plug-in type, if you create a sample project, the project will contain three directories:

plugin Directory: Plugin code directory.
miniprogram Directory: Place a Mini Program for debugging the plug-in.
doc Directory: Used to place plug-in development documentation.

miniprogram The contents of the directory can be written as ordinary Mini Programs for plug-in debugging, previewing, and auditing. The following content mainly introduces plugin The plugin code in the doc The plugin development documentation in the.

We have provided A complete plugin example that can be viewed directly in the Weixin DevToolsDevelopers can compare notes to understand. Please note:

Due to the need for plug-ins appid To work, please fill in a appid
Due to the limitations of the current code snippet, after you open the sample Manual will appid Fill in the miniprogram/app.json To make the example run properly in.

手动填写 appid

# Plugin directory structure

A plug-in can contain several custom components, pages, and a set of js Interface. The contents of the plugin's directory are as follows:

plugin
 components
    hello-component.js    // Custom components provided by the plug-in (you can have more than one)
    hello-component.json 
    hello-component.wxml 
    hello-component.wxss 
 pages
    hello-page.js        // Pages provided by the plug-in (there can be multiple, Mini Program base library versions 2.1.0 Start support)
    hello-page.json
    hello-page.wxml
    hello-page.wxss
 index.js                 // Plug-in js interface
 plugin.json              // Plugin Profile

# Plugin Profile

All custom components, pages, and files that are open to the user's Mini Programs js Interface must be in the plugin configuration file plugin.json Listed, in the following format:

Code example:

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

This configuration file will open a custom component to the user Mini Program Hello-component, A Page hello-page and index.js All exported under js Interface.

# For plug-in development

Please note: In plugin development, only the Partial interface Can be called directlyThere is also some capacity (such as Get User Information and Initiate payment Etc.) can be obtained by Plugin Function Page The manner used.

# Custom Components

A plug-in can define several custom components that can all refer to each other within the plug-in. However, the custom components provided for use by the user Mini Program must be specified in the publicComponents Paragraph listed (refer to above).

Except for interface limitations, custom components are written and organized in the same way as general custom components. Each custom component is composed of wxml, wxss, js and json It consists of four documents. Specific can refer to Documentation for custom components。

# page

Plug-in Mini Program base library version 2.1.0 Start the support page. A plug-in can define a number of plug-in pages that can jump from a custom component of the plug-in, other pages, or from a user Mini Program. All pages must be in the configuration file's pages Paragraph listed (refer to above).

With the exception of interface restrictions, plug-in pages are written and organized in the same way as regular pages, with each page consisting of wxml, wxss, js and json It consists of four documents. You can refer to other documents about the page.

When the plug-in performs a page jump, you can use the navigator Components. When the plugin jumps to its own page, url Should be set in the form of:plugin-private://PLUGIN_APPID/PATH/TO/PAGE You can also set this when you need to jump to another plugin url 。

Code example:

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

Self-base library version 2.2.2 To start, in the plug-in's own page, the plug-in can also call [wx.navigateTo ]((wx.navigateTo )) To make the page jump, url Format and use navigator Components are similar.

# interface

Plug-ins can be found in the interface file (specified in the configuration file, see above) export some js Interface that is invoked by the user of the plug-in, such as:

Code example:

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

# Get Mini Program Export

{% Minicode ('GbXmMLml7vjC') %}, need to be filled out manually miniprogram/app.json Plugins in AppID

From the base library 2.11.1 Up, there are global functions in the plug-in requireMiniProgramCan get the content exported by the user Mini Program.

For example, the user Mini Program makes the following export:

// User Mini Program
module.exports = {
  greeting() {
    return 'Greetings from Weixin MiniProgram!'
  }
}

Then in the plugin, you can get the content like this:

// plug-in
const miniProgramExports  = requireMiniProgram()
miniProgramExports.greeting() // 'Greetings from Weixin MiniProgram!'

It's also possible [Refer to the documentation for the user Mini Program](./using.md#Export to Plugins)

# Refer to the custom component of the Mini Program

{% Minicode ('QRRovLmu7Xjm') %}, need to be filled out manually miniprogram/app.json Plugins in AppID

Sometimes, plug-ins may need to render a portion of a page or custom component to the Mini Program they are using, so they need a custom component that can reference the Mini Program. However, because the custom component path of the Mini Program cannot be specified directly in the plug-in, it is not possible to directly pass through the usingComponents Way to quote. Introduced here through Abstract nodes (generics) To implement the reference.

If it is a plug-in custom component (for example plugin-view), then we can do so by declaring a generic：

// plugin/components/plugin-view.json
{ "componentGenerics": { "mp-view": true } }

And referenced where you want the Mini Program component to be displayed:

<!-- plugin/components/plugin-view.wxml -->
<view>Small Program Components:</view>
<mp-view /><!-- Here is a Mini Program custom component -->

Referenced in the Mini Program plugin-view You can pass the component to the plug-in for rendering:

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

If it is a plugin page, the plugin page itself is a page top level component. The Mini Program will not reference it and cannot pass generic:xxx="" To specify the abstract node implementation in theTherefore, from the base library 2.12.2 The Mini Program can specify an abstract node implementation for the plug-in page in the plug-in configuration. For example the plugin page is called plugin-index, you can:

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

It's also possible [Refer to the documentation for the user Mini Program](./using.md#Provide custom components for plug-ins)

# Preview, upload and publish

Plug-ins can be previewed and uploaded like Mini Programs, but there is no experience version of the plugin.

Plug-ins can have multiple online versions at the same time, and the specific version number is determined by the Mini Program using the plug-in.

Mobile phone preview and arraignment plug-in, will use a special Mini Program to apply the project miniprogram Folder under the Mini Program, thus previewing the plugin.

(the suggestion) if the current developer has Test number, will use this test numberIn the test number's settings page you can see the appid 、 appsecret And set up a list of domain names.
Otherwise, the "Plugin Development Assistant" is used, which has a specific appid 。

# Test in the development version of the Mini Program

Typically, you can place miniprogram Under the code as a plug-in Mini Program code, to debug and test plug-ins.

But sometimes, you need to put the plug-in code in the actual running Mini Program for debugging, testing. At this point, you can use the development version of the Mini Program directly reference the development version of the plug-in. The method is as follows:

Upload the plug-in in the Developer Tools plug-in project. At this point, the successful upload notification will contain the plug-in development version obtained by the upload. ID A random character string of English and numbers.
Click on the notification button in the lower right corner of the developer tools. You can open the notification bar and see the newly generated ID
In an Mini Program project that requires the development version of the plug-in, place the plug-in version Set to "version": "dev-[Development version ID]" The form, such as "version": "dev-abcdef0123456789abcdef0123456789" Just...

If the Development Version Mini Program refers to the Development Version plug-in, the Mini Program cannot be uploaded at this time. The plug-in version must be set to the official version before the Mini Program can be uploaded and released normally.

Notes:

Generated by each upload plugin ID Not necessarily the same. Even with the same plugin and the same developer, multiple uploads may change ID
Each developer will only have one active dev plugin in each plugin, i.e. only the latest uploaded dev plugin. ID Effective (using the old ID Will fail)
The development version uploaded by different developers of the same plugin does not affect each other and can be effective at the same time.
The development version of the plug-in has no time limit and is valid for a long time.

# Plugin Development Documentation

The plug-in code is not visible when the user Mini Program uses the plug-in. Therefore, in addition to the plugin code, we also support plugin developers to upload a plugin development document. This development document will be displayed on the plugin details page for other developers to read and refer to as they browse and use the plugin. Plug-in developers should provide the necessary description and explanation to the custom components, pages, interfaces, etc. provided by the plug-in in the plug-in development document, so as to facilitate the correct use of the plug-in by users.

The plug-in development document must be placed in the plug-in project root directory. doc Directory, the directory structure is as follows:

doc
 README.md   // The plug-in document should be markdown format
 picture.jpg // Other source files, images only

Among them,README.md The preparation has certain Restrictions, specifically:

The reference must not be a graph of a network and must be placed in this directory
Links in the document can only be linked to:
- WeChat developer community (developers.weixin.qq.com)
- WeChat Official Platform (mp.weixin.qq.com)
- GitHub（github.com）

edit README.md After that, you can right-click in the file bar of Explorer on the left side of Developer Tools README.md, and choose to upload the document. After posting the uploaded document, the document is not published immediately. You can login with your account and password at this time. Management background , In Mini Program plug-in > Basic settings Preview and publish plug-in documentation in.

The total plugin document size cannot be greater than 2M, the upload will return an error code when it exceeds 80051。

# Other considerations

# Calls between plug-ins

Plugins cannot directly reference other plugins. But if the Mini Program refers to multiple plug-ins, the plug-ins can call each other.

One plug-in calls another plug-in's methods, just as the plug-in calls its own methods. Can be used plugin-private://APPID Access the plug-in's custom components, pages (temporarily unavailable) plugin:// ）。

for js Interface, which can be used requirePlugin , but it is not yet possible to use it at the beginning of the document requirePlugin , because the dependent plugin may not have been initialized yet, consider calling it at a later time requirePlugin , such as when the interface is actually called, the component attached Time. (This will be fixed in the future. ）

# Plugin Request Signature

The plugin is using the wx.request etc. API When sending a network request, it will carry an additional signature HostSign , used to verify that the request originated from the Mini Program plug-in. This signature is located in the header of the request and looks like:

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

Among them, NONCESTR It's a random character string. TIMESTAMP Is to generate this random character string and SIGNATURE of UNIX Time stamp. They are used to calculate signatures SIGNATRUE The signature algorithm is:

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

Among them,APPID yes Where the Mini Program of AppId (which can be obtained from the request header's Referrer Obtained in)TOKEN Is a plugin Token, which can be found in the basic settings of the Mini Program plug-in.

Network Request Referer The format is fixed as https://servicewechat.com /{appid} /{version}/page-frame.html, which {appid} For the Mini Program. appid，{version} Is the version number of the Mini Program, which is 0 Represented as the Development, Experience, and Audit versions, the version number is Devtools Expressed as developer tools, the rest as official versions.

The plug-in developer can verify the signature on the server by following these steps:

sort Yes APPID NONCESTR TIMESTAMP TOKEN Is represented as a character string, lexicographically sorted the same JavaScript Array of sort Method)
Join Concatenate the four character strings in order directly
Use the connection result sha1 Algorithm, the result of which is SIGNATURE 。

Self-base library version 2.0.7 Start, during the operation of the Mini Program, if the network condition is normal, NONCESTR and TIMESTAMP Will each 10 Change every minute. If necessary, by judgment TIMESTAMP To determine if the current signature is still valid.