Реактивные ссылки ref - полный разбор для разработчиков

Введение

Реактивные ссылки ref сегодня встречаются почти во всех популярных фронтенд‑фреймворках. В Vue 3, React, Solid, Svelte и других есть своя форма работы с "ссылками" на данные или DOM, которые позволяют отслеживать изменения и правильно обновлять интерфейс.

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

Давайте разберемся, что такое реактивная ссылка, чем она отличается от обычной переменной, как она ведет себя в шаблоне и в JavaScript‑коде, какие типичные ошибки возникают и как их избегать.

---

Что такое реактивная ссылка ref

Базовое определение

Если говорить простыми словами, реактивная ссылка ref – это "обертка" вокруг значения, у которой есть одно важное свойство: при изменении этого значения фреймворк автоматически понимает, что нужно обновить все места, где оно используется.

В случае Vue 3 типичная реактивная ссылка создается с помощью функции ref:

import { ref } from 'vue'

// Создаем реактивную ссылку на число
const counter = ref(0)

// Теперь counter — это объект-ссылка
// Значение лежит в поле value
console.log(counter.value) // 0

// Обновляем значение
counter.value++ // Триггерим обновление всех зависимостей

Комментарии к примеру:

// ref(0) — создает специальный объект, который умеет "сообщать" системе реактивности о том, что его значение прочитали или изменили
// counter.value — доступ к реальному числовому значению
// counter сам по себе — не число, а объект с метаданными и возможностью реагировать на изменения

Важно: реактивная ссылка чаще всего используется для простых (примитивных) типов: числа, строки, булевы значения. Хотя ничего не мешает поместить внутрь и объект или массив.

Почему вообще нужен ref

Можно спросить: почему бы не использовать обычную переменную?

let count = 0
count++

Проблема в том, что фреймворк не может отслеживать изменения таких переменных "сам по себе". Ему нужно специальное "место", через которое он:

• регистрирует чтение значения (чтобы понять, от чего зависит вычисление или компонент);
• отслеживает запись (чтобы понять, когда нужно обновить шаблон или вычисление).

Реактивная ссылка дает именно это: единый объект, к которому "подключена" система отслеживания зависимостей.

---

ref в составе Composition API

Создание и использование в компоненте

Посмотрите, как ref обычно используется внутри компонента Vue 3:

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

// Создаем реактивную ссылку на строку
const message = ref('Привет')

// Функция, которая будет менять значение
function updateMessage() {
  // Меняем реальное значение через .value
  message.value = 'Сообщение обновлено'
}
</script>

<template>
  <!-- В шаблоне к ref можно обращаться как к обычной переменной -->
  <p>{{ message }}</p>

  <button @click="updateMessage">
    Обновить сообщение
  </button>
</template>

Комментарии:

// В script setup message — это объект-ссылка, доступ к значению — через message.value
// В template Vue делает "авто-распаковку" — в разметке {{ message }} ведет себя так, как если бы там было само значение, а не объект

Здесь мы плавно подходим к важному моменту: поведение ref отличается в JavaScript‑коде и в шаблоне.

---

.value – зачем он нужен и как с ним жить

Поведение в JavaScript

В чистом JS‑коде (внутри setup, в обычных функциях, в модулях) ref — это объект. Его структура в упрощенном виде может быть описана так:

const state = ref(0)

// Внутренний вид (упрощенно):
// state = {
//   value: 0,          // само значение
//   /* служебные поля для реактивности */
// }

Чтобы прочитать значение или записать новое, всегда нужно использовать .value:

const count = ref(1)

console.log(count)        // Выведет объект-ссылку
console.log(count.value)  // Выведет 1

count.value = 5           // Меняем значение
count.value++             // Увеличиваем и триггерим обновления

Если забыть про .value, появятся типичные ошибки:

const count = ref(1)

// Плохой код:
if (count === 1) {
  // Это условие никогда не сработает, потому что count — объект, а не число
}

Авто-распаковка в шаблонах

В шаблонах Vue ведет себя по-другому. В разметке ref автоматически "разворачивается" до своего значения:

<template>
  <!-- Здесь message — уже не объект, а его значение -->
  <p>{{ message }}</p>

  <!-- В выражениях внутри шаблона работает то же правило -->
  <p>Длина: {{ message.length }}</p>
</template>

Это значит, что вам не нужно писать message.value в шаблоне. Такая "поблажка" сделана специально, чтобы шаблон выглядел проще и ближе к обычному HTML с вкраплениями выражений.

Авто-распаковка в script setup

В режиме script setup есть еще одна особенность: если вы возвращаете ref из setup, то при использовании в шаблоне он также будет авто‑распакован. Но в самом JS‑коде внутри setup по-прежнему нужно явно использовать .value.

Чтобы вы не запутались, зафиксируем простое правило:

• В JavaScript‑коде (setup, функции, модули) — всегда .value
• В шаблоне — без .value, фреймворк делает это сам

---

ref для примитивов и для объектов

ref vs reactive

В Vue 3 есть две базовые конструкции для реактивности:

• ref — реактивная ссылка на любое значение (часто — на примитив);
• reactive — делает реактивным сам объект (возвращает прокси‑объект).

Смотрите, как отличается их поведение:

import { ref, reactive } from 'vue'

// Примитив через ref
const count = ref(0)

// Объект через reactive
const user = reactive({
  name: 'Alex',
  age: 25
})

Комментарии:

// ref оборачивает значение в объект-ссылку, само значение лежит в .value
// reactive возвращает "прокси", который выглядит как обычный объект, но его чтение и запись отслеживаются системой реактивности

Когда использовать ref для объектов

Иногда бывает удобно использовать ref даже для объектов:

const user = ref({
  name: 'Alex',
  age: 25
})

// Изменение вложенных полей
user.value.age++

// Полная замена объекта
user.value = {
  ...user.value,
  name: 'Max'
}

Давайте посмотрим, почему такой подход полезен:

1. Можно легко "переназначить" целый объект (например, результат запроса к API), просто присвоив новое значение в .value.
2. Когда вы работаете с объектом как с "ресурсом", который может быть undefined, null или полноценным объектом.

Например:

const user = ref(null)

// Позже, после загрузки с сервера:
user.value = {
  id: 1,
  name: 'Alex'
}

Глубина реактивности внутри ref

Если вы передаете в ref объект, Vue сделает его содержимое реактивным:

const state = ref({
  a: 1,
  b: 2
})

// Изменение вложенного свойства
state.value.a++  // Это изменение будет отслеживаться

Комментарии:

// Под капотом для вложенного объекта также используется реактивная обертка
// Поэтому изменение state.value.a вызовет перерендер так же, как и изменение state.value целиком

То есть ref работает "поверх" еще одного слоя реактивности, когда внутри лежит объект или массив.

---

Шаблоны и директивы: как ref ведет себя в разметке

Использование ref в выражениях шаблона

Вы уже видели базовый пример:

<p>{{ message }}</p>

Теперь давайте усложним пример и посмотрим, как ref участвует в вычислениях внутри шаблона:

<template>
  <p>Счетчик: {{ count }}</p>
  <p>Удвоенное значение: {{ count * 2 }}</p>
  <p>Текст: {{ message.toUpperCase() }}</p>
</template>

Комментарии:

// Во всех выражениях count и message автоматически подставляются как их реальные значения
// В шаблоне вы можете выполнять операции, как если бы работали с обычными переменными, без .value

Фреймворк сам отслеживает, какие ref были использованы в шаблоне, и при изменении этих ref перерисует только ту часть DOM, где есть зависимости.

ref в директивах и обработчиках событий

Посмотрите, как ref используются в обработчиках и привязках:

<template>
  <input
    v-model="message"        <!-- Двусторонняя привязка к ref -->
  />

  <button @click="count++">  <!-- Операция с ref в шаблоне -->
    Увеличить
  </button>

  <p v-if="count > 5">
    Значение больше пяти
  </p>
</template>

Комментарии:

// v-model="message" — двусторонне связывает поле ввода с message.value
// @click="count++" — в момент клика фреймворк фактически выполнит count.value++
// v-if="count > 5" — условие будет пересчитано при каждом изменении count

---

Композиция логики: передача и возврат ref

Возврат ref из композиционных функций

Сильная сторона Composition API — возможность вынести куски логики в отдельные функции, которые возвращают ref‑ы и другие реактивные сущности.

Смотрите пример простой композиционной функции:

// useCounter.js
import { ref } from 'vue'

export function useCounter(initial = 0) {
  const count = ref(initial)

  function inc() {
    count.value++
  }

  function dec() {
    count.value--
  }

  return {
    count, // возвращаем сам ref
    inc,
    dec
  }
}

Теперь давайте подключим ее в компоненте:

<script setup>
import { useCounter } from './useCounter'

const { count, inc, dec } = useCounter(10)
</script>

<template>
  <p>Значение: {{ count }}</p>

  <button @click="dec">-1</button>
  <button @click="inc">+1</button>
</template>

Комментарии:

// useCounter создает один ref и несколько функций, которые этот ref изменяют
// Компонент использует результат как "готовый блок" логики, не задумываясь о деталях реализации
// В шаблоне count авто‑распаковывается, как и любые другие ref

Этот подход позволяет переиспользовать и тестировать бизнес‑логику отдельно от конкретных компонентов.

Передача ref в другие функции

Реактивную ссылку удобно передавать в функции, которые должны что‑то "делать" с реактивным значением.

Например:

function useToggle(flagRef) {
  // flagRef — это ref(boolean)
  function toggle() {
    flagRef.value = !flagRef.value
  }

  return { toggle }
}

// Где-то в компоненте:
const isOpen = ref(false)
const { toggle } = useToggle(isOpen)

Комментарии:

// useToggle не создает свой ref, а работает с тем, что вы передали
// Это позволяет организовать "надстройки" над существующими состояниями

Важно следить, чтобы вы передавали именно ref, а не его значение. Если случайно передать flagRef.value, реативность потеряется.

---

DOM-ссылки: template ref (на элементы и компоненты)

Здесь важно не путать две разные вещи:

• ref как реактивная ссылка на данные (то, о чем мы говорим большую часть статьи);
• template ref — ссылка на DOM‑элемент или экземпляр дочернего компонента.

Оба механизма используют одинаковое ключевое слово ref, но их смысл различается.

Template ref на DOM‑элемент

Посмотрите, как это выглядит в Vue 3:

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

// Создаем ref без начального значения
const inputEl = ref(null)

onMounted(() => {
  // После монтирования в DOM inputEl.value содержит сам DOM-элемент
  // Здесь мы можем, например, сфокусировать поле ввода
  inputEl.value.focus()
})
</script>

<template>
  <!-- Привязываем ref к DOM-элементу -->
  <input ref="inputEl" type="text" />
</template>

Комментарии:

// inputEl — это все тот же ref-объект
// До монтирования inputEl.value === null
// После монтирования inputEl.value указывает на реальный HTMLInputElement

Такую ссылку удобно использовать, когда вам нужен доступ к нативным методам DOM, которые не покрываются стандартными возможностями фреймворка.

Template ref на дочерний компонент

С помощью ref можно получать ссылку не только на DOM, но и на экземпляр дочернего компонента:

<!-- Child.vue -->
<script setup>
function exposeMethod() {
  console.log('Метод дочернего компонента вызван')
}

// Экспортируем методы через defineExpose
defineExpose({
  exposeMethod
})
</script>

<template>
  <div>Дочерний компонент</div>
</template>

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

const childRef = ref(null)

onMounted(() => {
  // Доступ к публичным методам дочернего компонента
  childRef.value.exposeMethod()
})
</script>

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

Комментарии:

// ref="childRef" связывает экземпляр Child с childRef.value
// Через defineExpose мы явно указываем, какие методы доступны снаружи
// В родителе childRef.value — экземпляр Child с доступом к exposeMethod

---

Вычисляемые значения и ref

computed и работа с ref

Вычисляемые значения (computed) во Vue тоже реализованы на основе ref. Функция computed возвращает объект, который внешне ведет себя так же, как ref:

import { ref, computed } from 'vue'

const price = ref(100)
const qty = ref(2)

// Создаем вычисляемое значение
const total = computed(() => {
  // Здесь мы используем .value, потому что это обычный JS-код
  return price.value * qty.value
})

Комментарии:

// total — это тоже ref-подобный объект
// total.value всегда содержит актуальное пересчитанное значение
// computed автоматически отслеживает price и qty как зависимости

В шаблоне вы сможете использовать total без .value, как и любой другой ref:

<template>
  <p>Цена: {{ price }}</p>
  <p>Количество: {{ qty }}</p>
  <p>Итого: {{ total }}</p>
</template>

read-only поведение computed

По умолчанию computed создаёт "только для чтения" ref:

total.value = 500 // Ошибка — вычисляемое значение нельзя назначать напрямую

Это логично: computed описывает зависимость, а не отдельное состояние. Если нужно и читать, и писать, есть форма с геттером и сеттером, но важно понимать, что и в этом случае возвращаемый объект по сути всё тот же ref с расширенным поведением.

---

Особенности работы с ref в массивах и объектах

Массив ref в state

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

const items = ref([])

function addItem(newItem) {
  // Добавляем элемент в массив
  items.value.push(newItem)
}

function resetItems() {
  // Заменяем весь массив
  items.value = []
}

Комментарии:

// items.value — обычный массив, к нему применимы стандартные методы push, filter и т.д.
// Система реактивности "видит" изменения как в структуре массива, так и при полной замене

Обновление элементов массива

Давайте посмотрим типичный сценарий:

function removeById(id) {
  items.value = items.value.filter(item => item.id !== id)
}

function updateItem(id, patch) {
  items.value = items.value.map(item =>
    item.id === id ? { ...item, ...patch } : item
  )
}

Комментарии:

// Здесь мы работаем через иммутабельные операции filter и map
// Это удобно для предсказуемости: каждый вызов создает новый массив, а не мутирует старый
// Для Vue такой подход тоже хорошо читается — полная замена items.value

Можно и мутировать массив напрямую:

items.value.splice(index, 1)

Это тоже будет отслеживаться.

---

Частые ошибки и подводные камни

Забыли .value в JS‑коде

Это, пожалуй, самая распространенная ошибка:

const count = ref(0)

function log() {
  console.log(count) // Выведет объект, а не число
}

Как исправить:

console.log(count.value)

Смотрите, еще один пример с условием:

if (count > 5) {  // Ошибка
  // ...
}

Правильный вариант:

if (count.value > 5) {
  // ...
}

В шаблоне вы так писать не будете, но в обычном JS это нужно помнить всегда.

Перенос значения вместо ref

Еще одна частая проблема — случайно передать само значение, а не ref:

const isOpen = ref(false)

function initModal(open) {
  // Здесь open — уже не ref, а обычный boolean
}

initModal(isOpen.value) // Потеряли реактивность

Если функция должна работать с реактивным состоянием, передавайте ref целиком:

function initModal(openRef) {
  openRef.value = true
}

initModal(isOpen)

Потеря реактивности при деструктуризации

Если вы возьмете объект с ref‑ами и примените к нему обычную деструктуризацию, вы отрежете .value и реактивность:

const state = {
  count: ref(0),
  message: ref('Привет')
}

// Плохой вариант:
const { count, message } = state
// Здесь count и message — все еще ref, это нормально

// Но если вы сделаете так:
const { count: countValue } = state
// countValue — это ref, а не число

Более тонкая проблема появляется, когда мы деструктурируем результат reactive объекта. Там нужно использовать специальные утилиты (например, toRefs), но это уже отдельная тема. Важно помнить, что деструктуризация может менять формы данных, и нужно следить, чтобы вы не "вытащили" обычное значение, надеясь, что оно останется реактивным.

---

Как ref работает под капотом (коротко и по существу)

Давайте, без лишних деталей реализации, разберем базовую идею.

Представьте, что ref хранит:

• само значение (value);
• список "наблюдателей" — эффектов, которые должны выполниться, когда значение меняется (например, рендер компонента или вычисление computed).

Когда вы читаете ref.value:

1. Система реактивности проверяет, есть ли сейчас "активный" эффект (например, идет рендер компонента или вычисление computed).
2. Если да, этот эффект записывается как зависимость от текущего ref.

Когда вы меняете ref.value:

1. Значение обновляется.
2. Система находит все эффекты, которые зависят от этого ref.
3. Запускает их повторно (перерендер компонента, пересчет вычисляемого значения и т.п.).

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

---

Заключение

Реактивные ссылки ref — это фундаментальная единица реактивности во Vue 3 и похожих фреймворках. Они представляют собой объекты‑обертки вокруг значений, позволяющие системе отслеживать чтение и запись, а затем правильно обновлять зависимости: шаблон, вычисляемые значения, побочные эффекты.

Ключевые моменты, которые стоит закрепить:

• В JavaScript‑коде реальное значение ref всегда лежит в поле .value.
• В шаблоне ref автоматически распаковывается, и можно писать просто {{ count }} вместо count.value.
• ref удобно использовать как для примитивов, так и для объектов и массивов, особенно когда нужно иметь возможность легко заменить значение целиком.
• Композиционные функции могут создавать и возвращать ref, а также принимать их как аргументы, что позволяет выстраивать гибкую архитектуру.
• Template ref на DOM‑элементы и компоненты использует то же ключевое слово ref, но работает с самим DOM и экземплярами, а не с реактивными данными.

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

---

Частозадаваемые технические вопросы и ответы

Как передать ref как проп в дочерний компонент и не потерять реактивность

Если вы передаете ref в проп, обычно достаточно передать его как есть:

<!-- Родитель -->
<script setup>
const count = ref(0)
</script>

<template>
  <Child :count="count" />
</template>

В дочернем компоненте вы получите ref:

const props = defineProps({
  count: Object // или конкретный тип через PropType
})

// props.count — это ref, используйте props.count.value в JS

Лучше не "разворачивать" значение в родителе (не писать :count="count.value"), иначе в дочернем вы будете работать уже с обычным числом и потеряете реактивность.

Как типизировать ref в TypeScript

В TypeScript вы можете указать тип значения внутри ref:

const count = ref<number>(0)
const message = ref<string | null>(null)

Для DOM‑ссылок:

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

Так вы получите автоподсказки и тип‑проверку при обращении к value и методам DOM‑элемента.

Как обнулить ref правильно

Чтобы "сбросить" значение, достаточно записать в .value нужное состояние:

const user = ref({ name: 'Alex' })

function resetUser() {
  user.value = null      // если допускается null
  // или
  user.value = { name: '' }
}

Важно не пытаться "удалить" сам ref (delete user) — его нужно сохранять, а менять только его содержимое.

Как отслеживать изменения ref в watch

Для наблюдения за ref используйте watch:

const count = ref(0)

watch(count, (newVal, oldVal) => {
  // newVal и oldVal — уже значения, а не ref
})

Vue сам "распознает" ref и будет отслеживать изменения в его value, передавая в колбэк значения напрямую, без необходимости писать .value.

Как работать с массивом ref в шаблоне без потери производительности

Если у вас массив внутри ref и вы рендерите его через v-for:

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

Старайтесь всегда указывать стабильный :key (например, id), а в JS‑коде по возможности использовать иммутабельные операции (map, filter, slice) при обновлении массива:

items.value = items.value.filter(item => item.id !== removedId)

Так фреймворк сможет эффективно "сопоставлять" элементы списка и минимизировать реальные изменения DOM.