全局 API 应用实例

非兼容

#

Vue 2.x 有许多全局 API 和配置，它们可以全局改变 Vue 的行为。例如，要注册全局组件，可以使用 Vue.component API，就像这样：

Vue.component('button-counter', {
  data: () => ({
    count: 0
  }),
  template: '<button @click="count++">Clicked {{ count }} times.</button>'
})

类似地，全局指令的声明方式如下：

Vue.directive('focus', {
  inserted: (el) => el.focus()
})

虽然这种声明方式很方便，但它也会导致一些问题。从技术上讲，Vue 2 没有“app”的概念，我们定义的应用只是通过 new Vue() 创建的根 Vue 实例。从同一个 Vue 构造函数创建的每个根实例共享相同的全局配置，因此：

• 在测试期间，全局配置很容易意外地污染其他测试用例。用户需要仔细地存储原始全局配置，并在每次测试后恢复 (例如重置 Vue.config.errorHandler)。有些 API 像 Vue.use 以及 Vue.mixin 甚至连恢复它们所产生的作用的方法都没有，这使得涉及插件的测试特别棘手。实际上，vue-test-utils 必须实现一个特殊的 API createLocalVue 来处理此问题：

  js

  import { createLocalVue, mount } from '@vue/test-utils'
  
  // 创建一个扩展的 `Vue` 构造函数
  const localVue = createLocalVue()
  
  // 在 “local” Vue构造函数上 “全局地” 安装插件
  localVue.use(MyPlugin)
  
  // 将 `localVue` 传入挂载选项
  mount(Component, { localVue })
  

• 全局配置使得在同一页面上的多个“应用”在全局配置不同时共享同一个 Vue 副本非常困难。

  js

  // 这会影响到所有根实例
  Vue.mixin({
    /* ... */
  })
  
  const app1 = new Vue({ el: '#app-1' })
  const app2 = new Vue({ el: '#app-2' })
  

为了避免这些问题，在 Vue 3 中我们引入了...

一个新的全局 API：createApp #

调用 createApp 返回一个应用实例，一个 Vue 3 中的新概念。

import { createApp } from 'vue'

const app = createApp({})

如果你使用的是 Vue 的 CDN 构建版本，那么 createApp 将通过全局的 Vue 对象暴露。

const { createApp } = Vue

const app = createApp({})

应用实例暴露了 Vue 2 全局 API 的一个子集，经验法则是，任何全局改变 Vue 行为的 API 现在都会移动到应用实例上，以下是 Vue2 全局 API 及其相应的实例 API 列表：

所有其他不全局改变行为的全局 API 现在都是具名导出，文档见全局 API Treeshaking。

config.productionTip 移除 #

在 Vue 3.x 中，“使用生产版本”提示仅在使用“dev + full build”(包含运行时编译器并有警告的构建版本) 时才会显示。

对于 ES 模块构建版本，由于它们是与打包器一起使用的，而且在大多数情况下，CLI 或脚手架已经正确地配置了生产环境，所以本提示将不再出现。

迁移构建开关：CONFIG_PRODUCTION_TIP

config.ignoredElements 替换为 config.isCustomElement #

引入此配置选项的目的是为了支持原生自定义元素，因此重命名可以更好地传达它的意图。同时，新选项接受一个函数，相比旧的字符串或正则表达式来说能提供更高的灵活性：

// 之前
Vue.config.ignoredElements = ['my-el', /^ion-/]

// 之后
const app = createApp({})
app.config.compilerOptions.isCustomElement = (tag) => tag.startsWith('ion-')

迁移构建开关：CONFIG_IGNORED_ELEMENTS

Vue.prototype 替换为 config.globalProperties #

在 Vue 2 中， Vue.prototype 通常用于添加所有组件都能访问的 property。

在 Vue 3 中与之对应的是 config.globalProperties。这些 property 将被复制到应用中，作为实例化组件的一部分。

// 之前 - Vue 2
Vue.prototype.$http = () => {}

// 之后 - Vue 3
const app = createApp({})
app.config.globalProperties.$http = () => {}

使用 provide (稍后会讨论) 时，也应考虑作为 globalProperties 的替代品。

迁移构建开关：GLOBAL_PROTOTYPE

Vue.extend 移除 #

在 Vue 2.x 中，Vue.extend 曾经被用于创建一个基于 Vue 构造函数的“子类”，其参数应为一个包含组件选项的对象。在 Vue 3.x 中，我们已经没有组件构造器的概念了。应该始终使用 createApp 这个全局 API 来挂载组件：

// 之前 - Vue 2

// 创建构造器
const Profile = Vue.extend({
  template: '<p>{{firstName}} {{lastName}} aka {{alias}}</p>',
  data() {
    return {
      firstName: 'Walter',
      lastName: 'White',
      alias: 'Heisenberg'
    }
  }
})
// 创建一个 Profile 的实例，并将它挂载到一个元素上
new Profile().$mount('#mount-point')

// 之后 - Vue 3
const Profile = {
  template: '<p>{{firstName}} {{lastName}} aka {{alias}}</p>',
  data() {
    return {
      firstName: 'Walter',
      lastName: 'White',
      alias: 'Heisenberg'
    }
  }
}
Vue.createApp(Profile).mount('#mount-point')

类型推断 #

在 Vue 2 中，Vue.extend 也被用来为组件选项提供 TypeScript 类型推断。在 Vue 3 中，为了达到相同的目的，defineComponent 全局 API 可以用来作为 Vue.extend 的替代方案。

需要注意的是，虽然 defineComponent 的返回类型是一个类似构造器的类型，但是它的目的仅仅是为了 TSX 的推断。在运行时 defineComponent 里基本没有什么操作，只会原样返回该选项对象。

组件继承 #

在 Vue 3 中，我们强烈建议使用 组合式 API 来替代继承与 mixin。如果因为某种原因仍然需要使用组件继承，你可以使用 extends 选项 来代替 Vue.extend。

迁移构建开关：GLOBAL_EXTEND

插件开发者须知 #

在 UMD 构建中，插件开发者使用 Vue.use 来自动安装插件是一个通用的做法。例如，官方的 vue-router 插件是这样在浏览器环境中自行安装的：

var inBrowser = typeof window !== 'undefined'
/* … */
if (inBrowser && window.Vue) {
  window.Vue.use(VueRouter)
}

由于 use 全局 API 在 Vue 3 中已无法使用，因此此方法将无法正常工作，并且调用 Vue.use() 现在将触发一个警告。取而代之的是，开发者必须在应用实例上显式指定使用此插件：

const app = createApp(MyApp)
app.use(VueRouter)

挂载 App 实例 #

使用 createApp(/* options */) 初始化后，应用实例 app 可通过 app.mount(domTarget) 挂载根组件实例：

import { createApp } from 'vue'
import MyApp from './MyApp.vue'

const app = createApp(MyApp)
app.mount('#app')

经过所有的这些更改，我们在指南开头编写的组件和指令现在将被改写为如下内容：

const app = createApp(MyApp)

app.component('button-counter', {
  data: () => ({
    count: 0
  }),
  template: '<button @click="count++">Clicked {{ count }} times.</button>'
})

app.directive('focus', {
  mounted: (el) => el.focus()
})

// 现在，所有通过 app.mount() 挂载的应用实例及其组件树，
// 将具有相同的 “button-counter” 组件和 “focus” 指令，
// 而不会污染全局环境
app.mount('#app')

迁移构建开关：GLOBAL_MOUNT

Provide / Inject #

与在 2.x 根实例中使用 provide 选项类似，Vue 3 应用实例也提供了可被应用内任意组件注入的依赖项：

// 在入口中
app.provide('guide', 'Vue 3 Guide')

// 在子组件中
export default {
  inject: {
    book: {
      from: 'guide'
    }
  },
  template: `<div>{{ book }}</div>`
}

在编写插件时使用 provide 将尤其有用，可以替代 globalProperties。

在应用之间共享配置 #

在应用之间共享配置 (如组件或指令) 的一种方法是创建工厂函数，如下所示：

import { createApp } from 'vue'
import Foo from './Foo.vue'
import Bar from './Bar.vue'

const createMyApp = (options) => {
  const app = createApp(options)
  app.directive('focus' /* ... */)

  return app
}

createMyApp(Foo).mount('#foo')
createMyApp(Bar).mount('#bar')

现在，Foo 和 Bar 实例及其后代中都可以使用 focus 指令。