Skip to content

Commit 2ddec96

Browse files
authored
refactor (#173): reorder migration section sidebar with title standardized for consistency with rendering (#187)
1 parent 5f66924 commit 2ddec96

File tree

5 files changed

+47
-44
lines changed

5 files changed

+47
-44
lines changed

src/.vuepress/config.js

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -85,28 +85,28 @@ const sidebar = {
8585
'/guide/a11y-basics',
8686
'/guide/a11y-semantics',
8787
'/guide/a11y-standards',
88-
'/guide/a11y-resources',
88+
'/guide/a11y-resources'
8989
]
9090
},
9191
{
9292
title: 'Migration to Vue 3',
9393
collapsable: true,
9494
children: [
9595
'migration/introduction',
96-
'migration/global-api',
97-
'migration/treeshaking',
98-
'migration/v-model',
99-
'migration/functional-components',
10096
'migration/async-components',
10197
'migration/custom-directives',
102-
'migration/events-api',
98+
'migration/custom-elements-interop',
10399
'migration/data-option',
100+
'migration/events-api',
104101
'migration/filters',
105102
'migration/fragments',
103+
'migration/functional-components',
104+
'migration/global-api',
105+
'migration/global-api-treeshaking',
106+
'migration/keycode-modifiers',
106107
'migration/render-function-api',
107108
'migration/slots-unification',
108-
'migration/keycode-modifiers',
109-
'migration/custom-elements-interop'
109+
'migration/v-model'
110110
]
111111
},
112112
{

src/guide/migration/events-api.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ types:
44
- breaking
55
---
66

7-
# `$on`, `$off` and `$once` methods removal <span v-for="type in $frontmatter.types" class="badge" :key="`type-${type}`">{{ type }}</span>
7+
# Events API <span v-for="type in $frontmatter.types" class="badge" :key="`type-${type}`">{{ type }}</span>
88

99
## Overview
1010

src/guide/migration/global-api.md

Lines changed: 36 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
1-
# Global API Changes
1+
# Global API
22

33
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:
44

5-
``` js
5+
```js
66
Vue.component('button-counter', {
77
data: () => ({
88
count: 0
@@ -13,40 +13,43 @@ Vue.component('button-counter', {
1313

1414
Similarly, this is how a global directive is declared:
1515

16-
``` js
16+
```js
1717
Vue.directive('focus', {
1818
inserted: el => el.focus()
1919
})
2020
```
2121

2222
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:
2323

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+
2728
import { createLocalVue, mount } from '@vue/test-utils'
28-
29+
2930
// create an extended `Vue` constructor
3031
const localVue = createLocalVue()
31-
32+
3233
// install a plugin “globally” on the “local” Vue constructor
3334
localVue.use(MyPlugin)
3435

3536
// pass the `localVue` to the mount options
3637
mount(Component, { localVue })
37-
```
38+
```
3839
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.
4041
4142
```js
4243
// this affects both root instances
43-
Vue.mixin({ /* ... */ })
44-
44+
Vue.mixin({
45+
/* ... */
46+
})
47+
4548
const app1 = new Vue({ el: '#app-1' })
4649
const app2 = new Vue({ el: '#app-2' })
4750
```
4851

49-
To avoid these problems, in Vue 3 we introduce…
52+
To avoid these problems, in Vue 3 we introduce…
5053

5154
## A New Global API: `createApp`
5255

@@ -55,20 +58,20 @@ Calling `createApp` returns an _app instance_, a new concept in Vue 3.
5558
```js
5659
import { createApp } from 'vue'
5760

58-
const app = createApp()
61+
const app = createApp()
5962
```
6063

6164
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:
6265

63-
| 2.x Global API | 3.x Instance API (`app`) |
64-
|----------------|--------------------------|
65-
| Vue.config | app.config |
66-
| Vue.config.productionTip | _removed_ ([see below](config-productiontip-removed)) |
66+
| 2.x Global API | 3.x Instance API (`app`) |
67+
| -------------------------- | ----------------------------------------------------------------------------------------------- |
68+
| Vue.config | app.config |
69+
| Vue.config.productionTip | _removed_ ([see below](config-productiontip-removed)) |
6770
| Vue.config.ignoredElements | app.config.isCustomElement ([see below](#config-ignoredelements-is-now-config-iscustomelement)) |
68-
| Vue.component | app.component |
69-
| Vue.directive | app.directive |
70-
| Vue.mixin | app.mixin |
71-
| Vue.use | app.use ([see below](#a-note-for-plugin-authors)) |
71+
| Vue.component | app.component |
72+
| Vue.directive | app.directive |
73+
| Vue.mixin | app.mixin |
74+
| Vue.use | app.use ([see below](#a-note-for-plugin-authors)) |
7275

7376
All other global APIs that do not globally mutate behavior are now named exports, as documented in [Global API Treeshaking](./treeshaking.html).
7477

@@ -82,7 +85,7 @@ For ES modules builds, since they are used with bundlers, and in most cases a CL
8285

8386
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:
8487

85-
``` js
88+
```js
8689
// before
8790
Vue.config.ignoredElements = ['my-el', /^ion-/]
8891

@@ -95,19 +98,19 @@ app.config.isCustomElement = tag => tag.startsWith('ion-')
9598

9699
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).
97100

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+
:::
101104

102105
### A Note for Plugin Authors
103106

104107
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:
105108

106109
```js
107-
var inBrowser = typeof window !== 'undefined';
110+
var inBrowser = typeof window !== 'undefined'
108111
/**/
109112
if (inBrowser && window.Vue) {
110-
window.Vue.use(VueRouter);
113+
window.Vue.use(VueRouter)
111114
}
112115
```
113116

@@ -116,7 +119,7 @@ As the `use` global API is no longer available in Vue 3, this method will cease
116119
```js
117120
const app = createApp(MyApp)
118121
app.use(VueRouter)
119-
```
122+
```
120123

121124
## Mounting App Instance
122125

@@ -140,7 +143,7 @@ app.mount(MyApp, '#app', {
140143

141144
With all these changes, the component and directive we have at the beginning of the guide will be rewritten into something like this:
142145

143-
``` js
146+
```js
144147
const app = createApp()
145148

146149
app.component('button-counter', {
@@ -154,8 +157,8 @@ app.directive('focus', {
154157
inserted: el => el.focus()
155158
})
156159

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
159162
// and “focus” directive without polluting the global environment
160163
app.mount(MyApp, '#app')
161164
```
@@ -192,7 +195,7 @@ import Bar from './Bar.vue'
192195

193196
const createMyApp = () => {
194197
const app = createApp()
195-
app.directive('focus', /* ... */)
198+
app.directive('focus' /* ... */)
196199

197200
return app
198201
}

src/guide/migration/v-model.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
1-
# Changes to `v-model` on custom components
1+
# `v-model`
22

33
## Overview
44

55
In terms of what has changed, at a high level:
66

7-
- **BREAKING:**When used on custom components, `v-model` prop and event default names are changed:
7+
- **BREAKING:** When used on custom components, `v-model` prop and event default names are changed:
88
- prop: `value` -> `modelValue`;
99
- event: `input` -> `update:modelValue`;
1010
- **BREAKING:** `v-bind`'s `.sync` modifier and component `model` option are removed and replaced with an argument on `v-model`;

0 commit comments

Comments
 (0)