|
| 1 | +# Plugins |
| 2 | + |
| 3 | +Plugins usually add global-level functionality to Vue. There is no strictly defined scope for a plugin, but common scenarios where plugins are useful include: |
| 4 | + |
| 5 | +1. Add some global methods or properties, e.g. [vue-custom-element](https://github.com/karol-f/vue-custom-element). |
| 6 | + |
| 7 | +2. Add one or more global assets: directives/filters/transitions etc. (e.g. [vue-touch](https://github.com/vuejs/vue-touch)). |
| 8 | + |
| 9 | +3. Add some component options by global mixin (e.g. [vue-router](https://github.com/vuejs/vue-router)). |
| 10 | + |
| 11 | +4. Add some Vue instance methods by attaching them to `config.globalProperties`. |
| 12 | + |
| 13 | +5. A library that provides an API of its own, while at the same time injecting some combination of the above (e.g. [vue-router](https://github.com/vuejs/vue-router)). |
| 14 | + |
| 15 | +## Using a Plugin |
| 16 | + |
| 17 | +After a Vue app has been initialized with `createApp()`, you can add a plugin to your application by calling the `use()` method: |
| 18 | + |
| 19 | +```js |
| 20 | +// calls `MyPlugin.install(Vue)` |
| 21 | +const app = Vue.createApp({}) |
| 22 | +app.use(MyPlugin) |
| 23 | +``` |
| 24 | + |
| 25 | +If you need to define configuration for a plugin, you can pass a config object as the second argument: |
| 26 | + |
| 27 | +```js |
| 28 | +app.use(MyPlugin, { someOption: true }) |
| 29 | +``` |
| 30 | + |
| 31 | +`app.use()` automatically prevents you from using the same plugin more than once, so calling it multiple times on the same plugin will install the plugin only once. |
| 32 | + |
| 33 | +Checkout [awesome-vue](https://github.com/vuejs/awesome-vue#components--libraries) for a huge collection of community-contributed plugins and libraries. |
| 34 | + |
| 35 | +## Writing a Plugin |
| 36 | + |
| 37 | +A Vue.js plugin should expose an `install()` method. The method will be called with the application instance as the first argument, along with possible options: |
| 38 | + |
| 39 | +```js |
| 40 | +MyPlugin.install = (app, options) => { |
| 41 | + // 1. add a global provided function/attribute (this would require using an 'inject' in components where we want to access 'myProvidedAttribute') |
| 42 | + app.provide('myProvidedAttribute', 'foo') |
| 43 | + |
| 44 | + // 2. add an instance method (this will be available in every component) |
| 45 | + app.config.globalProperties.$myMethod = (methodOptions) => { |
| 46 | + // some logic ... |
| 47 | + } |
| 48 | + |
| 49 | + // 3. add a global asset |
| 50 | + app.directive('my-directive', { |
| 51 | + bind (el, binding, vnode, oldVnode) { |
| 52 | + // some logic ... |
| 53 | + } |
| 54 | + ... |
| 55 | + }) |
| 56 | + |
| 57 | + // 4. inject some component options |
| 58 | + app.mixin({ |
| 59 | + created() { |
| 60 | + // some logic ... |
| 61 | + } |
| 62 | + ... |
| 63 | + }) |
| 64 | +} |
| 65 | +``` |
0 commit comments