Vue3全局API

最新推荐文章于 2024-02-29 14:10:18 发布

江湖烟雨十年灯

最新推荐文章于 2024-02-29 14:10:18 发布

阅读量1k

点赞数 19

文章标签： vue.js 前端

本文链接：https://blog.csdn.net/qq_53642101/article/details/135154558

版权

Vue3全局API

应用实例API

createApp()

创建一个应用实例

类型：

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

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

eg：

可以直接内联根组件：

import { createApp } from 'vue'

const app = createApp({
  /* 根组件选项 */
})

也可以使用从别处导入的组件：

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

const app = createApp(App)

createSSRApp()

以SSR激活模式创建一个应用实例。用法与createApp()完全相同。

app.mount()

将应用实例挂载在一个容器元素中。

类型：

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

参数可以是一个实际的DOM元素或一个CSS选择器(使用第一个匹配到的元素)。返回根组件的实例。

如果该组件有模板或定义了渲染函数，他将替换容器内所有现存的DOM节点。否则在运行时编译器可用的情况下，容器元素的innerHTML将被用作模板。

在SSR激活模式下，它将激活容器内现有的DOM节点。如果出现了激活不匹配，那么现有的DOM节点将会被修改以匹配客户端的实际渲染结果。

对于每个应用实例，mount()仅能调用一次。

eg：

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

app.mount('#app')

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

app.mount(document.body.firstChild)

app.unmount()

卸载一个已挂载的应用实例。卸载一个应用会触发该应用组件树内所有组件的卸载生命周期钩子。
类型：

interface App {
  unmount(): void
}

app.component()

如果同时传递一个组件名字字符串及其定义，则注册一个全局组件；如果只传递一个名字，则会返回用该名字注册的组件(如果存在的话)。
类型:

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

eg:

import { createApp } from 'vue'

const app = createApp({})

// 注册一个选项对象
app.component('my-component', {
  /* ... */
})

// 得到一个已注册的组件
const MyComponent = app.component('my-component')

app.dirctive()

如果同时传递一个名字和一个指令定义，则注册一个全局指令；如果只传递一个名字，则会返回用该名字注册的指令(如果存在的话)。

类型：

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

eg:

import { createApp } from 'vue'

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

// 注册（对象形式的指令）
app.directive('my-directive', {
  /* 自定义指令钩子 */
})

// 注册（函数形式的指令）
app.directive('my-directive', () => {
  /* ... */
})

// 得到一个已注册的指令
const myDirective = app.directive('my-directive')

app.use()

安装一个插件
类型：

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

第一个参数应是插件本身，可选的第二个参数是要传递给插件的选项。
插件可以是一个带install()方法的对象，亦或直接是一个将被用作install()方法的函数。
插件选项(app.use()的第二个参数)将会传递给插件的install()方法。
若app.use()对同一个插件多次调用，该插件只会被安装一次。
eg：

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

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

app.use(MyPlugin)

app.mixin()

应用一个全局mixin(适用于该应用的范围)。一个全局的mixin会作用中的每个组件实例。
Mixins在Vue3支持主要是为了向后兼容，因为生态中有许多库使用到。在新的应用中应尽量避免使用mixin，特别是全局mixin。
若要进行逻辑复用，推荐用组合式函数来替代。
类型：

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

app.provide()

提供一个值，可以在应用中的所有后代组件中注入使用。
类型：

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

app.provide()

提供一个值，可以在应用中的所有后代组件中注入使用。
类型:

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

详细信息
第一个参数应当是注入的key，第二个参数则是提供的值。返回应用实例本身。
eg：

import { createApp } from 'vue'

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

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

在应用的某个组件中：

import { inject } from 'vue'

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

app.runWithContext()

使用当前应用作为注入上下文执行回调函数。
类型：

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

需要一个回调函数并立即运行该回调。在回调同步调用期间，即使没有当前活动的组件实例，
inject()调用也可以从当前应用提供的值中查找注入。回调的返回值也将被返回。
eg：

import { inject } from 'vue'

app.provide('id', 1)

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

console.log(injected) // 1

app.version

提供当前应用所使用的Vue版本号。这在插件中很有用，因为可能需要根据不同的Vue版本执行不同的逻辑。
类型：

interface App {
  version: string
}

eg:
在一个插件中对版本作判断：

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

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` 是一个 Vue 特定的错误信息
    // 例如：错误是在哪个生命周期的钩子上抛出的
    info: string
  ) => void
}

错误处理器接收三个参数：错误对象、触发该错误的组件实例和一个指出错误来源类型信息的字符串。
它可以从下面这些来源中捕获错误：
组件渲染器
事件处理器
生命周期钩子
setup()函数
侦听器
自定义指令钩子
过渡(Transition)钩子

eg:

app.config.errorHandler = (err, instance, info) => {
  // 处理错误，例如：报告给一个服务
}

app.config.warnHandler

用于为Vue的运行时警告指定一个自定义处理函数。

类型：

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

警告处理器将接收警告信息作为其第一个参数，来源组件实例为第二个参数，以及组件追踪字符串作为第三个参数。
这可以用户过滤筛选特定的警告信息，降低控制台输出的冗余。所有的Vue警告都需要在开发阶段得到解决，因此仅建议在调试期间选取部分特定警告，并且应该在调试完成之后立刻移除。
eg:

app.config.warnHandler = (msg, instance, trace) => {
  // `trace` 是组件层级结构的追踪
}

app.config.performance

设置此项为true可以在浏览器开发工具的"性能/时间线"页中启用对组件初始化、编译、渲染和修补的性能表现追踪。仅在开发模式和支持performance.API的浏览器中工作。
类型：boolean

app.config.compilerOptions

配置运行是编译器的选项。设置在此对象上的值将会在浏览器内进行模板编译时使用，并会影响到所配置应用的所有组件。另外你也可以通过compilerOptions选项在每个组件的基础上覆盖这些选项。

此配置项仅在完整构建版本，即可以在浏览器中编译模板的vue.js文件中可用。如果你用的是带构建的项目配置，且使用的是仅含运行时的Vue文件版本，那么编译器选项必须通过构建工具的相关配置传递给@vue/compiler-dom。

vue-loader：通过compilerOptions loader的选项传递。并请阅读如何在vue-cli中配置它。

vite：通过@vitejs/plugin-vue的选项传递。

app.config.compilerOptions.isCustomElement

用于指定一个检查方法来识别原生自定义元素。
类型
(tag：string) => boolean
如果该标签需要当作原生自定义元素则应返回true。对匹配到的标签，Vue会将其渲染为原生元素而非将其视为一个Vue组件来解析。
原生HTML和SVG标签不需要在此函数中进行匹配，Vue的解析器会自动识别它们。

eg：

// 将所有标签前缀为 `ion-` 的标签视为自定义元素
app.config.compilerOptions.isCustomElement = (tag) => {
  return tag.startsWith('ion-')
}

app.config.compilerOptions.whitespace

用于调整模板中空格的处理行为。
类型 “ondense”| “preserve”
默认 “condense”

vue移除/缩短了模板中的空格以求更高效的模板输出。默认的策略是"缩短"，表现行为如下：

元素中开头和结尾的空格字符将被缩短为一个空格
包含换行的元素之间的空白字符会被删除
文本节点中连续的空白字符被缩短成一个空格。

设置该选项为"preserve"则会禁用23两项。
eg：

app.config.compilerOptions.whitespace = 'preserve'

app.config.compilerOptions.delimiters

用于调整模板内文本插值的分割符。
类型 [string,string]
默认 [‘{{’,‘}}’]
此项通常是为了避免与同样使用 mustache语法的服务器端框架发生冲突。
eg:

// 分隔符改为ES6模板字符串样式
app.config.compilerOptions.delimiters = ['${', '}']

app.config.compilerOptions.comments

用于调整是否移除模板中的HTML注释
类型boolean
默认false
默认情况下，Vue会在生产情况移除所有注释，设置该项为true会强制Vue在生产环境也保留注释。在开发过程中，注释是始终被保留的。这个选项通常在Vue与其他依赖HTML注释的库一起使用时使用。
eg：

app.config.compilerOptions.comments = true

app.config.globalProperties

一个用于注册能够被应用内所有组件实例访问到的全局属性的对象。
类型：

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

这是对Vue2中Vue.prototype使用方式的一种替代，此写法在Vue3已经不存在了。与任何全局的东西一样，应该谨慎使用。
如果全局属性与组件自己的属性冲突，组件自己的属性将具有更高的优先级。
用法：

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

一些插件或库对自定义组件选项添加了支持(通过注入全局mixin)。这些选项在有多个不同来源时可能需要特殊的合并策略(例如mixin或组件继承)
可能在app.config.optionMergeStrategies对象上以选项的名称作为key，可以为一个自定义选项注册分配一个合并策略函数。
合并策略函数分别接受在父实例和子实例上定义的该选项的值作为第一和第二个参数。
eg：

const app = createApp({
  // 自身的选项
  msg: 'Vue',
  // 来自 mixin 的选项
  mixins: [
    {
      msg: 'Hello '
    }
  ],
  mounted() {
    // 在 this.$options 上暴露被合并的选项
    console.log(this.$options.msg)
  }
})

// 为 `msg` 定义一个合并策略函数
app.config.optionMergeStrategies.msg = (parent, child) => {
  return (parent || '') + (child || '')
}

app.mount('#app')
// 打印 'Hello Vue'

全局API：常规

version

暴露当前所使用的Vue版本。
类型 string
eg：

import { version } from 'vue'

console.log(version)

nextTick()

等待下一次DOM更新刷新的工具方法。
类型：

function nextTick(callback?: () => void): Promise<void>

当你在Vue中更改响应式状态时，最终的DOM更新并不是同步生效的，而是由Vue将它们缓存在一个队列中，知道下一个"tick"才一起执行。这样是为了确保每个组件无论发生多少状态改变，都仅执行一次更新。
nextTick()可以在状态后立即使用，以等待DOM更新完成。你可以传递一个回调函数作为参数，或者await返回的Promise。

eg：

<script setup>
import { ref, nextTick } from 'vue'

const count = ref(0)

async function increment() {
  count.value++

  // DOM 还未更新
  console.log(document.getElementById('counter').textContent) // 0

  await nextTick()
  // DOM 此时已经更新
  console.log(document.getElementById('counter').textContent) // 1
}
</script>

<template>
  <button id="counter" @click="increment">{{ count }}</button>
</template>

defineComponent()

在定义Vue组件时提供类型推导的辅助函数。
类型：

// 选项语法
function defineComponent(
  component: ComponentOptions
): ComponentConstructor

// 函数语法 (需要 3.3+)
function defineComponent(
  setup: ComponentOptions['setup'],
  extraOptions?: ComponentOptions
): () => any

详细信息
第一个参数是一个组件选项对象。返回值将是该选项对象本身，因为该函数实际上在运行时没有任何操作，仅用于提供类型推导。
注意返回值的类型有一点特别：它会是一个构造函数类型，它的实例类型是根据选项推断出的组件实例类型。这是为了能让该返回值在TSX中用作标签时提供类型推导支持。
你可以像这样从defineComponent()的返回类型中提取出一个组件的实例类型(与其选项中的this的类型等价):

const Foo = defineComponent(/* ... */)

type FooInstance = InstanceType<typeof Foo>

函数签名

defineComponent()还有一种备用签名，旨在与组合式API和渲染函数或JSX一起使用。
与传递选项对象不同的是，它需要传入一个函数。这个函数的工作方式与组合式API的setup()函数相同：它接收props和setup上下文。返回值应该是一个渲染函数–支持h()和JSX:

import { ref, h } from 'vue'

const Comp = defineComponent(
  (props) => {
    // 就像在 <script setup> 中一样使用组合式 API
    const count = ref(0)

    return () => {
      // 渲染函数或 JSX
      return h('div', count.value)
    }
  },
  // 其他选项，例如声明 props 和 emits。
  {
    props: {
      /* ... */
    }
  }
)

此签名的主要用例是使用TypeScript(特别是使用TSX),因为它支持泛型：

const Comp = defineComponent(
  <T extends string | number>(props: { msg: T; list: T[] }) => {
    // 就像在 <script setup> 中一样使用组合式 API
    const count = ref(0)

    return () => {
      // 渲染函数或 JSX
      return <div>{count.value}</div>
    }
  },
  // 目前仍然需要手动声明运行时的 props
  {
    props: ['msg', 'list']
  }
)

在将来，我们计划提供一个Babel插件，自动推断并注入运行时props(就像在SFC中的defineProps一样)，以便省略运行时props的声明。

webpack Treeshaking的注意事项
因为defineComponent()是一个函数调用，所有它可能被某些构建工具认为会产生副作用，如webpack。即使一个组件从未被使用，也有可能不被tree-shake。
为了告诉webpack这个函数调用可以被安全地tree-shake，我们可以在函数调用之前添加一个/#PURE/形式的注释：

export default /*#__PURE__*/ defineComponent(/* ... */)

请注意，如果你的项目中使用的是Vite，就不需要这么做，因为Rollup(Vite底层使用的生产环境打包工具）可以智能地确定defineComponent()实际上并没有副作用，所以无需手动注释。

defineAsyncComponent()

定义一个异步组件，他在运行时是懒加载的。参数可以是一个异步加载函数，或是对加载行为进行更具体定制的一个选项对象。

类型

function defineAsyncComponent(
  source: AsyncComponentLoader | AsyncComponentOptions
): Component

type AsyncComponentLoader = () => Promise<Component>

interface AsyncComponentOptions {
  loader: AsyncComponentLoader
  loadingComponent?: Component
  errorComponent?: Component
  delay?: number
  timeout?: number
  suspensible?: boolean
  onError?: (
    error: Error,
    retry: () => void,
    fail: () => void,
    attempts: number
  ) => any
}

defineCustomElement()

这个方法和defineComponent接受的参数相同，不用的是会返回一个原生自定义元素类的构造器。
类型：

function defineCustomElement(
  component:
    | (ComponentOptions & { styles?: string[] })
    | ComponentOptions['setup']
): {
  new (props?: object): HTMLElement
}

除了常规的组件选项，defineCustomElement()还支持一个特别的选项styles，它应该是一个内联CSS字符串的数组，所提供的CSS会被注入到该元素的shadow root上。
返回值是一个可以通过customElements.define()注册的自定义元素构造器。
eg：

import { defineCustomElement } from 'vue'

const MyVueElement = defineCustomElement({
  /* 组件选项 */
})

// 注册自定义元素
customElements.define('my-vue-element', MyVueElement)