В шаблонах Vue используют предопределенные директивы [1], управляющие отображением страницы. Но также у пользователя есть возможность создать собственные директивы.

Пользовательская директива Vue это по сути определяемый объект JavaScript, котором есть возможность привязаться к жизненным циклам элемента, для которого директива предназначена.

Имя объекта для директивы должно начинаться на букву v, например:

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

...
const vFocus = {
    mounted: (el) => el.focus()
};
< /script>

Тогда в шаблоне эта директива будет доступна под именем v-focus.

Пользовательские директивы Vue представляют собой инструмент для повторного использования логики низкоуровневого доступа к DOM (Document Object Model), который применяется, когда декларативных возможностей компонентов и composables недостаточно.

Ниже — структурированный обзор того, как они работают в Vue 3 (с ключевыми отличиями от Vue 2).

[1. Назначение и когда использовать]

Не путать с компонентами: директивы не заменяют бизнес-логику, они работают напрямую с DOM-элементами.

Когда нужны:

- Автофокус (el.focus()).
- Интеграция сторонних библиотек (drag & drop, кастомные скроллбары).
- Манипуляции с атрибутами/стилями при появлении элемента.
- Ленивая загрузка изображений (IntersectionObserver).
- UI-фичи: закрепление элемента (`v-pin`).

Когда НЕ нужны:

- Вся бизнес-логика, работа с API, хранилища (Pinia/Vuex) — это задача компонентов или composables.

[2. Структура и жизненные хуки (Vue 3)]

Директива — это объект с хуками, аналогичными хукам компонента. Все хуки опциональны.

Vue 2 vs Vue 3 — названия хуков изменились:

- bind → mounted
- inserted → удалён
- update → updated
- componentUpdated → удалён
- unbind → unmounted 

[3. Аргументы хуков (объект binding)]

В каждый хук приходит 4 аргумента:  

mounted(el, binding, vnode, prevVnode)

Объект binding — самое важное:

{  value:        // переданное значение (v-dir="1" → 1)
  oldValue:     // предыдущее (только update/updated)
  arg:          // аргумент (v-dir:foo → 'foo')
  modifiers:    // модификаторы (v-dir.once → { once: true })
  instance:     // экземпляр компонента
  dir:          // объект самой директивы
}

Динамический аргумент — реактивно обновляется:

< div v-pin:[direction]="200">< /div>  < !-- direction может меняться -->

[4. Создание и регистрация]

Локально (в компоненте):

Composition API (< script setup>) — автоматически, если переменная с префиксом `v`:

< script setup>
const vFocus = { mounted: (el) => el.focus() }
< /script>

< template>
  < input v-focus />
< /template>

Options API — через опцию `directives`:

export default {
  directives: {
    focus: { mounted: (el) => el.focus() }
  }
}

Глобально:

import { createApp } from 'vue'
const app = createApp(App)
app.directive('focus', { mounted: (el) => el.focus() })

Доступна во всех компонентах без импорта.

[5. Синтаксический сахар]

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

app.directive('color', (el, binding) => {
  el.style.color = binding.value
})

Передача объекта параметров:

< div v-demo="{ color: 'white', text: 'hello' }">< /div>

[6. Особенности работы с компонентами]

- На однокорневом компоненте — директива применяется к корневому узлу.
- На многокорневом (fragment) — игнорируется, будет warning.
- Нельзя прокинуть через v-bind="$attrs" (в отличие от атрибутов).

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

[7. Практические примеры из реальной разработки]

[8. Best Practices]

1. Чистота: директива — только DOM. API, сторы, вычисления — в компонент.
2. Очистка: если навесили addEventListener в mounted — снимите в unmounted.
3. Простота: если директива сложнее 10 строк — возможно нужен компонент.
4. Не злоупотреблять: встроенные v-bind, v-show, v-if почти всегда лучше кастомных.
5. Чтение: объект binding (кроме el) — readonly. Обмен данными между хуками — через el.dataset.

Если вы переходите с Vue 2: самое важное изменение — имена хуков и отказ от синтаксиса "одной функции по умолчанию". Vue 3 предлагает чёткий объект с именованными методами жизненного цикла.

[Ссылки]

1. Директивы шаблона Vue.