Vue.js

# Встроенные компоненты

Встроенные компоненты можно использовать в шаблонах без их регистрации.

Компоненты <keep-alive>, <transition>, <transition-group> и <teleport> доступны для tree-shaking при сборке, поэтому будут включены в сборку только в случае, если они используются. Их можно импортировать явно, если нужен прямой доступ к компоненту:

// CDN-сборка Vue
const { KeepAlive, Teleport, Transition, TransitionGroup } = Vue
1
2
// ESM-сборка Vue
import { KeepAlive, Teleport, Transition, TransitionGroup } from 'vue'
1
2

Компоненты <component> и <slot> являются синтаксическим сахаром в шаблонах. Они не являются настоящими компонентами и их нельзя импортировать, как компоненты выше.

# component

  • Входные параметры:

    • is — string | Компонент | VNode

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

    «Мета-компонент» для отрисовки динамических компонентов. Настоящий компонент для отрисовки определяется входным параметром is. Значением входного параметра is должна быть строка с именем HTML-тега или именем компонента.

    <!-- динамический компонент, который -->
<!-- определяется свойством `componentId` в компоненте -->
<component :is="componentId"></component>

<!-- можно также отрисовывать зарегистрированный компонент -->
<!-- или компонент, передаваемый в свойстве -->
<component :is="$options.components.child"></component>

<!-- можно указывать имена компонентов строкой -->
<component :is="condition ? 'FooComponent' : 'BarComponent'"></component>

<!-- можно отрисовывать нативные HTML-элементы -->
<component :is="href ? 'a' : 'span'"></component>
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13

  • Использование со встроенными компонентами:

    Встроенные компоненты KeepAlive, Transition, TransitionGroup и Teleport можно передавать в is, но сначала их нужно зарегистрировать, если они будут передаваться по имени. Например:

     



     
     



     





    const { Transition, TransitionGroup } = Vue

const Component = {
  components: {
    Transition,
    TransitionGroup
  },

  template: `
    <component :is="isGroup ? 'TransitionGroup' : 'Transition'">
      ...
    </component>
  `
}
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14

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

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

    В продвинутых случаях иногда может быть полезно отрисовать существующую VNode через шаблон. Использование <component> делает это возможным, но рассматривайте это как крайний вариант, используемый для того, чтобы избежать переписывания всего шаблона в виде render функции.

    <component :is="vnode" :key="aSuitableKey" />
    1

    Есть ограничение при смешивании VNodes и шаблонов подобным образом — необходимо указывать подходящий атрибут key. Узел VNode рассматривается как статичный и любые обновления будут игнорироваться, пока не изменится key. Атрибут key может быть на VNode или на теге <component>, но в любом случае должен меняться каждый раз, когда необходимо чтобы VNode перерисовывалась. Этого ограничения не будет, если узлы имеют разные типы, например, при смене span на div.

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

# transition

  • Входные параметры:

    • name — string Используется для автоматической генерации CSS-классов перехода. Например, для name: 'fade' будут созданы .fade-enter, .fade-enter-active, и т.д.

    • appear — boolean Применять ли переход при первоначальной отрисовке. По умолчанию false.

    • persisted — boolean При значении true указывает на то, что переход на самом деле не вставляет/удаляет элемент, а изменяет его видимость (показан/скрыт). Хуки переходов внедряются, но будут пропускаться при отрисовке. Вместо этого, переходом может управлять пользовательская директива, вызывая хуки (например, v-show).

    • css — boolean Применять ли CSS-классы переходов. По умолчанию true. При значении false будут вызываться только хуки JavaScript, зарегистрированные через события компонента.

    • type — string Определяет тип событий перехода, которые требуется ждать для определения времени окончания перехода. Доступные значения "transition" и "animation". По умолчанию выбирается тип с наибольшей длительностью.

    • mode — string Управляет временной последовательностью переходов скрытия/появления. Доступны режимы "out-in" и "in-out"; по умолчанию — одновременно.

    • duration — number | { enter: number, leave: number }. Определяет продолжительность перехода. По умолчанию Vue дожидается первого события transitionend или animationend на корневом элементе перехода.

    • enter-from-class — string

    • leave-from-class — string

    • appear-class — string

    • enter-to-class — string

    • leave-to-class — string

    • appear-to-class — string

    • enter-active-class — string

    • leave-active-class — string

    • appear-active-class — string

  • События:

    • before-enter
    • before-leave
    • enter
    • leave
    • appear
    • after-enter
    • after-leave
    • after-appear
    • enter-cancelled
    • leave-cancelled (только для v-show)
    • appear-cancelled

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

    Компонент <transition> предоставляет эффекты перехода для одного элемента/компонента. Поведение эффекта перехода применяется только к содержимому внутри <transition>; он не отрисовывает дополнительный DOM-элемент и не отображается в иерархии компонентов в инструментах разработчика.

    <!-- простой элемент -->
<transition>
  <div v-if="ok">переключаемое содержимое</div>
</transition>

<!-- динамический компонент -->
<transition name="fade" mode="out-in" appear>
  <component :is="view"></component>
</transition>

<!-- перехват событий -->
<div id="transition-demo">
  <transition @after-enter="transitionComplete">
    <div v-show="ok">переключаемое содержимое</div>
  </transition>
</div>
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    const app = createApp({
  ...
  methods: {
    transitionComplete(el) {
      // с DOM-элементом, переданным аргументом `el`, сделать что-то ...
    }
  }
  ...
})

app.mount('#transition-demo')
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11

  • См. также: Переходы появления/исчезновения

# transition-group

  • Входные параметры:

    • tag — string Имя тега; если не определён, то будет отрисовываться без корневого элемента.
    • move-class — перезаписывать CSS-класс перехода в режиме перемещения.
    • предоставляет те же входные параметры что и <transition>, за исключением mode.

  • События:

    • предоставляет те же события что и <transition>.

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

    Компонент <transition-group> предоставляет эффекты перехода для нескольких элементов/компонентов. По умолчанию DOM-элемент обёртки не отрисовывается, но его можно определить с помощью атрибута tag.

    Обратите внимание, что у каждого потомка в <transition-group> должен быть уникальный key для корректной работы анимаций.

    Компонент <transition-group> поддерживает переходы с перемещениями с помощью CSS transform. Когда позиция дочернего элемента после обновлений изменится, он применит CSS-класс перемещения (автоматически сгенерированный по атрибуту name или определённый атрибутом move-class). Если при применении класса CSS-свойство transform возможно перемещение, то элемент будет плавно анимирован до точки назначения с помощью техники FLIP (opens new window).

    <transition-group tag="ul" name="slide">
  <li v-for="item in items" :key="item.id">
    {{ item.text }}
  </li>
</transition-group>
    1
    2
    3
    4
    5

  • См. также: Анимирование списков

# keep-alive

  • Входные параметры:

    • include — string | RegExp | Array. Только компоненты с совпадающими именами будут закэшированы.

    • exclude — string | RegExp | Array. Не будет кэшироваться любой компонент с подходящим именем.

    • max — number | string. Максимальное количество экземпляров компонентов для кэширования.

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

    При оборачивании вокруг динамического компонента, <keep-alive> будет кэшировать неактивные экземпляры компонентов, не уничтожая их. Аналогично <transition> или <keep-alive> это абстрактный компонент: он не отрисовывается DOM-элементом и не появляется в родительской цепочке компонента.

    Для компонента внутри <keep-alive> при переключениях будут вызываться хуки жизненного цикла activated и deactivated, предоставляя альтернативу mounted и unmounted, которые не будут вызываться. (Это относится как к непосредственному потомку <keep-alive>, так и ко всем его потомкам.)

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

    <!-- обычное применение -->
<keep-alive>
  <component :is="view"></component>
</keep-alive>

<!-- несколько потомков по условию -->
<keep-alive>
  <comp-a v-if="a > 1"></comp-a>
  <comp-b v-else></comp-b>
</keep-alive>

<!-- использование вместе с `<transition>` -->
<transition>
  <keep-alive>
    <component :is="view"></component>
  </keep-alive>
</transition>
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17

    Обратите внимание, что <keep-alive> предназначен для случаев с одним дочерним компонентом, отображение которого переключается по условию. Он не будет работать, если внутри него указать v-for. В случаях когда есть несколько дочерних компонентов, отображаемых по условию, <keep-alive> требует, чтобы только один компонент из них показывался в каждый момент времени.

  • include и exclude

    Входные параметры include и exclude позволяют кэшировать компоненты по условию. Значением входных параметров может быть строка, с перечислением через запятую, регулярное выражение или массив:

    <!-- строка, с перечислением через запятую -->
<keep-alive include="a,b">
  <component :is="view"></component>
</keep-alive>

<!-- регулярное выражение (используется `v-bind`) -->
<keep-alive :include="/a|b/">
  <component :is="view"></component>
</keep-alive>

<!-- массив (используется `v-bind`) -->
<keep-alive :include="['a', 'b']">
  <component :is="view"></component>
</keep-alive>
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14

    При сопоставлении сначала проверяется собственная опция компонента name, а если она недоступна — локальное имя при регистрации (ключ в опции components родителя). Анонимные компоненты не могут быть сопоставлены.

  • max

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

    <keep-alive :max="10">
  <component :is="view"></component>
</keep-alive>
    1
    2
    3

    ВНИМАНИЕ

    Компонент <keep-alive> не работает с функциональными компонентами, так как у них нет экземпляра для кэширования.

  • См. также: Динамические компоненты с keep-alive

# slot

  • Входные параметры:

    • name — string Используется для именованного слота.

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

    Компонент <slot> служит в качестве точки распространения контента в шаблонах компонента. Сам <slot> будет заменён.

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

  • См. также: Распределение контента слотами

# teleport

  • Входные параметры:

    • to — string Обязательный входной параметр, должен быть корректным селектором или HTMLElement (при использовании в браузерном окружении). Определяет целевой элемент, куда будет перемещаться содержимое <teleport>.
    <!-- ОК -->
<teleport to="#some-id" />
<teleport to=".some-class" />
<teleport to="[data-teleport]" />

<!-- НЕПРАВИЛЬНО -->
<teleport to="h1" />
<teleport to="some-string" />
    1
    2
    3
    4
    5
    6
    7
    8
    • disabled — boolean Опциональный входной параметр, позволяющий отключать функциональность <teleport>, что означает, что его содержимое никуда не будет перемещено, а вместо этого отрисовано в соответствующем родительском компоненте, там где был указан <teleport>.
    <teleport to="#popup" :disabled="displayVideoInline">
  <video src="./my-movie.mp4">
</teleport>
    1
    2
    3

    Обратите внимание, будут перемещены настоящие DOM-узлы, вместо их уничтожения и пересоздания, а также сохранятся все экземпляры компонентов. Все HTML-элементы с состоянием (например, воспроизводимое видео) также сохранят своё состояние.

  • См. также: Телепорты

← Основное API реактивности →