# Глобальное API

При использовании сборки с CDN доступ к функциям глобального API можно получить через глобальный объект Vue, например:

const { createApp, h, nextTick } = Vue
1

При использовании ES-модулей, их можно импортировать напрямую:

import { createApp, h, nextTick } from 'vue'
1

Глобальные функции для работы с реактивностью, такие как reactive и ref, задокументированы отдельно. Подробнее о них — в разделе API реактивности.

# createApp

Возвращает экземпляр приложения, который предоставляет контекст приложения. Всё дерево компонентов, смонтированное экземпляром приложения, имеет один и тот же контекст.

const app = createApp({})
1

После createApp можно цепочкой вызывать другие методы, список которых представлен в API приложения

# Аргументы

Первым аргументом функция получает объект настроек корневого компонента:

const app = createApp({
  data() {
    return {
      // ...
    }
  },
  methods: {
    // ...
  },
  computed: {
    // ...
  }
  // ...
})
1
2
3
4
5
6
7
8
9
10
11
12
13
14

Вторым аргументом можно передать корневые входные параметры приложения:

const app = createApp(
  {
    props: ['username']
  },
  { username: 'Evan' }
)
1
2
3
4
5
6
<div id="app">
  <!-- Отобразит 'Evan' -->
  {{ username }}
</div>
1
2
3
4

Корневые входные параметры — необработанные входные параметры, аналогичные тем, что передаются в h для создания VNode. В дополнение к входным параметрам компонента, они могут включать атрибуты и слушатели событий, которые будут применяться к корневому компоненту.

# Типы

interface Data {
  [key: string]: unknown
}

export type CreateAppFunction<HostElement> = (
  rootComponent: PublicAPIComponent,
  rootProps?: Data | null
) => App<HostElement>
1
2
3
4
5
6
7
8

# h

Возвращает «виртуальную ноду» VNode: простой объект с информацией о том, какой узел должен отобразиться на странице, включая описание дочерних узлов. Предназначается для написания render-функций вручную:

render() {
  return h('h1', {}, 'Какой-то заголовок')
}
1
2
3

# Аргументы

Принимает три аргумента: type, props и children

# type

  • Тип: String | Object | Function

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

    Имя HTML-тега, компонента, асинхронного или функционального компонента. Если указать функцию, возвращающую null — будет отрисовываться комментарий. Это обязательный параметр.

# props

  • Тип: Object

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

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

# children

  • Тип: String | Array | Object

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

    Дочерние VNode, созданные с помощью h() или с использованием строк (для получения «текстовых VNode») или объект со слотами. Опциональный параметр.

    h('div', {}, [
      'Какой-то текст идёт первым.',
      h('h1', 'Заголовок'),
      h(MyComponent, {
        someProp: 'foobar'
      })
    ])
    
    1
    2
    3
    4
    5
    6
    7

# defineComponent

С точки зрения реализации, defineComponent лишь возвращает переданный объект. Однако, с точки зрения типизации, возвращаемое значение имеет синтетический тип конструктора для создаваемых render-функций, TSX и поддержки инструментария IDE.

# Аргументы

Объект с опциями компонента

import { defineComponent } from 'vue'

const MyComponent = defineComponent({
  data() {
    return { count: 1 }
  },
  methods: {
    increment() {
      this.count++
    }
  }
})
1
2
3
4
5
6
7
8
9
10
11
12

Или функция setup, имя которой будет использовано в качестве имени компонента

import { defineComponent, ref } from 'vue'

const HelloWorld = defineComponent(function HelloWorld() {
  const count = ref(0)
  return { count }
})
1
2
3
4
5
6

# defineAsyncComponent

Создаёт асинхронный компонент, который будет загружен только при необходимости.

# Аргументы

Обычно в defineAsyncComponent передают функцию-фабрику, возвращающую Promise. Его коллбэк resolve должен вызываться при получении компонента с сервера. Также может быть вызван reject(reason) для обозначения неудачи при загрузке.

import { defineAsyncComponent } from 'vue'

const AsyncComp = defineAsyncComponent(() =>
  import('./components/AsyncComponent.vue')
)

app.component('async-component', AsyncComp)
1
2
3
4
5
6
7

При локальной регистрации компонента можно также указать функцию напрямую, которая вернёт Promise:

import { createApp, defineAsyncComponent } from 'vue'

createApp({
  // ...
  components: {
    AsyncComponent: defineAsyncComponent(() =>
      import('./components/AsyncComponent.vue')
    )
  }
})
1
2
3
4
5
6
7
8
9
10

Для продвинутого использования defineAsyncComponent может принимать объект:

import { defineAsyncComponent } from 'vue'

const AsyncComp = defineAsyncComponent({
  // Функция-фабрика
  loader: () => import('./Foo.vue'),
  // Компонент загрузки, используемый во время загрузки асинхронного компонента
  loadingComponent: LoadingComponent,
  // Компонент ошибки, используемый в случае неудачи при загрузке
  errorComponent: ErrorComponent,
  // Ожидание перед показом компонента загрузки. По умолчанию: 200ms.
  delay: 200,
  // Компонент ошибки будет отображаться, если был указан таймаут
  // и время ожидания превышено. По умолчанию: Infinity.
  timeout: 3000,
  // Определение, является ли компонент suspensible. По умолчанию: true.
  suspensible: false,
  /**
   * Обработчик ошибки
   * @param {*} error — объект ошибки с сообщением
   * @param {*} retry — функция, определяющая повторные попытки загрузки при promise rejects
   * @param {*} fail — конец обработки ошибок
   * @param {*} attempts — максимальное число повторных попыток
   */
  onError(error, retry, fail, attempts) {
    if (error.message.match(/fetch/) && attempts <= 3) {
      // повтор при ошибках загрузки, максимум 3 попытки
      retry()
    } else {
      // обратите внимание, что retry/fail аналогичны resolve/reject для promise:
      // один из них должен быть вызван для продолжения обработки ошибок.
      fail()
    }
  },
})
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

См. также: Динамические и асинхронные компоненты

# defineCustomElement 3.2+

Метод принимает такой же аргумент, что и defineComponent, но возвращает нативный пользовательский элемент (opens new window), который может использоваться с любым фреймворком или без фреймворка вообще.

Пример использования:

<my-vue-element></my-vue-element>
1
import { defineCustomElement } from 'vue'

const MyVueElement = defineCustomElement({
  // обычные опции компонента Vue
  props: {},
  emits: {},
  template: `...`,

  // ТОЛЬКО ДЛЯ defineCustomElement: CSS, внедряемый в shadow root
  styles: [`/* inlined css */`]
})

// Регистрация пользовательского элемента.
// После регистрации все теги `<my-vue-element>` на странице будут обновлены.
customElements.define('my-vue-element', MyVueElement)

// Также есть возможность программно инстанцировать элемент:
// (это может быть сделано только после регистрации)
document.body.appendChild(
  new MyVueElement({
    // стартовые входные параметры (опционально)
  })
)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

Более подробную информации о создании веб-компонентов с помощью Vue, в том числе при использовании однофайловых компонентов, смотрите в разделе Vue и веб-компоненты.

# resolveComponent

ВНИМАНИЕ

resolveComponent можно использовать только внутри функций render или setup.

Позволяет разрешить компонент по его имени, если он доступен в текущем экземпляре приложения.

Возвращает Component или аргумент name, если не был найден.

const app = createApp({})

app.component('MyComponent', {
  /* ... */
})
1
2
3
4
5
import { resolveComponent } from 'vue'

render() {
  const MyComponent = resolveComponent('MyComponent')
}
1
2
3
4
5

# Аргументы

Принимает один аргумент: name

# name

  • Тип: String

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

    Имя загружаемого компонента.

# resolveDynamicComponent

ВНИМАНИЕ

resolveDynamicComponent можно использовать только внутри функций render или setup.

Позволяет разрешить компонент по аналогичному механизму, как в <component :is="">.

Возвращает Component или новую созданную VNode с именем компонента в качестве тега. Отобразит предупреждение, если Component не был найден.

import { resolveDynamicComponent } from 'vue'

render () {
  const MyComponent = resolveDynamicComponent('MyComponent')
}
1
2
3
4
5

# Аргументы

Принимает один аргумент: component

# component

# resolveDirective

ВНИМАНИЕ

resolveDirective можно использовать только внутри функций render или setup.

Позволяет разрешить директиву по её имени, если она доступна в текущем экземпляре приложения.

Возвращает Directive или undefined, если директива не найдена.

const app = createApp({})

app.directive('highlight', {})
1
2
3
import { resolveDirective } from 'vue'

render () {
  const highlightDirective = resolveDirective('highlight')
}
1
2
3
4
5

# Аргументы

Принимает один аргумент: name

# name

  • Тип: String

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

    Имя загружаемой директивы.

# withDirectives

ВНИМАНИЕ

withDirectives можно использовать только внутри функций render или setup.

Позволяет применять директивы к VNode. Возвращает VNode с применёнными директивами.

import { withDirectives, resolveDirective } from 'vue'

const foo = resolveDirective('foo')
const bar = resolveDirective('bar')

return withDirectives(h('div'), [
  [foo, this.x],
  [bar, this.y]
])
1
2
3
4
5
6
7
8
9

# Аргументы

Принимает два аргумента: vnode и directives.

# vnode

  • Тип: vnode

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

    Виртуальная нода, обычно созданная с помощью h().

# directives

  • Тип: Array

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

    Массив директив.

    Каждая директива сама по себе является массивом, что позволяет объявлять до 4 индексов, как показано в следующих примерах.

    • [directive] — Директива сама по себе. Обязательно.
    const MyDirective = resolveDirective('MyDirective')
    const nodeWithDirectives = withDirectives(h('div'), [[MyDirective]])
    
    1
    2
    • [directive, value] — То же, что и выше, плюс значение с типом any, которое присваивается директиве.
    const MyDirective = resolveDirective('MyDirective')
    const nodeWithDirectives = withDirectives(h('div'), [[MyDirective, 100]])
    
    1
    2
    • [directive, value, arg] — То же, что и выше, плюс аргумент с типом String, т.е. click в v-on:click.
    const MyDirective = resolveDirective('MyDirective')
    const nodeWithDirectives = withDirectives(h('div'), [
      [MyDirective, 100, 'click']
    ])
    
    1
    2
    3
    4
    • [directive, value, arg, modifiers] — То же, что и выше, плюс пары key: value с типом Object, определяющие любые модификаторы.
    const MyDirective = resolveDirective('MyDirective')
    const nodeWithDirectives = withDirectives(h('div'), [
      [MyDirective, 100, 'click', { prevent: true }]
    ])
    
    1
    2
    3
    4

# createRenderer

Функция createRenderer принимает 2 общих аргумента: HostNode и HostElement, соответствующие типам Node и Element в окружении.

Например, для runtime-DOM HostNode будет интерфейсом DOM Node, а HostElement будет интерфейсом DOM Element.

Пользовательские рендеры могут передавать специфичные для платформы типы следующим образом:

import { createRenderer } from 'vue'

const { render, createApp } = createRenderer<Node, Element>({
  patchProp,
  ...nodeOps
})
1
2
3
4
5
6

# Аргументы

Принимает два аргумента: HostNode и HostElement

# HostNode

  • Тип: Node

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

    Узел в окружении.

# HostElement

  • Тип: Element

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

    Элемент в окружении.

# nextTick

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

import { createApp, nextTick } from 'vue'

const app = createApp({
  setup() {
    const message = ref('Привет!')
    const changeMessage = async newMessage => {
      message.value = newMessage
      await nextTick()
      console.log('Теперь DOM обновлён')
    }
  }
})
1
2
3
4
5
6
7
8
9
10
11
12

См. также: метод экземпляра $nextTick

# mergeProps

Объединяет несколько объектов, содержащих входные параметры VNode. Возвращает новый объект — все передаваемые аргументами объекты останутся без изменений.

Можно передавать любое количество объектов, при этом приоритет будет у свойств, идущих позднее. Слушатели событий будут обрабатываться специальным образом, как class или style, значения этих свойств будут объединяться, а не перезаписываются.

import { h, mergeProps } from 'vue'

export default {
  inheritAttrs: false,

  render() {
    const props = mergeProps(
      {
        // Класс будет объединён с любым другим классом из $attrs
        class: 'active'
      },
      this.$attrs
    )

    return h('div', props)
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# useCssModule

Предупреждение

useCssModule можно использовать только внутри функций render или setup.

Позволяет в функции setup получить доступ к CSS-модулям однофайлового компонента:

<script>
import { h, useCssModule } from 'vue'

export default {
  setup() {
    const style = useCssModule()

    return () =>
      h(
        'div',
        {
          class: style.success
        },
        'Задача выполнена!'
      )
  }
}
</script>

<style module>
.success {
  color: #090;
}
</style>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

Дополнительную информацию об использовании CSS-модулей можно прочитать в разделе Возможности стилей SFC: <style module>.

# Аргументы

Принимает один аргумент: name

# name

  • Тип: String

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

    Имя CSS-модуля. По умолчанию '$style'.

# version

Возвращает номер установленной версии Vue в виде строки.

const version = Number(Vue.version.split('.')[0])

if (version === 3) {
  // Vue 3
} else if (version === 2) {
  // Vue 2
} else {
  // Неподдерживаемая версия Vue
}
1
2
3
4
5
6
7
8
9

См. также: API приложения — version