useCookie

Source
SSR-совместимый компосабл для чтения и записи cookies.

Использование

В страницах, компонентах и плагинах можно использовать useCookie для чтения и записи cookies с учётом SSR.

const cookie = useCookie(name, options)
useCookie работает только в контексте Nuxt.
Возвращаемый ref автоматически сериализует и десериализует значения cookie в JSON.

Тип

Signature
import type { Ref } from 'vue'
import type { CookieParseOptions, CookieSerializeOptions } from 'cookie-es'

export interface CookieOptions<T = any> extends Omit<CookieSerializeOptions & CookieParseOptions, 'decode' | 'encode'> {
  decode?(value: string): T
  encode?(value: T): string
  default?: () => T | Ref<T>
  watch?: boolean | 'shallow'
  readonly?: boolean
}

export interface CookieRef<T> extends Ref<T> {}

export function useCookie<T = string | null | undefined> (
  name: string,
  options?: CookieOptions<T>,
): CookieRef<T>

Параметры

name: Имя cookie.

options: Настройки поведения cookie. Объект может содержать следующие свойства:

Большинство опций передаётся в пакет cookie.

СвойствоТипПо умолчаниюОписание
decode(value: string) => TdecodeURIComponent + destr.Функция декодирования значения cookie. Значение cookie — строка с ограниченным набором символов; decode преобразует его в строку или объект.
Примечание: при ошибке в функции вернётся исходное недекодированное значение.
encode(value: T) => stringJSON.stringify + encodeURIComponentФункция кодирования значения в строку для cookie.
default() => T | Ref<T>undefinedФункция, возвращающая значение по умолчанию, если cookie нет. Может возвращать Ref.
watchboolean | 'shallow'trueСледить за изменениями и обновлять cookie. true — глубокий watch, 'shallow' — только верхний уровень, false — отключить.
Примечание: при изменении cookie извне обновляйте значение вручную через refreshCookie.
readonlybooleanfalseЕсли true, запись в cookie отключена.
maxAgenumberundefinedВремя жизни cookie в секундах (атрибут Max-Age). Число округляется вниз. По умолчанию не задано.
expiresDateundefinedДата истечения cookie. По умолчанию не задана; без неё или без maxAge cookie считается сессионной и удаляется при закрытии браузера.
Примечание: по спецификации при наличии обоих expires и maxAge приоритет у maxAge; лучше задавать одну и ту же дату.
httpOnlybooleanfalseАтрибут HttpOnly.
Примечание: при true клиентский JavaScript не видит cookie в document.cookie.
securebooleanfalseАтрибут Secure.
Примечание: при true без HTTPS браузер не отправляет cookie на сервер — возможны ошибки гидрации.
partitionedbooleanfalseАтрибут Partitioned. Ещё не финализирован в стандартах; многие клиенты могут его игнорировать. Подробнее.
domainstringundefinedАтрибут Domain. По умолчанию — текущий домен.
pathstring'/'Атрибут Path. По умолчанию — "default path".
sameSiteboolean | stringundefinedАтрибут SameSite.
- true или 'strict' — Strict
- false — атрибут не задаётся
- 'lax' — Lax
- 'none' — None (cross-site).

Возвращаемое значение

Vue Ref<T> со значением cookie. Изменение ref обновляет cookie (если не задано readonly). Ref совместим с SSR и работает на клиенте и сервере.

Примеры

Базовое использование

В примере создаётся cookie counter. Если его нет, задаётся случайное значение. При обновлении переменной counter обновляется и cookie.

app/app.vue
<script setup lang="ts">
const counter = useCookie('counter')

counter.value ||= Math.round(Math.random() * 1000)
</script>

<template>
  <div>
    <h1>Counter: {{ counter || '-' }}</h1>
    <button @click="counter = null">
      сброс
    </button>
    <button @click="counter--">
      -
    </button>
    <button @click="counter++">
      +
    </button>
  </div>
</template>

Только чтение

<script setup lang="ts">
const user = useCookie(
  'userInfo',
  {
    default: () => ({ score: -1 }),
    watch: false,
  },
)

if (user.value) {
  // фактический cookie `userInfo` не обновится
  user.value.score++
}
</script>

<template>
  <div>Очки пользователя: {{ user?.score }}</div>
</template>

Записываемые cookies

<script setup lang="ts">
const list = useCookie(
  'list',
  {
    default: () => [],
    watch: 'shallow',
  },
)

function add () {
  list.value?.push(Math.round(Math.random() * 1000))
  // cookie list от этого не обновится
}

function save () {
  // cookie list обновится
  list.value &&= [...list.value]
}
</script>

<template>
  <div>
    <h1>Список</h1>
    <pre>{{ list }}</pre>
    <button @click="add">
      Добавить
    </button>
    <button @click="save">
      Сохранить
    </button>
  </div>
</template>

Cookies в API-маршрутах

В серверных API-маршрутах для работы с cookies используйте getCookie и setCookie из пакета h3.

server/api/counter.ts
export default defineEventHandler((event) => {
  // Чтение cookie counter
  let counter = getCookie(event, 'counter') || 0

  // Увеличение counter на 1
  setCookie(event, 'counter', ++counter)

  // JSON-ответ
  return { counter }
})
Прочитайте и отредактируйте живой пример в Docs > 4 X > Examples > Advanced > Use Cookie.