应用 API

createApp()

创建应用程序实例。

类型

function createApp(rootComponent: Component, rootProps?: object): App

详情
第一个参数是根组件。第二个可选参数是要传递给根组件的 props。

示例

带有内联根组件

import { createApp } from 'vue'

const app = createApp({
  /* root component options */
})

带有导入的组件

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

const app = createApp(App)

另请参阅 指南 - 创建 Vue 应用程序

createSSRApp()

在SSR Hydration模式下创建应用程序实例。用法与createApp()完全相同。

app.mount()

将应用程序实例挂载到一个容器元素上。

类型

interface App {
  mount(rootContainer: Element | string): ComponentPublicInstance
}

详情
参数可以是实际的DOM元素或CSS选择器（将使用第一个匹配的元素）。返回根组件实例。
如果组件定义了模板或渲染函数，它将替换容器内的任何现有DOM节点。否则，如果可用运行时编译器，将使用容器的innerHTML作为模板。
在SSR Hydration模式下，它将初始化容器内现有的DOM节点。如果存在不匹配，现有DOM节点将被调整为匹配预期输出。
对于每个应用程序实例，mount()只能调用一次。

示例

import { createApp } from 'vue'
const app = createApp(/* ... */)

app.mount('#app')

也可以挂载到实际的DOM元素

app.mount(document.body.firstChild)

app.unmount()

卸载已挂载的应用程序实例，触发应用程序组件树中所有组件的卸载生命周期钩子。

类型
ts
```
interface App {
  unmount(): void
}
```

app.onUnmount()

注册一个回调，在应用程序卸载时被调用。

类型

interface App {
  onUnmount(callback: () => any): void
}

app.component()

如果传递了名称字符串和组件定义，则注册一个全局组件；如果只传递了名称，则检索已注册的一个。

类型

interface App {
  component(name: string): Component | undefined
  component(name: string, component: Component): this
}

示例

import { createApp } from 'vue'

const app = createApp({})

// register an options object
app.component('my-component', {
  /* ... */
})

// retrieve a registered component
const MyComponent = app.component('my-component')

另请参阅 组件注册

app.directive()

如果传递了名称字符串和指令定义，则注册一个全局自定义指令；如果只传递了名称，则检索已注册的一个。

类型

interface App {
  directive(name: string): Directive | undefined
  directive(name: string, directive: Directive): this
}

示例

import { createApp } from 'vue'

const app = createApp({
  /* ... */
})

// register (object directive)
app.directive('my-directive', {
  /* custom directive hooks */
})

// register (function directive shorthand)
app.directive('my-directive', () => {
  /* ... */
})

// retrieve a registered directive
const myDirective = app.directive('my-directive')

另请参阅 自定义指令

app.use()

安装一个插件。

类型

interface App {
  use(plugin: Plugin, ...options: any[]): this
}

详情
期望插件作为第一个参数，可选的插件选项作为第二个参数。
插件可以是一个带有install()方法的对象，或者是一个将被用作install()方法的函数。选项（app.use()的第二个参数）将被传递给插件上的install()方法。
当对同一插件多次调用app.use()时，该插件将只安装一次。

示例

import { createApp } from 'vue'
import MyPlugin from './plugins/MyPlugin'

const app = createApp({
  /* ... */
})

app.use(MyPlugin)

另请参阅 插件

app.mixin()

应用一个全局混入（仅限于应用程序）。全局混入将包含的选项应用于应用程序中的每个组件实例。

不推荐使用

由于在生态系统库中广泛使用，混入主要在Vue 3中得到支持，以实现向后兼容。在应用程序代码中应避免使用混入，特别是全局混入。

对于逻辑复用，首选使用组合式函数。

类型

interface App {
  mixin(mixin: ComponentOptions): this
}

app.provide()

为应用程序内部的所有子组件提供一个可以注入的值。

类型

interface App {
  provide<T>(key: InjectionKey<T> | symbol | string, value: T): this
}

详情
期望注入键作为第一个参数，提供的值作为第二个。返回应用程序实例本身。

示例

import { createApp } from 'vue'

const app = createApp(/* ... */)

app.provide('message', 'hello')

在应用程序中的组件内部

import { inject } from 'vue'

export default {
  setup() {
    console.log(inject('message')) // 'hello'
  }
}

export default {
  inject: ['message'],
  created() {
    console.log(this.message) // 'hello'
  }
}

另请参阅

app.runWithContext()

仅在3.3+版本中支持

以当前应用为注入上下文执行回调。

类型

interface App {
  runWithContext<T>(fn: () => T): T
}

详情
期望一个回调函数并立即运行回调。在回调的同步调用过程中，inject()调用能够从当前应用提供的值中查找注入，即使在没有当前活动的组件实例的情况下。回调函数的返回值也将被返回。

示例

import { inject } from 'vue'

app.provide('id', 1)

const injected = app.runWithContext(() => {
  return inject('id')
})

console.log(injected) // 1

app.version

提供应用创建时使用的Vue版本。这在插件内部很有用，你可能需要根据不同的Vue版本进行条件逻辑。

类型
ts
```
interface App {
  version: string
}
```

示例

在插件内部进行版本检查

export default {
  install(app) {
    const version = Number(app.version.split('.')[0])
    if (version < 3) {
      console.warn('This plugin requires Vue 3')
    }
  }
}

另请参阅 全局API - version

app.config

每个应用实例都公开一个包含该应用配置设置的config对象。在挂载应用之前，您可以修改其属性（如下文所述）。

import { createApp } from 'vue'

const app = createApp(/* ... */)

console.log(app.config)

app.config.errorHandler

为从应用内部传播的未捕获错误分配一个全局处理程序。

类型

interface AppConfig {
  errorHandler?: (
    err: unknown,
    instance: ComponentPublicInstance | null,
    // `info` is a Vue-specific error info,
    // e.g. which lifecycle hook the error was thrown in
    info: string
  ) => void
}

详情
错误处理程序接收三个参数：错误、触发错误的组件实例以及指定错误来源类型的字符串信息。
它可以捕获以下来源的错误
- 组件渲染
- 事件处理程序
- 生命周期钩子
- setup()函数
- 观察者
- 自定义指令钩子
- 过渡钩子
TIP
在生产环境中，第三个参数（info）将是一个缩短的代码而不是完整的信息字符串。您可以在生产错误代码参考中找到代码到字符串的映射。

示例

app.config.errorHandler = (err, instance, info) => {
  // handle error, e.g. report to a service
}

app.config.warnHandler

为Vue的运行时警告分配一个自定义处理程序。

类型

interface AppConfig {
  warnHandler?: (
    msg: string,
    instance: ComponentPublicInstance | null,
    trace: string
  ) => void
}

详情
警告处理程序接收警告消息作为第一个参数，源组件实例作为第二个参数，以及一个组件跟踪字符串作为第三个参数。
它可以用来过滤掉特定的警告以减少控制台冗余。所有Vue警告应在开发过程中解决，因此此功能仅建议在调试会话中用于关注许多警告中的特定警告，调试完成后应删除。
TIP
警告仅在开发期间起作用，因此此配置在生产模式下被忽略。

示例

app.config.warnHandler = (msg, instance, trace) => {
  // `trace` is the component hierarchy trace
}

app.config.performance

将其设置为true以启用浏览器开发工具性能/时间轴面板中的组件初始化、编译、渲染和补丁性能跟踪。仅在开发模式下以及在支持performance.mark API的浏览器中有效。

类型： boolean
另请参阅 指南 - 性能

app.config.compilerOptions

配置运行时编译器选项。设置在此对象上的值将传递给浏览器内模板编译器，并影响配置的应用程序中的每个组件。注意，您还可以使用compilerOptions选项（见compilerOptions）根据每个组件覆盖这些选项。

重要

此配置选项仅在使用完整构建（即可以编译浏览器中模板的独立vue.js）时才受尊重。如果您使用的是仅运行时构建并与构建设置一起使用，则必须通过构建工具配置将编译器选项传递给@vue/compiler-dom。

对于vue-loader：通过compilerOptions加载器选项传递。另请参阅如何在vue-cli中配置它。
对于vite：通过@vitejs/plugin-vue选项传递。

app.config.compilerOptions.isCustomElement

指定一个检查方法来识别原生自定义元素。

类型： (tag: string) => boolean
详情
如果标签应该被处理为原生自定义元素，则应返回true。对于匹配的标签，Vue将其渲染为原生元素，而不是尝试将其解析为Vue组件。
在此函数中不需要匹配原生HTML和SVG标签 - Vue的解析器会自动识别它们。

示例

// treat all tags starting with 'ion-' as custom elements
app.config.compilerOptions.isCustomElement = (tag) => {
  return tag.startsWith('ion-')
}

另请参阅 Vue和Web组件

app.config.compilerOptions.whitespace

调整模板空白处理行为。

类型： 'condense' | 'preserve'
默认： 'condense'
详情
Vue会从模板中删除/压缩空白字符以生成更高效的编译输出。默认策略是“压缩”，具有以下行为
1. 元素内部的前导/结尾空白字符将被压缩为一个空格。
2. 包含换行符的元素之间的空白字符将被删除。
3. 文本节点中的连续空白字符将被压缩为一个空格。
将此选项设置为'preserve'将禁用(2)和(3)。

示例

app.config.compilerOptions.whitespace = 'preserve'

app.config.compilerOptions.delimiters

调整模板中用于文本插值的定界符。

类型： [string, string]
默认： ['{{', '}}']
详情
这通常用于避免与也使用mustache语法的服务器端框架冲突。

示例

// Delimiters changed to ES6 template string style
app.config.compilerOptions.delimiters = ['${', '}']

app.config.compilerOptions.comments

调整模板中HTML注释的处理。

类型： boolean
默认： false
详情
默认情况下，Vue会在生产中删除注释。将此选项设置为true将强制Vue即使在生产中也保留注释。在开发期间始终保留注释。此选项通常用于Vue与其他依赖于HTML注释的库一起使用时。

示例

app.config.compilerOptions.comments = true

app.config.globalProperties

一个可以用于注册全局属性的对象，这些属性可以在应用中任何组件实例上访问。

类型

interface AppConfig {
  globalProperties: Record<string, any>
}

详情
这是Vue 2的Vue.prototype的替代品，在Vue 3中不再存在。像任何全局属性一样，应该谨慎使用。
如果全局属性与组件自身的属性冲突，则组件自身的属性具有更高的优先级。

用法

app.config.globalProperties.msg = 'hello'

这使得msg在应用中任何组件模板内部都可用，并且在任何组件实例的this上也可用。

export default {
  mounted() {
    console.log(this.msg) // 'hello'
  }
}

另请参阅 指南 - 增强全局属性

app.config.optionMergeStrategies

一个对象，用于定义自定义组件选项的合并策略。

类型

interface AppConfig {
  optionMergeStrategies: Record<string, OptionMergeFunction>
}

type OptionMergeFunction = (to: unknown, from: unknown) => any

详情
一些插件/库通过注入全局混入提供了对自定义组件选项的支持。当需要从多个来源（例如混入或组件继承）"合并"相同的选项时，这些选项可能需要特殊的合并逻辑。
可以通过将合并策略函数赋值到app.config.optionMergeStrategies对象（使用选项的名称作为键）来为自定义选项注册合并策略函数。
合并策略函数接收父实例和子实例上定义的该选项的值作为前两个参数。

示例

const app = createApp({
  // option from self
  msg: 'Vue',
  // option from a mixin
  mixins: [
    {
      msg: 'Hello '
    }
  ],
  mounted() {
    // merged options exposed on this.$options
    console.log(this.$options.msg)
  }
})

// define a custom merge strategy for `msg`
app.config.optionMergeStrategies.msg = (parent, child) => {
  return (parent || '') + (child || '')
}

app.mount('#app')
// logs 'Hello Vue'

另请参阅 组件实例 - $options

app.config.idPrefix

为此应用内部通过useId()生成的所有ID配置前缀。

类型： string
默认值： undefined

示例

app.config.idPrefix = 'my-app'

// in a component:
const id1 = useId() // 'my-app:0'
const id2 = useId() // 'my-app:1'

app.config.throwUnhandledErrorInProduction

在生产模式下强制未处理的错误抛出。

类型： boolean
默认： false
详情
默认情况下，在Vue应用内部抛出的错误但未显式处理的，在开发和生产模式之间有不同的行为。
- 在开发中，错误会被抛出，可能会使应用崩溃。这是为了让错误更加突出，以便在开发期间被发现和修复。
- 在生产中，错误只会记录到控制台，以最大限度地减少对最终用户的影响。然而，这可能会阻止错误监控服务捕获仅在生产中发生的错误。
通过将app.config.throwUnhandledErrorInProduction设置为true，即使在生产模式下，未处理的错误也会被抛出。

在GitHub上编辑此页面

应用 API ​

createApp() ​

createSSRApp() ​

app.mount() ​

app.unmount() ​

app.onUnmount() ​

app.component() ​

app.directive() ​

app.use() ​

app.mixin() ​

app.provide() ​

app.runWithContext() ​

app.version ​

app.config ​

app.config.errorHandler ​

app.config.warnHandler ​

app.config.performance ​

app.config.compilerOptions ​

app.config.compilerOptions.isCustomElement ​

app.config.compilerOptions.whitespace ​

app.config.compilerOptions.delimiters ​

app.config.compilerOptions.comments ​

app.config.globalProperties ​

app.config.optionMergeStrategies ​

app.config.idPrefix ​

app.config.throwUnhandledErrorInProduction ​