Шпаргалка по VueUse: когда использовать какую функцию

VueUse — это коллекция утилит для композиционного API Vue 3, предоставляющая готовые решения для часто встречающихся задач. Этот документ содержит краткое описание основных функций и случаев их применения. Я использую его как шпаргалку, чтобы быстро найти нужную утилиту – а не изобретать велосипед заново.

Полная документация: https://vueuse.org/functions

Управление состоянием и реактивностью

ref и reactive утилиты

useToggle

Когда использовать: Для переключения булевых значений (темы, модальные окна, видимость элементов)

import { useToggle } from "@vueuse/core";

const [isVisible, toggle] = useToggle();
// isVisible.value = false
toggle(); // isVisible.value = true

useLocalStorage / useSessionStorage

Когда использовать: Для сохранения данных в браузере между сессиями

import { useLocalStorage } from "@vueuse/core";

const store = useLocalStorage("my-storage", {
  name: "Apple",
  color: "red",
});
// Автоматическая синхронизация с localStorage

useVModel

Когда использовать: Для создания двустороннего связывания в компонентах

import { useVModel } from "@vueuse/core";

const props = defineProps<{ modelValue: string }>();
const emit = defineEmits(["update:modelValue"]);

const data = useVModel(props, "modelValue", emit);

usePrevious

Когда использовать: Для отслеживания предыдущего значения ref

import { usePrevious } from "@vueuse/core";

const counter = shallowRef("Hello");
const previous = usePrevious(counter);

counter.value = "World";
console.log(previous.value); // 'Hello'

Работа с DOM и элементами

Размеры и позиционирование

useElementSize

Когда использовать: Для отслеживания размеров DOM элемента

import { useElementSize } from "@vueuse/core";

const el = useTemplateRef("el");
const { width, height } = useElementSize(el);

useElementBounding

Когда использовать: Для получения полной информации о границах элемента

import { useElementBounding } from "@vueuse/core";

const el = useTemplateRef("el");
const { x, y, top, right, bottom, left, width, height } = useElementBounding(el);

useWindowSize

Когда использовать: Для отслеживания размеров окна браузера

import { useWindowSize } from "@vueuse/core";

const { width, height } = useWindowSize();

Видимость и пересечения

useElementVisibility

Когда использовать: Для определения видимости элемента в области просмотра

import { useElementVisibility } from "@vueuse/core";

const target = useTemplateRef("target");
const targetIsVisible = useElementVisibility(target);

useIntersectionObserver

Когда использовать: Для более детального контроля над пересечением элементов

import { useIntersectionObserver } from "@vueuse/core";

const target = useTemplateRef("target");
const targetIsVisible = shallowRef(false);

const { stop } = useIntersectionObserver(target, ([entry]) => {
  targetIsVisible.value = entry?.isIntersecting || false;
});

Наблюдение за изменениями

useResizeObserver

Когда использовать: Для отслеживания изменений размеров элемента

import { useResizeObserver } from "@vueuse/core";

const el = useTemplateRef("el");
const text = ref("");

useResizeObserver(el, (entries) => {
  const entry = entries[0];
  const { width, height } = entry.contentRect;
  text.value = `width: ${width}, height: ${height}`;
});

Пользовательский ввод и события

Мышь и указатели

useMouse

Когда использовать: Для отслеживания позиции курсора мыши

import { useMouse } from "@vueuse/core";

const { x, y, sourceType } = useMouse();

usePointer

Когда использовать: Для работы с указателями (включая touch и stylus)

import { usePointer } from "@vueuse/core";

const { x, y, pressure, pointerType } = usePointer();

useMousePressed

Когда использовать: Для отслеживания нажатия кнопок мыши

import { useMousePressed } from "@vueuse/core";

const { pressed } = useMousePressed();

useSwipe

Когда использовать: Для обработки свайпов на мобильных устройствах

import { useSwipe } from "@vueuse/core";

const el = useTemplateRef("el");
const { isSwiping, direction } = useSwipe(el);

Клавиатура

useMagicKeys

Когда использовать: Для обработки комбинаций клавиш

import { useMagicKeys, whenever } from "@vueuse/core";

const keys = useMagicKeys();
const { shift, space, a } = keys;

whenever(keys.shift_space, () => {
  console.log("Shift+Space нажаты");
});

onKeyStroke

Когда использовать: Для обработки отдельных клавиш с дополнительными опциями

import { onKeyStroke } from "@vueuse/core";

onKeyStroke(
  "A",
  (e) => {
    console.log("Клавиша A нажата");
  },
  { dedupe: true },
); // Предотвращает повторные срабатывания при удержании

Фокус

useFocus

Когда использовать: Для управления фокусом элементов

import { useFocus } from "@vueuse/core";

const target = shallowRef();
const { focused } = useFocus(target, { initialValue: true });

useActiveElement

Когда использовать: Для отслеживания активного элемента в документе

import { useActiveElement } from "@vueuse/core";

const activeElement = useActiveElement();

watch(activeElement, (el) => {
  console.log("Фокус изменился на", el);
});

Сетевые запросы

HTTP запросы

useFetch

Когда использовать: Для выполнения HTTP запросов с реактивным состоянием

import { useFetch } from "@vueuse/core";

const { isFetching, error, data } = useFetch(url);

// С обработкой ответа
const { data } = useFetch(url, {
  afterFetch(ctx) {
    if (ctx.data.title === "HxH") ctx.data.title = "Hunter x Hunter";
    return ctx;
  },
});

useAxios

Когда использовать: Для использования Axios с реактивным состоянием

import { useAxios } from "@vueuse/integrations/useAxios";

const { execute } = useAxios();
const result = await execute(url);

WebSocket

useWebSocket

Когда использовать: Для работы с WebSocket соединениями

import { useWebSocket } from "@vueuse/core";

const { status, data, send, open, close } = useWebSocket("ws://websocketurl");

Файлы и медиа

Работа с файлами

useFileDialog

Когда использовать: Для открытия диалога выбора файлов

import { useFileDialog } from "@vueuse/core";

const { files, open, reset, onChange } = useFileDialog({
  accept: "image/*",
  directory: true,
});

onChange((files) => {
  // Обработка выбранных файлов
});

useDropZone

Когда использовать: Для создания зоны перетаскивания файлов

import { useDropZone } from "@vueuse/core";

const dropZoneRef = ref<HTMLDivElement>();

function onDrop(files: File[] | null) {
  // Обработка сброшенных файлов
}

const { isOverDropZone } = useDropZone(dropZoneRef, {
  onDrop,
  dataTypes: ["image/jpeg"],
  multiple: true,
});

Изображения

useImage

Когда использовать: Для загрузки изображений с отслеживанием состояния

// Используется как компонент
<UseImage src="https://place.dog/300/200">
  <template #loading>Загрузка..</template>
  <template #error>Ошибка загрузки</template>
</UseImage>

Браузерные API

Буфер обмена

useClipboard

Когда использовать: Для работы с буфером обмена

import { useClipboard } from "@vueuse/core";

const source = ref("Hello");
const { text, copy, copied, isSupported } = useClipboard({
  source,
  legacy: true, // Поддержка старых браузеров
});

useClipboardItems

Когда использовать: Для работы с комплексными данными в буфере обмена

import { useClipboardItems } from "@vueuse/core";

const mime = "text/plain";
const source = ref([
  new ClipboardItem({
    [mime]: new Blob(["plain text"], { type: mime }),
  }),
]);

const { content, copy, copied, isSupported } = useClipboardItems({ source });

Уведомления

useWebNotification

Когда использовать: Для отправки веб-уведомлений

import { useWebNotification } from "@vueuse/core";

const { show, onClick, onShow, onError, onClose } = useWebNotification({
  title: "Заголовок",
  body: "Текст уведомления",
});

onClick((evt) => {
  // Обработка клика по уведомлению
});

Медиа запросы

useMediaQuery

Когда использовать: Для адаптивного дизайна и определения характеристик устройства

import { useMediaQuery } from "@vueuse/core";

const isLargeScreen = useMediaQuery("(min-width: 1024px)");
const isPreferredDark = useMediaQuery("(prefers-color-scheme: dark)");

useBreakpoints

Когда использовать: Для работы с предопределенными точками останова

import { breakpointsTailwind, useBreakpoints } from "@vueuse/core";

const breakpoints = useBreakpoints(breakpointsTailwind);

const smAndLarger = breakpoints.greaterOrEqual("sm");
const largerThanSm = breakpoints.greater("sm");

Предпочтения пользователя

usePreferredDark

Когда использовать: Для определения предпочтения темной темы

import { usePreferredDark } from "@vueuse/core";

const isDark = usePreferredDark();

useColorMode

Когда использовать: Для управления темами с возможностью переключения

import { useColorMode } from "@vueuse/core";

const mode = useColorMode(); // Ref<'dark' | 'light'>

useNavigatorLanguage

Когда использовать: Для определения языка браузера

import { useNavigatorLanguage } from "@vueuse/core";

const { language } = useNavigatorLanguage();

Состояние соединения

useOnline

Когда использовать: Для отслеживания состояния интернет-соединения

import { useOnline } from "@vueuse/core";

const online = useOnline();

Утилиты для форм

Текстовые поля

useTextareaAutosize

Когда использовать: Для автоматического изменения размера textarea

import { useTextareaAutosize } from "@vueuse/core";

const { textarea, input } = useTextareaAutosize({
  styleProp: "minHeight", // Для совместимости с атрибутом rows
});

Валидация и обработка

useBase64

Когда использовать: Для кодирования данных в base64

import { useBase64 } from "@vueuse/core";

const text = shallowRef("");
const { base64 } = useBase64(text);

Производительность и оптимизация

Дебаунсинг и троттлинг

useDebounceFn

Когда использовать: Для задержки выполнения функции до окончания серии вызовов

import { useDebounceFn } from "@vueuse/core";

const debouncedRequest = useDebounceFn(() => "response", 1000);

// Поддержка async/await
const value = await debouncedRequest();

useThrottleFn

Когда использовать: Для ограничения частоты выполнения функции

import { throttleFilter, useLocalStorage } from "@vueuse/core";

// Обновления в localStorage не чаще раза в секунду
const storage = useLocalStorage(
  "my-key",
  { foo: "bar" },
  {
    eventFilter: throttleFilter(1000),
  },
);

Виртуализация

useVirtualList

Когда использовать: Для отображения больших списков с оптимизацией производительности

import { useVirtualList } from "@vueuse/core";

const { list, containerProps, wrapperProps } = useVirtualList(
  Array.from({ length: 99999 }).map((_, i) => i),
  {
    itemHeight: 22,
  },
);

Мемоизация

useMemoize

Когда использовать: Для кэширования результатов дорогих вычислений

import { useMemoize } from "@vueuse/core";

const getUser = useMemoize(async (userId: number) => axios.get(`users/${userId}`).then(({ data }) => data));

const user1 = await getUser(1); // Запрос
const user1Again = await getUser(1); // Из кэша

Управление временем

Таймеры

useTimeout

Когда использовать: Для выполнения действий с задержкой

import { useTimeout } from "@vueuse/core";

const { ready, start, stop } = useTimeout(1000, { controls: true });

useIntervalFn

Когда использовать: Для периодического выполнения функций

import { useIntervalFn } from "@vueuse/core";

const { pause, resume, isActive } = useIntervalFn(() => {
  // Ваша функция
}, 1000);

useTimeAgo

Когда использовать: Для отображения относительного времени

// Как компонент
<UseTimeAgo v-slot="{ timeAgo }" :time="new Date(2021, 0, 1)">
  Время: {{ timeAgo }}
</UseTimeAgo>

История и отмена действий

Отслеживание изменений

useRefHistory

Когда использовать: Для автоматического отслеживания истории изменений ref

import { useRefHistory } from "@vueuse/core";

const counter = shallowRef(0);
const { history, undo, redo } = useRefHistory(counter);

useManualRefHistory

Когда использовать: Для ручного контроля над созданием снимков состояния

import { useManualRefHistory } from "@vueuse/core";

const counter = shallowRef(0);
const { history, commit, undo, redo } = useManualRefHistory(counter);

counter.value += 1;
commit(); // Создать снимок вручную

useDebouncedRefHistory

Когда использовать: Для отслеживания истории с задержкой

import { useDebouncedRefHistory } from "@vueuse/core";

const counter = shallowRef(0);
const { history, undo, redo } = useDebouncedRefHistory(counter, {
  deep: true,
  debounce: 1000,
});

Интеграция с внешними библиотеками

RxJS

from / toObserver

Когда использовать: Для интеграции Vue refs с RxJS потоками

import { from, toObserver, useSubscription } from "@vueuse/rxjs";
import { interval } from "rxjs";

const count = shallowRef(0);

useSubscription(
  interval(1000)
    .pipe(map((val) => val + 1))
    .subscribe(toObserver(count)),
);

Управление глобальным состоянием

Глобальное состояние

createGlobalState

Когда использовать: Для создания глобального состояния, доступного во всех компонентах

import { createGlobalState, useStorage } from "@vueuse/core";

export const useGlobalState = createGlobalState(() => useStorage("vueuse-local-storage", "initialValue"));

createSharedComposable

Когда использовать: Для создания синглтон-композаблов

import { createSharedComposable, useMouse } from "@vueuse/core";

const useSharedMouse = createSharedComposable(useMouse);

// Во всех компонентах будет один экземпляр useMouse
const { x, y } = useSharedMouse();

Управление скроллом

useScrollLock

Когда использовать: Для блокировки скролла (например, при открытии модальных окон)

import { useScrollLock } from "@vueuse/core";

const el = useTemplateRef("el");
const isLocked = useScrollLock(el);

isLocked.value = true; // Заблокировать скролл

Утилиты жизненного цикла

Безопасные хуки

tryOnMounted / tryOnBeforeUnmount

Когда использовать: Для безопасного использования хуков жизненного цикла в композаблах

import { tryOnBeforeUnmount } from "@vueuse/core";

tryOnBeforeUnmount(() => {
  // Очистка ресурсов
});

tryOnScopeDispose

Когда использовать: Для очистки ресурсов при завершении области видимости

import { tryOnScopeDispose } from "@vueuse/core";

tryOnScopeDispose(() => {
  // Очистка при завершении scope
});

Обработка событий

Глобальные события

onClickOutside

Когда использовать: Для обработки кликов вне элемента

// Как директива
<div
  v-if="modal"
  v-on-click-outside="closeModal"
>
  Содержимое модального окна
</div>

Создание событий

createEventHook

Когда использовать: Для создания кастомных событийных хуков

import { createEventHook } from "@vueuse/core";

export function useMyFetch(url) {
  const fetchResult = createEventHook<Response>();
  const fetchError = createEventHook<any>();

  fetch(url)
    .then((result) => fetchResult.trigger(result))
    .catch((error) => fetchError.trigger(error.message));

  return {
    onResult: fetchResult.on,
    onError: fetchError.on,
  };
}

Заключение

VueUse предоставляет широкий набор утилит для решения большинства задач в Vue.js приложениях. Выбор конкретной функции зависит от:

1. Специфики задачи - нужна ли реактивность, автоматическая очистка, интеграция с DOM
2. Производительности - требуется ли оптимизация (виртуализация, дебаунсинг)
3. Совместимости - поддержка старых браузеров, SSR
4. Архитектуры - локальное или глобальное состояние

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