Ссылки на элементы шаблона ​

Хотя декларативная модель отрисовки Vue абстрагирует большую часть прямых операций с DOM, всё же могут быть случаи, когда нам понадобится прямой доступ к базовым элементам DOM. Для этого мы можем использовать специальный атрибут ref:

<input ref="input">

ref — это специальный атрибут, аналогичный атрибуту key, о котором говорилось в главе v-for. Он позволяет получить прямую ссылку на конкретный элемент DOM или экземпляр дочернего компонента после его установки. Это может быть полезно, когда вы хотите, например, программно сфокусировать ввод на компоненте mount или инициализировать стороннюю библиотеку на элементе.

Доступ к рефам ​

<script setup>
import { useTemplateRef, onMounted } from 'vue'
// первый аргумент должен соответствовать значению ref в шаблоне
const input = useTemplateRef('my-input')
onMounted(() => {
  input.value.focus()
})
</script>
<template>
  <input ref="my-input" />
</template>

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

// объявляем ref для хранения ссылки на элемент шаблона
// имя должно соответствовать значению атрибута ref в разметке
const input = ref(null)

onMounted(() => {
  input.value.focus()
})
</script>

<template>
  <input ref="input" />
</template>

export default {
  setup() {
    const input = ref(null)
    // ...
    return {
      input
    }
  }
}

<script>
export default {
  mounted() {
    this.$refs.input.focus()
  }
}
</script>

<template>
  <input ref="input" />
</template>

Обратите внимание, что вы можете получить доступ к ссылке только после того, как компонент смонтирован. Если вы попытаетесь получить доступ к $refs.inputinput в выражении шаблона это будет undefinenull при первой отрисовке. Это потому, что элемент не существует до первой отрисовки!

watchEffect(() => {
  if (input.value) {
    input.value.focus()
  } else {
    // ещё не смонтирован, или элемент был размонтирован (например, с помощью v-if)
  }
})

Ссылка на компонент ​

Этот раздел предполагает знание Компонентов. Не стесняйтесь пропустить его и вернуться позже.

ref можно использовать и для дочернего компонента. В этом случае ссылка будет принадлежать экземпляру компонента:

<script setup>
import { useTemplateRef, onMounted } from 'vue'
import Child from './Child.vue'
const childRef = useTemplateRef('child')
onMounted(() => {
  // childRef.value будет содержать экземпляр <Child />
})
</script>
<template>
  <Child ref="child" />
</template>

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

const child = ref(null)

onMounted(() => {
  // child.value будет содержать экземпляр <Child />
})
</script>

<template>
  <Child ref="child" />
</template>

<script>
import Child from './Child.vue'

export default {
  components: {
    Child
  },
  mounted() {
    // this.$refs.child будет содержать экземпляр <Child />
  }
}
</script>

<template>
  <Child ref="child" />
</template>

Если дочерний компонент использует Options API или не использует <script setup>, то экземплярЭкземпляр, на который ссылаются, будет идентичен this дочернего компонента, что означает, что родительский компонент будет иметь полный доступ к каждому свойству и методу дочернего компонента. Это позволяет легко создавать тесно связанные детали реализации между родительским и дочерним компонентами, поэтому ссылки на компоненты следует использовать только в случае крайней необходимости — в большинстве случаев вы должны попытаться реализовать взаимодействие родитель/потомок, используя стандартные интерфейсы props и emit.

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

const a = 1
const b = ref(2)

// Макросы компилятора, такие как defineExpose, не нужно импортировать
defineExpose({
  a,
  b
})
</script>

export default {
  expose: ['publicData', 'publicMethod'],
  data() {
    return {
      publicData: 'foo',
      privateData: 'bar'
    }
  },
  methods: {
    publicMethod() {
      /* ... */
    },
    privateMethod() {
      /* ... */
    }
  }
}

Рефы внутри v-for ​

Требуется версия 3.5 или выше

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

const list = ref([
  /* ... */
])

const itemRefs = useTemplateRef('items')

onMounted(() => console.log(itemRefs.value))
</script>
<template>
  <ul>
    <li v-for="item in list" ref="items">
      {{ item }}
    </li>
  </ul>
</template>

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

const list = ref([
  /* ... */
])

const itemRefs = ref([])

onMounted(() => console.log(itemRefs.value))
</script>

<template>
  <ul>
    <li v-for="item in list" ref="itemRefs">
      {{ item }}
    </li>
  </ul>
</template>

<script>
export default {
  data() {
    return {
      list: [
        /* ... */
      ]
    }
  },
  mounted() {
    console.log(this.$refs.items)
  }
}
</script>

<template>
  <ul>
    <li v-for="item in list" ref="items">
      {{ item }}
    </li>
  </ul>
</template>

Следует отметить, что массив ref не гарантирует тот же порядок, что и исходный массив.

Ссылка на функцию ​

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

<input :ref="(el) => { /* присвоить el свойству или ссылке */ }">

Обратите внимание, что мы используем динамическую привязку :ref, поэтому мы можем передать ей функцию вместо строки с именем ref. Когда элемент будет размонтирован, аргумент станет null. Конечно, вы можете использовать метод вместо встроенной функции.