Globální API: Aplikace
createApp()
Vytvoří instanci aplikace.
Typ
tsfunction 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:
jsimport { createApp } from 'vue' const app = createApp({ /* vlastnosti root komponenty */ })
Importovaná root komponenta:
jsimport { 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
tsinterface 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
jsimport { createApp } from 'vue' const app = createApp(/* ... */) app.mount('#app')
Aplikaci lze připojit i ke konkrétnímu DOM elementu:
jsapp.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
tsinterface App { unmount(): void }
app.onUnmount()
Registruje callback, který se má zavolat, když je aplikace odpojena (unmounted).
Type
tsinterface 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
tsinterface App { component(name: string): Component | undefined component(name: string, component: Component): this }
Příklad
jsimport { 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
tsinterface App { directive(name: string): Directive | undefined directive(name: string, directive: Directive): this }
Příklad
jsimport { 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
tsinterface 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
jsimport { 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
tsinterface 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
tsinterface 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
jsimport { 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'
}
}
app.runWithContext()
- Podporováno až od verze 3.3+
Spustí callback s aktuální aplikací jako kontextem (injection context).
Typ
tsinterface 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
jsimport { 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
tsinterface App { version: string }
Příklad
Kontrola verze uvnitř pluginu:
jsexport 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
tsinterface 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
jsapp.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
tsinterface 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
jsapp.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.
Typ:
boolean
Viz také: Průvodce - Výkon
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.
Pro
vue-loader
: předejte pomocí volbycompilerOptions
. Viz také jak jej nakonfigurovat vvue-cli
.Pro
vite
: předejte pomocí nastavení@vitejs/plugin-vue
.
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:
- Počáteční / koncové mezery uvnitř prvku jsou zhuštěny do jedné mezery.
- Mezery mezi prvky, které obsahují nové řádky, jsou odstraněny.
- 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
jsapp.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
jsapp.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
tsinterface 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í
jsapp.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
tsinterface 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
jsconst 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
jsapp.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 hodnotutrue
budou neošetřené chyby vyvolávány i v produkčním módu.