Vue.js

Внешний вид

Содержание

Application API ​

createApp() ​

Создаёт экземпляр приложения.

  • Тип

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

  • Подробности

    Первым аргументом является корневой компонент. Вторым необязательным аргументом являются входные параметры, которые должны быть переданы корневому компоненту.

  • Пример

    Со встроенным корневым компонентом:

    js
    import { createApp } from 'vue'

const app = createApp({
  /* параметры корневого компонента */
})

    С импортируемым компонентом:

    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 внутри контейнера. В противном случае, если доступен runtime компилятор, в качестве шаблона будет использоваться innerHTML.

    В режиме гидратации SSR гидратирует существующие узлы 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() ​

Регистрирует коллбэк, который будет вызван при размонтировании компонента.

  • Type

    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({})

// регистрация с объектом настроек
app.component('my-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({
  /* ... */
})

// регистрация (объект директивы)
app.directive('my-directive', {
  /* хуки директивы */
})

// регистрация (определение директивы с помощью функции)
app.directive('my-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() ​

Применяет примесь (mixin) ко всей области приложения. Глобальный миксин применяет включенные в него опции к каждому экземпляру компонента в приложении.

Не рекомендуется

Миксины поддерживаются во Vue 3 в основном для обратной совместимости, что связано с их широким использованием в библиотеках экосистемы. Использование миксинов, особенно глобальных, следует избегать.

Для повторного использования логики предпочтите Composables.

  • Тип

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

  • Поддерживается только в 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('Для данного плагина требуется Vue 3')
    }
  }
}

  • См. также Глобальное API - version

app.config ​

Каждый экземпляр приложения предоставляет объект config, содержащий конфигурацию приложения. Перед монтированием приложения можно изменить его свойства (описанные ниже).

js
import { createApp } from 'vue'

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

console.log(app.config)

app.config.errorHandler ​

Назначает глобальный обработчик для не перехваченных ошибок, возникающих в приложении.

  • Тип

    ts
    interface AppConfig {
  errorHandler?: (
    err: unknown,
    instance: ComponentPublicInstance | null,
    // `info` - это специфическая для Vue информация об ошибке,
    // например, в каком хуке жизненного цикла возникла ошибка
    info: string
  ) => void
}

  • Подробности

    Обработчик ошибки получает три аргумента: ошибку, экземпляр компонента, в котором произошла ошибка, и строку, определяющую тип источника ошибки.

    Он может фиксировать ошибки от следующих источников:

    • Отрисовка компонентов
    • Слушатели событий
    • Хуки жизненного цикла
    • функция setup()
    • Наблюдатели
    • Хуки пользовательских директив
    • Хуки анимаций

    Совет

    В production, третий аргумент (info) будет содержать код вместо полного названия источника. Соответствие кода и названия можно найти в Руководстве по кодам ошибок.

  • Пример

    js
    app.config.errorHandler = (err, instance, info) => {
  // обработка ошибки, например, передать в сервис логирования
}

app.config.warnHandler ​

Назначение пользовательского обработчика предупреждений, возникающих во время выполнения Vue.

  • Тип

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

  • Подробности

    В качестве первого аргумента обработчик предупреждения получает сообщение о предупреждении, в качестве второго — экземпляр исходного компонента, в качестве третьего - trace строку компонента.

    С его помощью можно отфильтровать конкретные предупреждения, чтобы уменьшить количество сообщений в консоли. Все предупреждения Vue должны быть устранены в процессе разработки, поэтому этот фильтр рекомендуется использовать только в сеансах отладки, чтобы сосредоточиться на конкретных предупреждениях из множества, и должен быть удалён по окончании отладки.

    Совет

    Предупреждения работают только во время разработки, поэтому в рабочем режиме эта конфигурация игнорируется.

  • Пример

    js
    app.config.warnHandler = (msg, instance, trace) => {
  // `trace` - трассировка иерархии компонентов
}

app.config.performance ​

Установите значение true, чтобы включить отслеживание производительности компонентов при инициализации, компиляции, отрисовке и исправлениях в devtool панели браузера perfomance/timeline. Работает только в режиме разработки и в браузерах, поддерживающих API performance.mark.

app.config.compilerOptions ​

Настройка параметров runtime компилятора. Значения, установленные для этого объекта, будут передаваться компилятору шаблонов в браузере и влиять на каждый компонент сконфигурированного приложения. Обратите внимание, что вы также можете переопределить эти параметры для каждого компонента, используя опцию compilerOptions

Важно

Эта опция конфигурации учитывается только при использовании полной сборки (т.е. автономной vue.js, которая может компилировать шаблоны в браузере). Если вы используете сборку только во время выполнения с настройкой сборки, опции компилятора должны передаваться в @vue/compiler-dom через конфигурации инструмента сборки.

app.config.compilerOptions.isCustomElement ​

Определяет метод проверки для распознавания нативных пользовательских элементов.

  • Тип (tag: string) => boolean

  • Подробности

    Должен возвращать true, если тег должен рассматриваться как нативный пользовательский элемент. Для совпавшего тега Vue отобразит его как пользовательский элемент, а не попытается разрешить его как компонент Vue.

    Нативные HTML и SVG теги в этой функции указывать не нужно — парсер Vue распознаёт их автоматически.

  • Пример

    js
    // рассматривать все теги, начинающиеся с 'ion-', как пользовательские элементы
app.config.compilerOptions.isCustomElement = (tag) => {
  return tag.startsWith('ion-')
}

  • См. также Vue и Веб-компоненты

app.config.compilerOptions.whitespace ​

Настраивает поведение обработки символов пробела в шаблоне.

  • Тип 'condense' | 'preserve'

  • По умолчанию 'condense'

  • Подробности

    Vue удаляет / сжимает пробельные символы в шаблонах для получения более эффективного компилированного вывода. По умолчанию используется стратегия "condense" со следующим поведением:

    1. Начальные/конечные пробельные символы внутри элемента сжимает в один пробел.
    2. Пробельные символы между элементами, содержащими новые строки, удаляются.
    3. Последовательные пробельные символы в текстовых узлах сжимаются в один пробел.

    Установка этого параметра в значение 'preserve' отключает (2) и (3).

  • Пример

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

app.config.compilerOptions.delimiters ​

Настраивает разделители, используемые для интерполяции текста в шаблоне.

  • Тип [string, string]

  • По умолчанию ['{{', '}}']

  • Подробности

    Обычно это используется для того, чтобы избежать конфликта с серверными фреймворками, которые также используют синтаксис mustache (синтаксиса из двойных фигурных скобок).

  • Пример

    js
    // Разделители изменены на шаблонный стиль строки ES6
app.config.compilerOptions.delimiters = ['${', '}']

app.config.compilerOptions.comments ​

Настройка обработки HTML-комментариев в шаблонах.

  • Тип boolean

  • По умолчанию false

  • Подробности

    По умолчанию Vue будет удалять комментарии в production сборке. Установка этого значения в true заставит Vue сохранять комментарии даже в продакшене. Во время разработки комментарии всегда сохраняются. Эта опция обычно используется, когда Vue используется с другими библиотеками, которые полагаются на HTML-комментарии.

  • Пример

    js
    app.config.compilerOptions.comments = true

app.config.globalProperties ​

Объект, который может использоваться для регистрации глобальных свойств, доступ к которым может быть получен для любого экземпляра компонента внутри приложения.

  • Тип

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

  • Подробности

    Это замена Vue.prototype из Vue 2, которой больше нет во Vue 3. Как и всё глобальное, его следует использовать осторожно.

    Если глобальное свойство конфликтует с собственным свойством компонента, то собственное свойство компонента будет иметь более высокий приоритет.

  • Использование

    js
    app.config.globalProperties.msg = 'привет'

    Это делает msg доступным внутри любого шаблона компонента в приложении, а также на this любого экземпляра компонента:

    js
    export default {
  mounted() {
    console.log(this.msg) // 'привет'
  }
}

  • См. также Руководство — Расширение глобальных свойств

app.config.optionMergeStrategies ​

Объект для определения стратегий объединения для пользовательских опций компонентов.

  • Тип

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

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

  • Подробности

    Некоторые плагины/библиотеки добавляют поддержку пользовательских опций компонентов (путём инъекции глобальных миксинов). Для таких опций может потребоваться специальная логика объединения, когда одна и та же опция должна быть "смержена" из нескольких источников (например, миксинов или наследования компонентов).

    Функцию стратегии слияния можно зарегистрировать для пользовательской опции, назначив ее в объекте app.config.optionMergeStrategies, используя в качестве ключа имя опции.

    Функция стратегии слияния получает в качестве первого и второго аргументов значение этой опции, определенной для родительского и дочернего экземпляров соответственно.

  • Пример

    js
    const app = createApp({
  // собственная опция
  msg: 'Vue',
  // опция из примеси (mixin)
  mixins: [
    {
      msg: 'Привет '
    }
  ],
  mounted() {
    // объединенные опции, доступные в this.$options
    console.log(this.$options.msg)
  }
})

// определение пользовательской стратегии слияния для `msg`.
app.config.optionMergeStrategies.msg = (parent, child) => {
  return (parent || '') + (child || '')
}

app.mount('#app')
// logs 'Привет Vue'

  • См. также Экземпляр компонента - $options

app.config.idPrefix ​

Настройте префикс для всех идентификаторов, сгенерированных через useId() внутри этого приложения.

  • Тип: string

  • По умолчанию: undefined

  • Пример

    js
    app.config.idPrefix = 'my-app'
    js
    // в компоненте:
const id1 = useId() // 'my-app:0'
const id2 = useId() // 'my-app:1'

app.config.throwUnhandledErrorInProduction ​

Принудительно обрабатывает необработанные ошибки в продакшен режиме.

  • Тип: boolean

  • По умолчанию: false

  • Подробности

    По умолчанию ошибки, возникающие внутри приложения Vue, но не обработанные явно, имеют разное поведение в режимах разработки и продакшена:

    • В процессе разработки ошибка выбрасывается и может привести к краху приложения. Это сделано для того, чтобы сделать ошибку более заметной, чтобы ее можно было заметить и исправить во время разработки.

    • В продакшене ошибка будет выведена только в консоли, чтобы минимизировать воздействие на конечных пользователей. Однако это может помешать службам мониторинга ошибок отлавливать ошибки, которые происходят только в продакшене.

    Если установить app.config.throwUnhandledErrorInProduction в true, то необработанные ошибки будут выданы даже в продакшен режиме.

Исправить эту страницу на GitHub