useCookie

Исходный код
Композабл useCookie для чтения и записи cookie с поддержкой SSR.

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

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

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

Тип

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

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

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

Примеры

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

В приведённом ниже примере создаётся cookie с именем counter. Если куки не существует, то первоначально ему присваивается случайное значение. Всякий раз, когда мы обновляем переменную counter, cookie будет обновляться соответствующим образом.

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

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

<template>
  <div>
    <h1>Счётчик: {{ 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>

Запись с поверхностным наблюдением (watch: 'shallow')

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

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

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>

Куки в серверных маршрутах API

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

server/api/counter.ts
export default defineEventHandler((event) => {
  // Считываем cookie counter
  let counter = getCookie(event, 'counter') || 0

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

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