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

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

Компоненты <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

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

    • isstring | Компонент | 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

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

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

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

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

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

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

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

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

    • enter-from-classstring

    • leave-from-classstring

    • appear-classstring

    • enter-to-classstring

    • leave-to-classstring

    • appear-to-classstring

    • enter-active-classstring

    • leave-active-classstring

    • appear-active-classstring

  • События:

    • 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

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

    • tagstring Имя тега; если не определён, то будет отрисовываться без корневого элемента.
    • 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

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

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

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

    • maxnumber | 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

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

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

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

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

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

# teleport

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

    • tostring Обязательный входной параметр, должен быть корректным селектором или 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
    • disabledboolean Опциональный входной параметр, позволяющий отключать функциональность <teleport>, что означает, что его содержимое никуда не будет перемещено, а вместо этого отрисовано в соответствующем родительском компоненте, там где был указан <teleport>.
    <teleport to="#popup" :disabled="displayVideoInline">
      <video src="./my-movie.mp4">
    </teleport>
    
    1
    2
    3

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

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