Шаблонні посилання у Vue.js

Що таке Template Refs?

Template refs надають вам прямий доступ до DOM-елементів або екземплярів дочірніх компонентів. Вони оголошуються за допомогою атрибута ref на елементах і доступні через ref() у скрипті.

Основний DOM Ref

vue

<script setup>
import { ref, onMounted } from 'vue'

const inputRef = ref<HTMLInputElement | null>(null)

onMounted(() => {
  // Елемент доступний після монтування
  inputRef.value?.focus()
})
</script>

<template>
  <input ref="inputRef" type="text" />
</template>

Компонент Ref

vue

<script setup>
import { ref } from 'vue'
import ChildComponent from './ChildComponent.vue'

const childRef = ref<InstanceType<typeof ChildComponent> | null>(null)

function callChild() {
  childRef.value?.someMethod()
  console.log(childRef.value?.someData)
}
</script>

<template>
  <ChildComponent ref="childRef" />
  <button @click="callChild">Викликати дитину</button>
</template>

Примітка: З <script setup> дочірні компоненти повинні використовувати defineExpose, щоб зробити властивості доступними через ref.

Refs у v-for

vue

<script setup>
import { ref, onMounted } from 'vue'

const itemRefs = ref<HTMLElement[]>([])

onMounted(() => {
  console.log(itemRefs.value.length) // Масив елементів
  itemRefs.value[0]?.scrollIntoView()
})
</script>

<template>
  <ul>
    <li v-for="item in items" :key="item.id" ref="itemRefs">
      {{ item.name }}
    </li>
  </ul>
</template>

Функціональні Refs

vue

<script setup>
const elements = ref(new Map<string, HTMLElement>())

function setRef(el: HTMLElement | null, id: string) {
  if (el) elements.value.set(id, el)
  else elements.value.delete(id)
}
</script>

<template>
  <div
    v-for="item in items"
    :key="item.id"
    :ref="(el) => setRef(el as HTMLElement, item.id)"
  >
    {{ item.name }}
  </div>
</template>

Загальні випадки використання

Випадок використання	Приклад
Управління фокусом	`inputRef.value?.focus()`
Контроль прокрутки	`el.scrollIntoView()`
Малювання на полотні	`canvasRef.value?.getContext('2d')`
Треті сторони бібліотеки	Ініціалізація графіка на DOM-елементі
Вимірювання розмірів	`el.offsetHeight`, `el.getBoundingClientRect()`
Виклик методів дитини	`childRef.value?.reset()`

Важливі правила

Refs є null до монтування — доступ у onMounted або пізніше
Refs є null, якщо елемент умовно рендериться (v-if="false")
З <script setup> дочірні компоненти потребують defineExpose
Віддавайте перевагу реактивним даним замість прямого маніпулювання DOM

Важливо:

Template refs надають прямий доступ до DOM, коли це необхідно — для управління фокусом, прокрутки, вимірювання, операцій з полотном або інтеграції бібліотек третьої сторони. Вони є null до монтування та коли елемент умовно прихований. Завжди віддавайте перевагу реактивній моделі даних Vue над прямим маніпулюванням DOM, коли це можливо.

Коротка відповідь

Для співбесіди

Premium

Коротка відповідь допоможе вам впевнено відповідати на цю тему під час співбесіди.

Дочитали статтю?

Практика завдань

Шаблонні посилання у Vue.js

#Що таке Template Refs?

#Основний DOM Ref

#Компонент Ref

#Refs у v-for

#Функціональні Refs

#Загальні випадки використання

#Важливі правила