useCookie

useCookie es un composable compatible con SSR para leer y escribir cookies.

Uso

Dentro de tus páginas, componentes y plugins, puedes usar useCookie para leer y escribir cookies de una manera compatible con SSR.

const cookie = useCookie(name, options)

useCookie solo funciona en el contexto de Nuxt.

El ref devuelto serializará y deserializará automáticamente los valores de las cookies a JSON.

Tipo

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>

Parámetros

name: El nombre de la cookie.

options: Opciones para controlar el comportamiento de la cookie. El objeto puede tener las siguientes propiedades:

La mayoría de las opciones se pasarán directamente al paquete cookie.

Propiedad	Tipo	Predeterminado	Descripción
`decode`	`(value: string) => T`	`decodeURIComponent` + destr.	Función personalizada para decodificar el valor de la cookie. Dado que el valor de una cookie tiene un conjunto de caracteres limitado (y debe ser una cadena simple), esta función se puede usar para decodificar un valor de cookie previamente codificado en una cadena de JavaScript u otro objeto. Nota: Si se lanza un error desde esta función, el valor original de la cookie no decodificado se devolverá como el valor de la cookie.
`encode`	`(value: T) => string`	`JSON.stringify` + `encodeURIComponent`	Función personalizada para codificar el valor de la cookie. Dado que el valor de una cookie tiene un conjunto de caracteres limitado (y debe ser una cadena simple), esta función se puede usar para codificar un valor en una cadena adecuada para el valor de una cookie.
`default`	`() => T \| Ref<T>`	`undefined`	Función que devuelve el valor predeterminado si la cookie no existe. La función también puede devolver un `Ref`.
`watch`	`boolean \| 'shallow'`	`true`	Si se debe observar los cambios y actualizar la cookie. `true` para observación profunda, `'shallow'` para observación superficial, es decir, cambios de datos solo para propiedades de nivel superior, `false` para deshabilitar. Nota: Actualiza manualmente los valores de `useCookie` cuando una cookie ha cambiado con `refreshCookie`.
`readonly`	`boolean`	`false`	Si es `true`, desactiva la escritura en la cookie.
`maxAge`	`number`	`undefined`	Edad máxima en segundos para la cookie, es decir, el valor para el atributo `Max-Age` `Set-Cookie`. El número dado se convertirá en un entero redondeando hacia abajo. Por defecto, no se establece una edad máxima.
`expires`	`Date`	`undefined`	Fecha de expiración para la cookie. Por defecto, no se establece una expiración. La mayoría de los clientes considerarán esto como una "cookie no persistente" y la eliminarán en una condición como salir de una aplicación de navegador web. Nota: La especificación del modelo de almacenamiento de cookies establece que si se establecen tanto `expires` como `maxAge`, entonces `maxAge` tiene prioridad, pero no todos los clientes pueden obedecer esto, por lo que si ambos están establecidos, deben apuntar a la misma fecha y hora. Si no se establece ni `expires` ni `maxAge`, la cookie será solo de sesión y se eliminará cuando el usuario cierre su navegador.
`httpOnly`	`boolean`	`false`	Establece el atributo HttpOnly. Nota: Ten cuidado al establecer esto en `true`, ya que los clientes compatibles no permitirán que el JavaScript del lado del cliente vea la cookie en `document.cookie`.
`secure`	`boolean`	`false`	Establece el atributo `Secure` `Set-Cookie`. Nota: Ten cuidado al establecer esto en `true`, ya que los clientes compatibles no enviarán la cookie de vuelta al servidor en el futuro si el navegador no tiene una conexión HTTPS. Esto puede llevar a errores de hidratación.
`partitioned`	`boolean`	`false`	Establece el atributo `Partitioned` `Set-Cookie`. Nota: Este es un atributo que aún no ha sido completamente estandarizado, y puede cambiar en el futuro. Esto también significa que muchos clientes pueden ignorar este atributo hasta que lo entiendan. Más información se puede encontrar en la propuesta.
`domain`	`string`	`undefined`	Establece el atributo `Domain` `Set-Cookie`. Por defecto, no se establece un dominio, y la mayoría de los clientes considerarán aplicar la cookie solo al dominio actual.
`path`	`string`	`'/'`	Establece el atributo `Path` `Set-Cookie`. Por defecto, el camino se considera el "camino predeterminado".
`sameSite`	`boolean \| string`	`undefined`	Establece el atributo `SameSite` `Set-Cookie`. - `true` establecerá el atributo `SameSite` en `Strict` para una aplicación estricta del mismo sitio. - `false` no establecerá el atributo `SameSite`. - `'lax'` establecerá el atributo `SameSite` en `Lax` para una aplicación laxa del mismo sitio. - `'none'` establecerá el atributo `SameSite` en `None` para una cookie explícita de sitio cruzado. - `'strict'` establecerá el atributo `SameSite` en `Strict` para una aplicación estricta del mismo sitio.

Valores de Retorno

Devuelve un Ref<T> de Vue que representa el valor de la cookie. Actualizar el ref actualizará la cookie (a menos que readonly esté establecido). El ref es compatible con SSR y funcionará tanto en el cliente como en el servidor.

Ejemplos

Uso Básico

El siguiente ejemplo crea una cookie llamada counter. Si la cookie no existe, inicialmente se establece en un valor aleatorio. Cada vez que actualizamos la variable counter, la cookie se actualizará en consecuencia.

app.vue

<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>

Cookies de Solo Lectura

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

if (user.value) {
  // la cookie real `userInfo` no se actualizará
  user.value.score++
}
</script>

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

Cookies Modificables

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

function add() {
  list.value?.push(Math.round(Math.random() * 1000))
  // la cookie list no se actualizará con este cambio
}

function save() {
  if (list.value) {
    // la cookie real `list` se actualizará
    list.value = [...list.value]
  }
}
</script>

<template>
  <div>
    <h1>List</h1>
    <pre>{{ list }}</pre>
    <button @click="add">Add</button>
    <button @click="save">Save</button>
  </div>
</template>

Cookies en Rutas de API

Puedes usar getCookie y setCookie del paquete h3 para establecer cookies en rutas de API del servidor.

server/api/counter.ts

export default defineEventHandler(event => {
  // Leer cookie de contador
  let counter = getCookie(event, 'counter') || 0

  // Incrementar cookie de contador en 1
  setCookie(event, 'counter', ++counter)

  // Enviar respuesta JSON
  return { counter }
})

Editar y previsualizar el código de ejemploexamples > advanced > use-cookie

※Esta página es una traducción no oficial de la documentación oficial de Nuxt.js.

La página correspondiente en la documentación oficial está aquí:
https://nuxt.com/docs/3.x/api/composables/use-cookie