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

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

const { createApp, h, nextTick } = Vue

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

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

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

# createApp

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

const app = createApp({})

После 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>

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

Тип: String | Object (объект настроек компонента)
Подробности:

Подробнее можно прочитать в разделе динамические компоненты.

# 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

← API приложения Локальное состояние →