useCookie

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

const cookie = useCookie(name, options)

Пример

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

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

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

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

Параметры

Данный композабл принимает несколько опций, которые позволяют изменять поведение cookie.

Большинство опций будут напрямую переданы в пакет cookie.

maxAge / expires

Используйте эти параметры для установки срока действия cookie.

maxAge: Определяет number (в секундах), которое будет значением для атрибута Max-Age Set-Cookie. Указанное число будет преобразовано в целое число путем округления вниз. По умолчанию maxAge не задается.

expires: Определяет объект Date в качестве значения для атрибута Expires Set-Cookie. По умолчанию срок действия не установлен. Большинство клиентов (браузеров) будут считать это «непостоянным cookie» и удалят его при определенном условии, например, при выходе из приложения веб-браузера.

httpOnly

Определяет boolean значение для атрибута HttpOnly Set-Cookie. Если значение истинно, атрибут HttpOnly устанавливается, в противном случае - нет. По умолчанию атрибут HttpOnly не установлен.

secure

Определяет boolean значение для атрибута Secure Set-Cookie. Если значение истинно, атрибут Secure устанавливается, в противном случае - нет. По умолчанию атрибут Secure не установлен.

partitioned

Определяет boolean значение для атрибута Partitioned Set-Cookie. Если значение истинно, атрибут Partitioned устанавливается, в противном случае - нет. По умолчанию атрибут Partitioned не установлен.

domain

Определяет значение для атрибута Domain Set-Cookie. По умолчанию домен не задается, и большинство клиентов будут считать, что cookie применяется только к текущему домену.

path

Определяет значение для атрибута Path Set-Cookie. По умолчанию путь считается "default path".

sameSite

Определяет boolean или string значение для атрибута SameSite Set-Cookie.

• true установит для атрибута SameSite значение Strict для строгого соблюдения same-site.
• false не будет устанавливать атрибут SameSite.
• 'lax' установит атрибут SameSite в значение Lax для нестрогого соблюдения правил на одном сайте.
• 'none' установит атрибут SameSite в None для явного межсайтового cookie.
• 'strict' установит для атрибута SameSite значение Strict для строгого соблюдения same-site.

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

encode

Определяет функцию, которая будет использоваться для кодирования значения cookie. Поскольку значение cookie имеет ограниченный набор символов (и должно быть простой строкой), эта функция может быть использована для кодирования значения в строку, подходящую для значения cookie.

По умолчанию используется кодировщик JSON.stringify + encodeURIComponent.

decode

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

По умолчанию используется декодер decodeURIComponent + destr.

default

Определяет функцию, которая возвращает значение cookie по умолчанию. Функция также может возвращать Ref.

readonly

Позволяет получить доступ к значению cookie без возможности его установки.

watch

Определяет boolean или string значение для слежения за данными cookie ref.

• true - Будет следить за изменениями данных cookie ref и их вложенных свойств (по умолчанию).
• shallow - Будет следить за изменениями данных cookie ref только для свойств верхнего уровня.
• false - Не будет следить за изменениями данных cookie ref.

Пример 1:

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

if (user.value && user.value !== null) {
  user.value.score++; // userInfo cookie не обновится при этом изменении
}
</script>

<template>
  <div>User score: {{ user?.score }}</div>
</template>

Пример 2:

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

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

function save() {
  if (list.value && list.value !== null) {
    list.value = [...list.value]
    // list cookie обновится при помощи такого изменения
  }
}
</script>

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

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

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

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

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

  // Отправляем ответ в формате JSON
  return { counter }
})