Skip to content

Globální API: Aplikace

createApp()

Vytvoří instanci aplikace.

  • Typ

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

    První parametr je root komponenta. Druhý volitelný parametr jsou vlastnosti, které se mají root komponentě předat.

  • Příklad

    Inline root komponenta:

    js
    import { createApp } from 'vue'
    
    const app = createApp({
      /* vlastnosti root komponenty */
    })

    Importovaná root komponenta:

    js
    import { createApp } from 'vue'
    import App from './App.vue'
    
    const app = createApp(App)
  • Viz také: Průvodce - Vytvoření Vue aplikace

createSSRApp()

Vytvoří instanci aplikace v režimu SSR hydratace. Použití je zcela totožné jako u createApp().

app.mount()

Připojí (mount) instanci aplikace do mateřského elementu.

  • Typ

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

    Parametrem může být buď skutečný DOM element nebo CSS selektor (bude použit první vyhovující element). Vrací instanci root komponenty.

    Pokud má komponenta definovanou šablonu nebo vykreslovací funkci, nahradí všechny existující DOM elementy uvnitř kontejneru. Jinak, pokud je k dispozici runtime kompilátor, bude jako šablona použito innerHTML kontejneru.

    V režimu SSR hydratace provede hydrataci existujících DOM elementů uvnitř kontejneru. Pokud existuje nesoulad, existující DOM elementy budou změněny tak, aby odpovídaly očekávanému výstupu.

    Pro každou instanci aplikace lze mount() zavolat pouze jednou.

  • Příklad

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

    Aplikaci lze připojit i ke konkrétnímu DOM elementu:

    js
    app.mount(document.body.firstChild)

app.unmount()

Odpojí (unmount) připojenou instanci aplikace a spustí unmount lifecycle hooky pro všechny komponenty v aplikačním stromu komponent.

  • Typ

    ts
    interface App {
      unmount(): void
    }

app.onUnmount()

Registruje callback, který se má zavolat, když je aplikace odpojena (unmounted).

  • Type

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

app.component()

Registruje globální komponentu, pokud je zadán jak název, tak definice komponenty, nebo vrátí již registrovanou komponentu, pokud je zadán pouze název.

  • Typ

    ts
    interface App {
      component(name: string): Component | undefined
      component(name: string, component: Component): this
    }
  • Příklad

    js
    import { createApp } from 'vue'
    
    const app = createApp({})
    
    // zaregistrovat objekt vlastností
    app.component('my-component', {
      /* ... */
    })
    
    // získat již registrovanou komponentu
    const MyComponent = app.component('my-component')
  • Viz také Registrace komponent

app.directive()

Registruje globální vlastní direktivu, pokud je zadán jak název, tak definice direktivy, nebo získá již registrovanou direktivu, pokud je zadán pouze název.

  • Typ

    ts
    interface App {
      directive(name: string): Directive | undefined
      directive(name: string, directive: Directive): this
    }
  • Příklad

    js
    import { createApp } from 'vue'
    
    const app = createApp({
      /* ... */
    })
    
    // zaregistrovat direktivu (objektová notace)
    app.directive('my-directive', {
      /* vlastní hooks direktivy */
    })
    
    // zaregistrovat direktivu (zkrácená funkční notace)
    app.directive('my-directive', () => {
      /* ... */
    })
    
    // získat již registrovanou direktivu
    const myDirective = app.directive('my-directive')
  • Viz také Vlastní direktivy

app.use()

Nainstaluje plugin.

  • Typ

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

Očekává plugin jako první parametr a volitelně vlastnosti pluginu jako druhý parametr.

Plugin může být buď objekt s metodou install(), nebo pouze funkce, která bude použita jako metoda install(). Vlastnosti (druhý parametr app.use()) budou do metody install() předány.

Když je na stejný plugin voláno app.use() vícekrát, plugin bude nainstalován pouze jednou.

  • Příklad

    js
    import { createApp } from 'vue'
    import MyPlugin from './plugins/MyPlugin'
    
    const app = createApp({
      /* ... */
    })
    
    app.use(MyPlugin)
  • Viz také Pluginy

app.mixin()

Použije globální mixin (omezený na aplikaci). Globální mixin aplikuje své obsažené vlastnosti na každou instanci komponenty v aplikaci.

Nedoporučeno

Mixins jsou ve Vue 3 podporovány hlavně z důvodu zpětné kompatibility kvůli jejich rozsáhlému používání v knihovnách ekosystému. Používání mixins, zejména globálních, byste se měli ve vlastním kódu aplikace vyhnout.

Pro znovupoužití logiky je lepší použít Composables.

  • Typ

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

app.provide()

Poskytne hodnotu, která může být implementována (injected) do všech komponent potomků v rámci aplikace.

  • Typ

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

    Očekává klíč (injection key) jako první a poskytnutou hodnotu jako druhý parametr. Vrací instanci aplikace jako takovou.

  • Příklad

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

    Uvnitř komponenty v aplikaci:

js
import { inject } from 'vue'

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

app.runWithContext()

  • Podporováno až od verze 3.3+

Spustí callback s aktuální aplikací jako kontextem (injection context).

  • Typ

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

    Očekává callback funkci a okamžitě ji spustí. Během synchronního volání callbacku mohou volání inject() vyhledávat hodnoty poskytované v rámci aktuální aplikace, i když momentálně neexistuje žádná aktivní instance komponenty. Návratová hodnota callback funkce bude také vrácena.

  • Příklad

    js
    import { inject } from 'vue'
    
    app.provide('id', 1)
    
    const injected = app.runWithContext(() => {
      return inject('id')
    })
    
    console.log(injected) // 1

app.version

Poskytuje verzi Vue, se kterou byla aplikace vytvořena. To se hodí uvnitř pluginů, kde můžete potřebovat podmíněnou logiku založenou na různých verzích Vue.

  • Typ

    ts
    interface App {
      version: string
    }
  • Příklad

    Kontrola verze uvnitř pluginu:

    js
    export default {
      install(app) {
        const version = Number(app.version.split('.')[0])
        if (version < 3) {
          console.warn('Tento plugin vyžaduje Vue 3')
        }
      }
    }
  • Viz také: Globální API - version

app.config

Každá instance aplikace vystavuje objekt config, který obsahuje konfigurační nastavení dané aplikace. Před nasazením vaší aplikace můžete upravit její vlastnosti (dokumentováno níže).

js
import { createApp } from 'vue'

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

console.log(app.config)

app.config.errorHandler

Přiřadí globální handler pro nezachycené chyby propagované z aplikace.

  • Typ

    ts
    interface AppConfig {
      errorHandler?: (
        err: unknown,
        instance: ComponentPublicInstance | null,
        // `info` je informace o Vue chybě,
        // např. ve kterém lifecycle hooku chyba vznikla
        info: string
      ) => void
    }
  • Podrobnosti

    Error handler přijímá tři parametry: objekt chyby, instanci komponenty, která chybu vyvolala, a informační string, který specifikuje typ zdroje chyby.

    Může zachytit chyby z následujících zdrojů:

    • Vykreselení komponenty
    • Event handlery
    • Metody životního cyklu
    • Funkce setup()
    • Watchery
    • Vlastní direktivy
    • Transition metody

    TIP

    V produkčním prostředí bude třetí parametr (info) zkrácený kód místo kompletního řetězce s informací. Na mapování kódů na texty se můžete podívat do Reference chybových kódů v produkci.

  • Příklad

    js
    app.config.errorHandler = (err, instance, info) => {
      // zpracování chyby, např. nahlášení službě
    }

app.config.warnHandler

Přiřadí vlastní handler pro Vue runtime varování.

  • Typ

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

    Warning handler přijímá jako první parametr zprávu varování, jako druhý parametr instanci zdrojové komponenty a jako třetí parametr trace string.

    Může být použit k odfiltrování konkrétních varování pro snížení množství výpisů do konzole. Všechna Vue varování by měla být řešena během vývoje, takže se použití doporučuje pouze během ladění se zaměřením na jedno konkrétní varování po skončení debuggingu metodu opět odstranit.

    TIP

    Varování fungují pouze během vývoje, takže tato konfigurace je v produkčním režimu ignorována.

  • Příklad

    js
    app.config.warnHandler = (msg, instance, trace) => {
      // `trace` je trasování hierarchie komponent
    }

app.config.performance

Nastavte tuto vlastnost na true, abyste povolili sledování výkonu inicializace, kompilace, vykreslování a běhových úprav komponent v panelu výkon/časová osa (performance/timeline) nástroje pro vývojáře (devtools) v prohlížeči. Funguje pouze v režimu vývoje a v prohlížečích, které podporují rozhraní performance.mark.

app.config.compilerOptions

Runtime konfigurace vlastností překladače. Hodnoty nastavené v tomto objektu budou předány překladači šablon v prohlížeči a ovlivní každou komponentu v konfigurované aplikaci. Poznámka: Tyto možnosti lze také přepsat pro každou komponentu pomocí volby compilerOptions.

Důležité

Tato možnost konfigurace je možná pouze při použití plného buildu (tj. samostatného vue.js, který může v prohlížeči kompilovat šablony). Pokud používáte runtime-only build + build setup, vlastnosti překladače musí být předány do @vue/compiler-dom pomocí konfigurace build nástroje.

app.config.compilerOptions.isCustomElement

Definuje ověřovací metodu pro rozpoznání custom nativních prvků.

  • Typ: (tag: string) => boolean

  • Podrobnosti

    Metoda by měla vrátit true, pokud má být nějaký tag považován za nativní element. Odpovídající tag bude Vue vykreslovat nativně, místo aby se pokoušelo jej zpracovat jako Vue komponentu.

    Nativní HTML a SVG tagy není třeba v této funkci řešit - Vue parser je rozpozná automaticky.

  • Příklad

    js
    // pokládá všechny tagy, které začínají 'ion-', za custom nativní elementy
    app.config.compilerOptions.isCustomElement = (tag) => {
      return tag.startsWith('ion-')
    }
  • Viz také: Vue a Web Components

app.config.compilerOptions.whitespace

Upravuje chování manipulace s mezerami (whitespace) v šablonách.

  • Typ: 'condense' | 'preserve'

  • Výchozí hodnota: 'condense'

  • Podrobnosti

    Vue odstraňuje / zhušťuje bílé znaky v šablonách, aby byl vytvořený zkompilovaný výstup efektivnější. Výchozí strategie je „condense“ s následujícím chováním:

    1. Počáteční / koncové mezery uvnitř prvku jsou zhuštěny do jedné mezery.
    2. Mezery mezi prvky, které obsahují nové řádky, jsou odstraněny.
    3. Po sobě jdoucí mezery ve textových elementech jsou zhuštěny do jedné mezery.

    Nastavení této možnosti na 'preserve' zakáže (2) a (3).

  • Příklad

    js
    app.config.compilerOptions.whitespace = 'preserve'

app.config.compilerOptions.delimiters

Upravuje oddělovače používané pro textovou interpolaci ve šabloně.

  • Typ: [string, string]

  • Výchozí hodnota: ['{{', '}}']

  • Podrobnosti

    Toto se typicky používá pro předcházení konfliktům se serverovými frameworky, které také používají „mustache“ syntaxi.

  • Příklad

    js
    // Oddělovače změněny na ES6 styl šablon 
    app.config.compilerOptions.delimiters = ['${', '}']

app.config.compilerOptions.comments

Upravuje zpracování HTML komentářů ve šablonách.

  • Typ: boolean

  • Výchozí hodnota: false

  • Podrobnosti

    Ve výchozím nastavení Vue v produkčním prostředí komentáře odstraňuje. Nastavení této možnosti na true donutí Vue komentáře zachovávat i pro produkci. Během vývoje jsou komentáře zachovány vždy. Tato možnost se obvykle používá, když je Vue používáno s jinými knihovnami, které na HTML komentáře spoléhají.

  • Příklad

    js
    app.config.compilerOptions.comments = true

app.config.globalProperties

Objekt, který může být použit k registraci globálních vlastností, ke kterým lze přistupovat z jakéhokoli instance komponenty v rámci aplikace.

  • Typ

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

    Toto je náhrada za Vue.prototype z Vue 2, který již není ve Vue 3 přítomen. Stejně jako cokoli globálního, by měly být používány střídmě a s rozmyslem.

    Pokud dojde ke konfliktu názvů globální vlastnosti s vlastností komponenty, vlastnost uvnitř komponenty bude mít vyšší prioritu.

  • Použití

    js
    app.config.globalProperties.msg = 'ahoj'

Umožňí použití msg uvnitř kterékoli šablony a také na this libovolné instance komponenty:

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

app.config.optionMergeStrategies

Objekt pro definici strategií pro slučování custom vlastností komponenty.

  • Typ

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

    Některé pluginy / knihovny přidávají podporu pro custom vlastnosti komponent (implementací globálních mixins). Tyto vlastnosti mohou vyžadovat speciální logiku pro slučování, když je třeba „sloučit“ vlastnost z více zdrojů (např. mixins nebo dědičnosti komponenty).

    Funkce pro strategii slučování může být pro custom vlastnost zaregistrována jejím přiřazením na objekt app.config.optionMergeStrategies s použitím názvu vlastnosti jako klíče.

    Funkce přijímá hodnotu této vlastnosti definovanou na instancích komponenty rodiče a potomka jako první a druhý parametr.

  • Příklad

    js
    const app = createApp({
      // vlastnost z aplikace (self)
      msg: 'Vue',
      // vlastnost z mixinu
      mixins: [
        {
          msg: 'Ahoj '
        }
      ],
      mounted() {
        // sloučené volby vystavené na this.$options
        console.log(this.$options.msg)
      }
    })
    
    // definování strategie pro sloučení `msg`
    app.config.optionMergeStrategies.msg = (parent, child) => {
      return (parent || '') + (child || '')
    }
    
    app.mount('#app')
    // vypíše 'Ahoj Vue'
  • Viz také: Instance komponenty - $options

app.config.idPrefix

Nastavení prefixu pro všechny ID generované přes useId() uvnitř aplikace.

  • Typ: string

  • Výchozí hodnota: undefined

  • Příklad

    js
    app.config.idPrefix = 'my-app'
    js
    // v komponentně:
    const id1 = useId() // 'my-app:0'
    const id2 = useId() // 'my-app:1'

app.config.throwUnhandledErrorInProduction

Vynutí vyvolání neošetřených chyb v produkci.

  • Typ: boolean

  • Výchozí hodnota: false

  • Podrobnosti Ve výchozím nastavení se chyby vzniklé uvnitř Vue aplikace, které nejsou explicitně ošetřené, chovají jinak ve vývojovém a produkčním prostředí:

    • Při vývoji je chyba vyvolána (thrown) a může potenciálně celou aplikaci shodit. Je to proto, aby byla chyba více viditelná a mohla být během vývoje objevena a opravena.
    • V produkci bude chyba pouze zalogována do konzole, aby se minimalizoval dopad na koncové uživatele. Nicméně to může znamenat, že chyby, které se objevují pouze v produkci, nebudou zachycovány nástroji na monitoring. Nastavením app.config.throwUnhandledErrorInProduction na hodnotu true budou neošetřené chyby vyvolávány i v produkčním módu.
Globální API: Aplikace has loaded