You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: src/guide/migration/global-api.md
+36-33Lines changed: 36 additions & 33 deletions
Original file line number
Diff line number
Diff line change
@@ -1,8 +1,8 @@
1
-
# Global API Changes
1
+
# Global API
2
2
3
3
Vue 2.x has a number of global APIs and configurations that globally mutate Vue’s behavior. For instance, to create a global component, you would use the `Vue.component` API like this:
Similarly, this is how a global directive is declared:
15
15
16
-
```js
16
+
```js
17
17
Vue.directive('focus', {
18
18
inserted:el=>el.focus()
19
19
})
20
20
```
21
21
22
22
While this approach is convenient, it leads to a couple of problems. Technically, Vue 2 doesn't have a concept of an "app". What we define as an app is simply a root Vue instance created via `new Vue()`. Every root instance created from the same Vue constructor **shares the same global configuration**. As a result:
23
23
24
-
* Global configuration makes it easy to accidentally pollute other test cases during testing. Users need to carefully store original global configuration and restore it after each test (e.g. resetting `Vue.config.errorHandler`). Some APIs like `Vue.use` and `Vue.mixin` don't even have a way to revert their effects. This makes tests involving plugins particularly tricky. In fact, vue-test-utils has to implement a special API `createLocalVue` to deal with this:
25
-
26
-
``` js
24
+
- Global configuration makes it easy to accidentally pollute other test cases during testing. Users need to carefully store original global configuration and restore it after each test (e.g. resetting `Vue.config.errorHandler`). Some APIs like `Vue.use` and `Vue.mixin` don't even have a way to revert their effects. This makes tests involving plugins particularly tricky. In fact, vue-test-utils has to implement a special API `createLocalVue` to deal with this:
25
+
26
+
``` js
27
+
27
28
import { createLocalVue, mount } from '@vue/test-utils'
28
-
29
+
29
30
// create an extended `Vue` constructor
30
31
const localVue = createLocalVue()
31
-
32
+
32
33
// install a plugin “globally” on the “local” Vue constructor
33
34
localVue.use(MyPlugin)
34
35
35
36
// pass the `localVue` to the mount options
36
37
mount(Component, { localVue })
37
-
```
38
+
```
38
39
39
-
* Global configuration makes it difficult to share the same copy of Vue between multiple "apps" on the same page, but with different global configurations.
40
+
- Global configuration makes it difficult to share the same copy of Vue between multiple "apps" on the same page, but with different global configurations.
40
41
41
42
```js
42
43
// this affects both root instances
43
-
Vue.mixin({ /* ... */ })
44
-
44
+
Vue.mixin({
45
+
/* ... */
46
+
})
47
+
45
48
const app1 = new Vue({ el: '#app-1' })
46
49
const app2 = new Vue({ el: '#app-2' })
47
50
```
48
51
49
-
To avoid these problems, in Vue 3 we introduce…
52
+
To avoid these problems, in Vue 3 we introduce…
50
53
51
54
## A New Global API: `createApp`
52
55
@@ -55,20 +58,20 @@ Calling `createApp` returns an _app instance_, a new concept in Vue 3.
55
58
```js
56
59
import { createApp } from'vue'
57
60
58
-
constapp=createApp()
61
+
constapp=createApp()
59
62
```
60
63
61
64
An app instance exposes a subset of the current global APIs. The rule of thumb is _any APIs that globally mutate Vue's behavior are now moved to the app instance_. Here is a table of the current global APIs and their corresponding instance APIs:
All other global APIs that do not globally mutate behavior are now named exports, as documented in [Global API Treeshaking](./treeshaking.html).
74
77
@@ -82,7 +85,7 @@ For ES modules builds, since they are used with bundlers, and in most cases a CL
82
85
83
86
This config option was introduced with the intention to support native custom elements, so the renaming better conveys what it does. The new option also expects a function which provides more flexibility than the old string / RegExp approach:
84
87
85
-
```js
88
+
```js
86
89
// before
87
90
Vue.config.ignoredElements= ['my-el',/^ion-/]
88
91
@@ -95,19 +98,19 @@ app.config.isCustomElement = tag => tag.startsWith('ion-')
95
98
96
99
In 3.0, the check of whether an element is a component or not has been moved to the template compilation phase, therefore this config option is only respected when using the runtime compiler. If you are using the runtime-only build, `isCustomElement` must be passed to `@vue/compiler-dom` in the build setup instead - for example, via the [`compilerOptions` option in vue-loader](https://vue-loader.vuejs.org/options.html#compileroptions).
97
100
98
-
* If `config.isCustomElement` is assigned to when using a runtime-only build, a warning will be emitted instructing the user to pass the option in the build setup instead;
99
-
* This will be a new top-level option in the Vue CLI config.
100
-
:::
101
+
- If `config.isCustomElement` is assigned to when using a runtime-only build, a warning will be emitted instructing the user to pass the option in the build setup instead;
102
+
- This will be a new top-level option in the Vue CLI config.
103
+
:::
101
104
102
105
### A Note for Plugin Authors
103
106
104
107
It is a common practice for plugin authors to install the plugins automatically in their UMD builds using `Vue.use`. For instance, this is how the official `vue-router` plugin installs itself in a browser environment:
105
108
106
109
```js
107
-
var inBrowser =typeofwindow!=='undefined';
110
+
var inBrowser =typeofwindow!=='undefined'
108
111
/* … */
109
112
if (inBrowser &&window.Vue) {
110
-
window.Vue.use(VueRouter);
113
+
window.Vue.use(VueRouter)
111
114
}
112
115
```
113
116
@@ -116,7 +119,7 @@ As the `use` global API is no longer available in Vue 3, this method will cease
116
119
```js
117
120
constapp=createApp(MyApp)
118
121
app.use(VueRouter)
119
-
```
122
+
```
120
123
121
124
## Mounting App Instance
122
125
@@ -140,7 +143,7 @@ app.mount(MyApp, '#app', {
140
143
141
144
With all these changes, the component and directive we have at the beginning of the guide will be rewritten into something like this:
142
145
143
-
```js
146
+
```js
144
147
constapp=createApp()
145
148
146
149
app.component('button-counter', {
@@ -154,8 +157,8 @@ app.directive('focus', {
154
157
inserted:el=>el.focus()
155
158
})
156
159
157
-
// now every Vue instance mounted with app.mount(), along with its
158
-
// component tree, will have the same “button-counter” component
160
+
// now every Vue instance mounted with app.mount(), along with its
161
+
// component tree, will have the same “button-counter” component
159
162
// and “focus” directive without polluting the global environment
0 commit comments