應用 API ​

createApp() ​

建立應用程式例項。

• 型別

  ts

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

• 詳情

  第一個引數是根元件。第二個可選引數是要傳遞給根元件的 props。

• 示例

  帶有內聯根元件

  js

  import { createApp } from 'vue'
  
  const app = createApp({
    /* root component options */
  })

  帶有匯入的元件

  js

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

• 另請參閱 指南 - 建立 Vue 應用程式

createSSRApp() ​

在SSR Hydration模式下建立應用程式例項。用法與createApp()完全相同。

app.mount() ​

將應用程式例項掛載到一個容器元素上。

• 型別

  ts

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

• 詳情

  引數可以是實際的DOM元素或CSS選擇器（將使用第一個匹配的元素）。返回根元件例項。

  如果元件定義了模板或渲染函式，它將替換容器內的任何現有DOM節點。否則，如果可用執行時編譯器，將使用容器的innerHTML作為模板。

  在SSR Hydration模式下，它將初始化容器內現有的DOM節點。如果存在不匹配，現有DOM節點將被調整為匹配預期輸出。

  對於每個應用程式例項，mount()只能呼叫一次。

• 示例

  js

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

  也可以掛載到實際的DOM元素

  js

  app.mount(document.body.firstChild)

app.unmount() ​

解除安裝已掛載的應用程式例項，觸發應用程式元件樹中所有元件的解除安裝生命週期鉤子。

• 型別

  ts

  interface App {
    unmount(): void
  }

app.onUnmount() ​

註冊一個回撥，在應用程式解除安裝時被呼叫。

• 型別

  ts

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

app.component() ​

如果傳遞了名稱字串和元件定義，則註冊一個全域性元件；如果只傳遞了名稱，則檢索已註冊的一個。

• 型別

  ts

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

• 示例

  js

  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() ​

如果傳遞了名稱字串和指令定義，則註冊一個全域性自定義指令；如果只傳遞了名稱，則檢索已註冊的一個。

• 型別

  ts

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

• 示例

  js

  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() ​

安裝一個外掛。

• 型別

  ts

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

• 詳情

  期望外掛作為第一個引數，可選的外掛選項作為第二個引數。

  外掛可以是一個帶有install()方法的物件，或者是一個將被用作install()方法的函式。選項（app.use()的第二個引數）將被傳遞給外掛上的install()方法。

  當對同一外掛多次呼叫app.use()時，該外掛將只安裝一次。

• 示例

  js

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

• 另請參閱 外掛

app.mixin() ​

應用一個全域性混入（僅限於應用程式）。全域性混入將包含的選項應用於應用程式中的每個元件例項。

• 型別

  ts

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

app.provide() ​

為應用程式內部的所有子元件提供一個可以注入的值。

• 型別

  ts

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

• 詳情

  期望注入鍵作為第一個引數，提供的值作為第二個。返回應用程式例項本身。

• 示例

  js

  import { createApp } from 'vue'
  
  const app = createApp(/* ... */)
  
  app.provide('message', 'hello')

  在應用程式中的元件內部

  js

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

  js

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

• 另請參閱

  • 提供/注入
  • 應用級提供
  • app.runWithContext()

app.runWithContext() ​

• 僅在3.3+版本中支援

以當前應用為注入上下文執行回撥。

• 型別

  ts

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

• 詳情

  期望一個回撥函式並立即執行回撥。在回撥的同步呼叫過程中，inject()呼叫能夠從當前應用提供的值中查詢注入，即使在沒有當前活動的元件例項的情況下。回撥函式的返回值也將被返回。

• 示例

  js

  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
  }

• 示例

  在外掛內部進行版本檢查

  js

  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 ​

為從應用內部傳播的未捕獲錯誤分配一個全域性處理程式。

• 型別

  ts

  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）將是一個縮短的程式碼而不是完整的資訊字串。您可以在生產錯誤程式碼參考中找到程式碼到字串的對映。

• 示例

  js

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

app.config.warnHandler ​

為Vue的執行時警告分配一個自定義處理程式。

• 型別

  ts

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

• 詳情

  警告處理程式接收警告訊息作為第一個引數，源元件例項作為第二個引數，以及一個元件跟蹤字串作為第三個引數。

  它可以用來過濾掉特定的警告以減少控制檯冗餘。所有Vue警告應在開發過程中解決，因此此功能僅建議在除錯會話中用於關注許多警告中的特定警告，除錯完成後應刪除。

  TIP

  警告僅在開發期間起作用，因此此配置在生產模式下被忽略。

• 示例

  js

  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）根據每個元件覆蓋這些選項。

app.config.compilerOptions.isCustomElement ​

指定一個檢查方法來識別原生自定義元素。

• 型別： (tag: string) => boolean

• 詳情

  如果標籤應該被處理為原生自定義元素，則應返回true。對於匹配的標籤，Vue將其渲染為原生元素，而不是嘗試將其解析為Vue元件。

  在此函式中不需要匹配原生HTML和SVG標籤 - Vue的解析器會自動識別它們。

• 示例

  js

  // 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)。

• 示例

  js

  app.config.compilerOptions.whitespace = 'preserve'

app.config.compilerOptions.delimiters ​

調整模板中用於文字插值的定界符。

• 型別： [string, string]

• 預設： ['{{', '}}']

• 詳情

  這通常用於避免與也使用mustache語法的伺服器端框架衝突。

• 示例

  js

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

app.config.compilerOptions.comments ​

調整模板中HTML註釋的處理。

• 型別： boolean

• 預設： false

• 詳情

  預設情況下，Vue會在生產中刪除註釋。將此選項設定為true將強制Vue即使在生產中也保留註釋。在開發期間始終保留註釋。此選項通常用於Vue與其他依賴於HTML註釋的庫一起使用時。

• 示例

  js

  app.config.compilerOptions.comments = true

app.config.globalProperties ​

一個可以用於註冊全域性屬性的物件，這些屬性可以在應用中任何元件例項上訪問。

• 型別

  ts

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

• 詳情

  這是Vue 2的Vue.prototype的替代品，在Vue 3中不再存在。像任何全域性屬性一樣，應該謹慎使用。

  如果全域性屬性與元件自身的屬性衝突，則元件自身的屬性具有更高的優先順序。

• 用法

  js

  app.config.globalProperties.msg = 'hello'

  這使得msg在應用中任何元件模板內部都可用，並且在任何元件例項的this上也可用。

  js

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

• 另請參閱 指南 - 增強全域性屬性

app.config.optionMergeStrategies ​

一個物件，用於定義自定義元件選項的合併策略。

• 型別

  ts

  interface AppConfig {
    optionMergeStrategies: Record<string, OptionMergeFunction>
  }
  
  type OptionMergeFunction = (to: unknown, from: unknown) => any

• 詳情

  一些外掛/庫透過注入全域性混入提供了對自定義元件選項的支援。當需要從多個來源（例如混入或元件繼承）"合併"相同的選項時，這些選項可能需要特殊的合併邏輯。

  可以透過將合併策略函式賦值到app.config.optionMergeStrategies物件（使用選項的名稱作為鍵）來為自定義選項註冊合併策略函式。

  合併策略函式接收父例項和子例項上定義的該選項的值作為前兩個引數。

• 示例

  js

  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

• 示例

  js

  app.config.idPrefix = 'my-app'

  js

  // 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，即使在生產模式下，未處理的錯誤也會被丟擲。