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
In Vue 2, using the `ref` attribute inside `v-for` will populate the corresponding `$refs` property with an array of refs. This behavior becomes ambiguous and inefficient when there are nested `v-for`s present.
10
+
11
+
In Vue 3, such usage will no longer automatically create an array in `$refs`. To retrieve multiple refs from a single binding, bind `ref` to a function which provides more flexibility (this is a new feature):
Copy file name to clipboardExpand all lines: src/guide/migration/data-option.md
+53Lines changed: 53 additions & 0 deletions
Original file line number
Diff line number
Diff line change
@@ -10,6 +10,8 @@ badges:
10
10
11
11
-**BREAKING**: `data` component option declaration no longer accepts a plain JavaScript `object` and expects a `function` declaration.
12
12
13
+
-**BREAKING**: when merging multiple `data` return values from mixins or extends, the merge is now shallow instead of deep (only root-level properties are merged).
14
+
13
15
## 2.x Syntax
14
16
15
17
In 2.x, developers could define the `data` option with either an `object` or a `function`.
@@ -60,9 +62,60 @@ Using the example above, there would only be one possible implementation of the
60
62
</script>
61
63
```
62
64
65
+
## Mixin Merge Behavior Change
66
+
67
+
In addition, when `data()` from a component and its mixins or extends base are merged, the merge is now performed *shallowly*:
68
+
69
+
```js
70
+
constMixin= {
71
+
data() {
72
+
return {
73
+
user: {
74
+
name:'Jack',
75
+
id:1
76
+
}
77
+
}
78
+
}
79
+
}
80
+
81
+
constCompA= {
82
+
mixins: [Mixin],
83
+
data() {
84
+
return {
85
+
user: {
86
+
id:2
87
+
}
88
+
}
89
+
}
90
+
}
91
+
```
92
+
93
+
In Vue 2.x, the resulting `$data` is:
94
+
95
+
```json
96
+
{
97
+
user: {
98
+
id: 2,
99
+
name: 'Jack'
100
+
}
101
+
}
102
+
```
103
+
104
+
In 3.0, the result will be:
105
+
106
+
```json
107
+
{
108
+
user: {
109
+
id: 2
110
+
}
111
+
}
112
+
```
113
+
63
114
## Migration Strategy
64
115
65
116
For users relying on the object declaration, we recommend:
66
117
67
118
- Extracting the shared data into an external object and using it as a property in `data`
68
119
- Rewrite references to the shared data to point to a new shared object
120
+
121
+
For users relying on the deep merge behavior from mixins, we recommend refactoring your code to avoid such reliance altogether, since deep merges from mixins are very implicit and can make the code logic more difficult to understand and debug.
> There's so much here! Does that mean 3.0 is completely different, I'll have to learn the basics all over again, and migrating will be practically impossible?
3
+
This guide is primarily for users with prior Vue 2 experience who want to learn about the new features and changes in Vue 3. The lists may look long, but it is because we want to be as thorough as possible and provide detailed examples for every documented change. **This is not something you have to read from top to bottom before trying out Vue 3.**
4
4
5
-
We're glad you asked! The answer is no. We've gone to great lengths to ensure most of the API is the same and the core concepts haven't changed. It's long because we like to offer very detailed explanations and include a lot of examples. Rest assured, **this is not something you have to read from top to bottom!**
6
-
7
-
Possibly the biggest change is our new [Composition API](/guide/composition-api-introduction.html), which is entirely additive- the previous Options API will continue to be supported, as the Composition API is an advanced feature.
5
+
-[Quickstart](#quickstart)
6
+
-[New Features](#new-features)
7
+
-[Breaking Changes](#breaking-changes)
8
+
-[Supporting Libraries](#supporting-libraries)
8
9
9
10
## Overview
10
11
@@ -13,67 +14,167 @@ Possibly the biggest change is our new [Composition API](/guide/composition-api-
13
14
14
15
Start learning Vue 3 at [Vue Mastery](https://www.vuemastery.com/courses-path/vue3).
15
16
16
-
### New Features
17
+
## Quickstart
18
+
19
+
- Via CDN: `<script src="https://unpkg.com/vue@next"></script>`
20
+
- In-browser playground on [Codepen](https://codepen.io/yyx990803/pen/OJNoaZL)
21
+
- Scaffold via [Vite](https://github.com/vitejs/vite):
22
+
23
+
```bash
24
+
npm init vite-app hello-vue3 # OR yarn create vite-app hello-vue3
25
+
```
26
+
27
+
- Scaffold via [vue-cli](https://cli.vuejs.org/):
28
+
29
+
```bash
30
+
npm install -g @vue/cli # OR yarn global add @vue/cli
31
+
vue create hello-vue3
32
+
# select vue 3 preset
33
+
```
34
+
35
+
## New Features
17
36
18
37
Some of the new features to keep an eye on in Vue 3 include:
We are still working on a dedicated Migration Build of Vue 3 with Vue 2 compatible behavior and runtime warnings of incompatible usage. If you are planning to migrate a non-trivial Vue 2 app, we strongly recommend waiting for the Migration Build for a smoother experience.
51
+
:::
27
52
28
53
The following consists a list of breaking changes from 2.x:
29
54
55
+
### Global API
56
+
30
57
-[Global Vue API is changed to use an application instance](/guide/migration/global-api.html)
31
58
-[Global and internal APIs have been restructured to be tree-shakable](/guide/migration/global-api-treeshaking.html)
32
-
-[`model` component option and `v-bind`'s `sync` modifier are removed in favor of `v-model` arguments](/guide/migration/v-model.html)
33
-
-[Render function API changed](/guide/migration/render-function-api.html)
59
+
60
+
### Template Directives
61
+
62
+
-[`v-model` usage on components has been reworked](/guide/migration/v-model.html)
63
+
-[`key` usage on `<template v-for>` and non-`v-for` nodes has changed](/guide/migration/key-attribute.html)
64
+
-[`v-if` and `v-for` precedence when used on the same element has changed](/guide/migration/v-if-v-for.html)
65
+
-[`v-bind="object"` is now order-sensitive](/guide/migration/v-bind.html)
66
+
-[`ref` inside `v-for` no longer register an array of refs](/guide/migration/array-refs.html)
67
+
68
+
### Components
69
+
34
70
-[Functional components can only be created using a plain function](/guide/migration/functional-components.html)
35
71
-[`functional` attribute on single-file component (SFC) `<template>` and `functional` component option are deprecated](/guide/migration/functional-components.html)
36
72
-[Async components now require `defineAsyncComponent` method to be created](/guide/migration/async-components.html)
37
-
-[Component data option should always be declared as a function](/guide/migration/data-option.html)
38
-
-[Custom elements whitelisting is now performed during template compilation](/guide/migration/custom-elements-interop.html)
39
-
-[Special `is` prop usage is restricted to the reserved `<component>` tag only](/guide/migration/custom-elements-interop.html)
73
+
74
+
### Render Function
75
+
76
+
-[Render function API changed](/guide/migration/render-function-api.html)
40
77
-[`$scopedSlots` property is removed and need to be replaced with `$slots`](/guide/migration/slots-unification.html)
-[Custom elements whitelisting is now performed during template compilation](/guide/migration/custom-elements-interop.html)
82
+
-[Special `is` prop usage is restricted to the reserved `<component>` tag only](/guide/migration/custom-elements-interop.html#customized-built-in-elements)
83
+
84
+
### Other Minor Changes
85
+
86
+
- The ~~`destroyed`~~ lifecycle option has been renamed to `unmounted`
87
+
- The ~~`beforeDestroy`~~ lifecycle option has been renamed to `beforeUnmount`
88
+
-[Props `default` factory function no longer has access to `this` context](/guide/migration/props-default-this.html)
42
89
-[Custom directive API changed to align with component lifecycle](/guide/migration/custom-directives.html)
43
-
-[Some transition classes got a rename](/guide/migration/transition.md)
44
-
-[Component watch option](/api/options-data.html#watch) and [instance method `$watch`](/api/instance-methods.html#watch) no longer supports dot-delimited string paths, use a computed function as the parameter instead
45
-
-[Changes in `key` attribute usage with `v-if` and `<template v-for>`](/guide/migration/key-attribute.md)
46
-
- In Vue 2.x, application root container's `outerHTML` is replaced with root component template (or eventually compiled to a template, if root component has no template/render option). Vue 3.x now uses application container's `innerHTML` instead.
90
+
-[The `data` option should always be declared as a function](/guide/migration/data-option.html)
91
+
-[The `data` option from mixins is now merged shallowly](/guide/migration/data-option.html#mixin-merge-behavior-change)
-[Some transition classes got a rename](/guide/migration/transition.html)
94
+
-[Component watch option](/api/options-data.html#watch) and [instance method `$watch`](/api/instance-methods.html#watch) no longer supports dot-delimited string paths, use a computed function as the parameter instead.
95
+
-`<template>` tags with no special directives (`v-if/else-if/else`, `v-for`, or `v-slot`) are now treated as plain elements and will result in a native `<template>` element instead of rendering its inner content.
96
+
- In Vue 2.x, application root container's `outerHTML` is replaced with root component template (or eventually compiled to a template, if root component has no template/render option). Vue 3.x now uses application container's `innerHTML` instead - this means the container itself is no longer considered part of the template.
47
97
48
-
### Removed
98
+
### Removed APIs
49
99
50
100
-[`keyCode` support as `v-on` modifiers](/guide/migration/keycode-modifiers.html)
51
101
-[$on, $off and \$once instance methods](/guide/migration/events-api.html)
-`$destroy` instance method. Users should no longer manually manage the lifecycle of individual Vue components.
105
+
106
+
## Supporting Libraries
107
+
108
+
All of our official libraries and tools now support Vue 3, but most of them are still in beta status and distributed under the `next` dist tag on NPM. **We are planning to stabilize and switch all projects to use the `latest` dist tag by end of 2020.**
109
+
110
+
### Vue CLI
111
+
112
+
As of v4.5.0, `vue-cli` now provides built-in option to choose Vue 3 preset when creating a new project. You can upgrade `vue-cli` and run `vue create` to create a Vue 3 project today.
113
+
114
+
### Vue Router
115
+
116
+
Vue Router 4.0 provides Vue 3 support and has a number of breaking changes of its own. Check out its [README](https://github.com/vuejs/vue-router-next#vue-router-next-) for full details.
Vuex 4.0 provides Vue 3 support with largely the same API as 3.x. The only breaking change is [how the plugin is installed](https://github.com/vuejs/vuex/tree/4.0#breaking-changes).
We are working on a new version of the Devtools with a new UI and refactored internals to support multiple Vue versions. The new version is currently in beta and only supports Vue 3 (for now). Vuex and Router integration is also work in progress.
54
132
55
-
## FAQ
133
+
- For Chrome: [Install from Chrome web store](https://chrome.google.com/webstore/detail/vuejs-devtools/ljjemllljcmogpfapbkkighbhhppjdbg?hl=en)
56
134
57
-
### Where should I start in a migration?
135
+
- Note: the beta channel may conflict with the stable version of devtools so you may need to temporarily disable the stable version for the beta channel to work properly.
58
136
59
-
1. Start by running the migration helper (still under development) on a current project. We've carefully minified and compressed a senior Vue dev into a simple command line interface. Whenever they recognize an obsolete feature, they'll let you know, offer suggestions, and provide links to more info.
137
+
- For Firefox: [Download the signed extension](https://github.com/vuejs/vue-devtools/releases/tag/v6.0.0-beta.2) (`.xpi` file under Assets)
60
138
61
-
2. After that, browse through the table of contents for this page in the sidebar. If you see a topic you may be affected by, but the migration helper didn't catch, check it out.
139
+
### Other Projects
62
140
63
-
3. If you have any tests, run them and see what still fails. If you don't have tests, just open the app in your browser and keep an eye out for warnings or errors as you navigate around.
4. By now, your app should be fully migrated. If you're still hungry for more though, you can read the rest of this page - or dive in to the new and improved guide from [the beginning](#overview). Many parts will be skimmable, since you're already familiar with the core concepts.
- Which obsolete features you're using. Most can be upgraded with find-and-replace, but others might take a few minutes. If you're not currently following best practices according to [our styleguide](/style-guide/), Vue 3.0 will also try harder to force you to. This is a good thing in the long run, but could also mean a significant (though possibly overdue) refactor.
Copy file name to clipboardExpand all lines: src/guide/migration/key-attribute.md
+1-1Lines changed: 1 addition & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -8,7 +8,7 @@ badges:
8
8
## Overview
9
9
10
10
-**NEW:**`key`s are no longer necessary on `v-if`/`v-else`/`v-else-if` branches, since Vue now automatically generates unique `key`s.
11
-
-**BREAKING:** If you manually provide `key`s, then each branch must use a unique `key`.
11
+
-**BREAKING:** If you manually provide `key`s, then each branch must use a unique `key`. You can no longer intentionally use the same `key` to force branch reuse.
12
12
-**BREAKING:**`<template v-for>``key` should be placed on the `<template>` tag (rather than on its children).
0 commit comments