diff --git a/src/.vuepress/config.js b/src/.vuepress/config.js index b8291aa8c2..eb251c0417 100644 --- a/src/.vuepress/config.js +++ b/src/.vuepress/config.js @@ -85,7 +85,7 @@ const sidebar = { '/guide/a11y-basics', '/guide/a11y-semantics', '/guide/a11y-standards', - '/guide/a11y-resources', + '/guide/a11y-resources' ] }, { @@ -93,20 +93,20 @@ const sidebar = { collapsable: true, children: [ 'migration/introduction', - 'migration/global-api', - 'migration/treeshaking', - 'migration/v-model', - 'migration/functional-components', 'migration/async-components', 'migration/custom-directives', - 'migration/events-api', + 'migration/custom-elements-interop', 'migration/data-option', + 'migration/events-api', 'migration/filters', 'migration/fragments', + 'migration/functional-components', + 'migration/global-api', + 'migration/global-api-treeshaking', + 'migration/keycode-modifiers', 'migration/render-function-api', 'migration/slots-unification', - 'migration/keycode-modifiers', - 'migration/custom-elements-interop' + 'migration/v-model' ] }, { diff --git a/src/guide/migration/events-api.md b/src/guide/migration/events-api.md index 3d963a3df6..1ab25ade49 100644 --- a/src/guide/migration/events-api.md +++ b/src/guide/migration/events-api.md @@ -4,7 +4,7 @@ types: - breaking --- -# `$on`, `$off` and `$once` methods removal {{ type }} +# Events API {{ type }} ## Overview diff --git a/src/guide/migration/treeshaking.md b/src/guide/migration/global-api-treeshaking.md similarity index 100% rename from src/guide/migration/treeshaking.md rename to src/guide/migration/global-api-treeshaking.md diff --git a/src/guide/migration/global-api.md b/src/guide/migration/global-api.md index 80578c4e39..e5625deb6c 100644 --- a/src/guide/migration/global-api.md +++ b/src/guide/migration/global-api.md @@ -1,8 +1,8 @@ -# Global API Changes +# Global API 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: -``` js +```js Vue.component('button-counter', { data: () => ({ count: 0 @@ -13,7 +13,7 @@ Vue.component('button-counter', { Similarly, this is how a global directive is declared: -``` js +```js Vue.directive('focus', { inserted: el => el.focus() }) @@ -21,32 +21,35 @@ Vue.directive('focus', { 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: -* 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: - - ``` js +- 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: + + ``` js + import { createLocalVue, mount } from '@vue/test-utils' - + // create an extended `Vue` constructor const localVue = createLocalVue() - + // install a plugin “globally” on the “local” Vue constructor localVue.use(MyPlugin) // pass the `localVue` to the mount options mount(Component, { localVue }) - ``` + ``` -* Global configuration makes it difficult to share the same copy of Vue between multiple "apps" on the same page, but with different global configurations. +- Global configuration makes it difficult to share the same copy of Vue between multiple "apps" on the same page, but with different global configurations. ```js // this affects both root instances - Vue.mixin({ /* ... */ }) - + Vue.mixin({ + /* ... */ + }) + const app1 = new Vue({ el: '#app-1' }) const app2 = new Vue({ el: '#app-2' }) ``` -To avoid these problems, in Vue 3 we introduce… +To avoid these problems, in Vue 3 we introduce… ## A New Global API: `createApp` @@ -55,20 +58,20 @@ Calling `createApp` returns an _app instance_, a new concept in Vue 3. ```js import { createApp } from 'vue' -const app = createApp() +const app = createApp() ``` 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: -| 2.x Global API | 3.x Instance API (`app`) | -|----------------|--------------------------| -| Vue.config | app.config | -| Vue.config.productionTip | _removed_ ([see below](config-productiontip-removed)) | +| 2.x Global API | 3.x Instance API (`app`) | +| -------------------------- | ----------------------------------------------------------------------------------------------- | +| Vue.config | app.config | +| Vue.config.productionTip | _removed_ ([see below](config-productiontip-removed)) | | Vue.config.ignoredElements | app.config.isCustomElement ([see below](#config-ignoredelements-is-now-config-iscustomelement)) | -| Vue.component | app.component | -| Vue.directive | app.directive | -| Vue.mixin | app.mixin | -| Vue.use | app.use ([see below](#a-note-for-plugin-authors)) | +| Vue.component | app.component | +| Vue.directive | app.directive | +| Vue.mixin | app.mixin | +| Vue.use | app.use ([see below](#a-note-for-plugin-authors)) | All other global APIs that do not globally mutate behavior are now named exports, as documented in [Global API Treeshaking](./treeshaking.html). @@ -82,7 +85,7 @@ For ES modules builds, since they are used with bundlers, and in most cases a CL 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: -``` js +```js // before Vue.config.ignoredElements = ['my-el', /^ion-/] @@ -95,19 +98,19 @@ app.config.isCustomElement = tag => tag.startsWith('ion-') 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). -* 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; -* This will be a new top-level option in the Vue CLI config. -::: +- 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; +- This will be a new top-level option in the Vue CLI config. + ::: ### A Note for Plugin Authors 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: ```js -var inBrowser = typeof window !== 'undefined'; +var inBrowser = typeof window !== 'undefined' /* … */ if (inBrowser && window.Vue) { - window.Vue.use(VueRouter); + window.Vue.use(VueRouter) } ``` @@ -116,7 +119,7 @@ As the `use` global API is no longer available in Vue 3, this method will cease ```js const app = createApp(MyApp) app.use(VueRouter) -``` +``` ## Mounting App Instance @@ -140,7 +143,7 @@ app.mount(MyApp, '#app', { With all these changes, the component and directive we have at the beginning of the guide will be rewritten into something like this: -``` js +```js const app = createApp() app.component('button-counter', { @@ -154,8 +157,8 @@ app.directive('focus', { inserted: el => el.focus() }) -// now every Vue instance mounted with app.mount(), along with its -// component tree, will have the same “button-counter” component +// now every Vue instance mounted with app.mount(), along with its +// component tree, will have the same “button-counter” component // and “focus” directive without polluting the global environment app.mount(MyApp, '#app') ``` @@ -192,7 +195,7 @@ import Bar from './Bar.vue' const createMyApp = () => { const app = createApp() - app.directive('focus', /* ... */) + app.directive('focus' /* ... */) return app } diff --git a/src/guide/migration/v-model.md b/src/guide/migration/v-model.md index 4b10cfd995..872d684849 100644 --- a/src/guide/migration/v-model.md +++ b/src/guide/migration/v-model.md @@ -1,10 +1,10 @@ -# Changes to `v-model` on custom components +# `v-model` ## Overview In terms of what has changed, at a high level: -- **BREAKING:**When used on custom components, `v-model` prop and event default names are changed: +- **BREAKING:** When used on custom components, `v-model` prop and event default names are changed: - prop: `value` -> `modelValue`; - event: `input` -> `update:modelValue`; - **BREAKING:** `v-bind`'s `.sync` modifier and component `model` option are removed and replaced with an argument on `v-model`;