useCookie

useCookie é um composable amigável ao SSR para ler e escrever cookies.

Uso

Dentro de suas páginas, componentes e plugins, você pode usar useCookie para ler e escrever cookies de uma maneira amigável ao SSR.

const cookie = useCookie(name, options)

useCookie só funciona no contexto do Nuxt.

O ref retornado irá automaticamente serializar e desserializar os valores dos cookies para 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: O nome do cookie.

options: Opções para controlar o comportamento do cookie. O objeto pode ter as seguintes propriedades:

A maioria das opções será passada diretamente para o pacote cookie.

Propriedade	Tipo	Padrão	Descrição
`decode`	`(value: string) => T`	`decodeURIComponent` + destr.	Função personalizada para decodificar o valor do cookie. Como o valor de um cookie tem um conjunto de caracteres limitado (e deve ser uma string simples), esta função pode ser usada para decodificar um valor de cookie previamente codificado em uma string JavaScript ou outro objeto. Nota: Se um erro for lançado a partir desta função, o valor original, não decodificado, do cookie será retornado como o valor do cookie.
`encode`	`(value: T) => string`	`JSON.stringify` + `encodeURIComponent`	Função personalizada para codificar o valor do cookie. Como o valor de um cookie tem um conjunto de caracteres limitado (e deve ser uma string simples), esta função pode ser usada para codificar um valor em uma string adequada para o valor de um cookie.
`default`	`() => T \| Ref<T>`	`undefined`	Função que retorna o valor padrão se o cookie não existir. A função também pode retornar um `Ref`.
`watch`	`boolean \| 'shallow'`	`true`	Se deve observar mudanças e atualizar o cookie. `true` para observação profunda, `'shallow'` para observação superficial, ou seja, mudanças de dados apenas para propriedades de nível superior, `false` para desativar. Nota: Atualize manualmente os valores de `useCookie` quando um cookie for alterado com `refreshCookie`.
`readonly`	`boolean`	`false`	Se `true`, desativa a escrita no cookie.
`maxAge`	`number`	`undefined`	Idade máxima em segundos para o cookie, ou seja, o valor para o atributo `Max-Age` `Set-Cookie`. O número fornecido será convertido em um inteiro arredondando para baixo. Por padrão, nenhuma idade máxima é definida.
`expires`	`Date`	`undefined`	Data de expiração para o cookie. Por padrão, nenhuma expiração é definida. A maioria dos clientes considerará isso como um "cookie não persistente" e o excluirá em uma condição como sair de um aplicativo de navegador da web. Nota: A especificação do modelo de armazenamento de cookies afirma que se ambos `expires` e `maxAge` estiverem definidos, então `maxAge` tem precedência, mas nem todos os clientes podem obedecer a isso, então se ambos estiverem definidos, eles devem apontar para a mesma data e hora! Se nenhum dos `expires` e `maxAge` estiver definido, o cookie será apenas de sessão e removido quando o usuário fechar o navegador.
`httpOnly`	`boolean`	`false`	Define o atributo HttpOnly. Nota: Tenha cuidado ao definir isso como `true`, pois clientes compatíveis não permitirão que o JavaScript do lado do cliente veja o cookie em `document.cookie`.
`secure`	`boolean`	`false`	Define o atributo `Secure` `Set-Cookie`. Nota: Tenha cuidado ao definir isso como `true`, pois clientes compatíveis não enviarão o cookie de volta ao servidor no futuro se o navegador não tiver uma conexão HTTPS. Isso pode levar a erros de hidratação.
`partitioned`	`boolean`	`false`	Define o atributo `Partitioned` `Set-Cookie`. Nota: Este é um atributo que ainda não foi totalmente padronizado e pode mudar no futuro. Isso também significa que muitos clientes podem ignorar este atributo até que o entendam. Mais informações podem ser encontradas na proposta.
`domain`	`string`	`undefined`	Define o atributo `Domain` `Set-Cookie`. Por padrão, nenhum domínio é definido, e a maioria dos clientes considerará aplicar o cookie apenas ao domínio atual.
`path`	`string`	`'/'`	Define o atributo `Path` `Set-Cookie`. Por padrão, o caminho é considerado o "caminho padrão".
`sameSite`	`boolean \| string`	`undefined`	Define o atributo `SameSite` `Set-Cookie`. - `true` definirá o atributo `SameSite` como `Strict` para uma aplicação estrita do mesmo site. - `false` não definirá o atributo `SameSite`. - `'lax'` definirá o atributo `SameSite` como `Lax` para uma aplicação relaxada do mesmo site. - `'none'` definirá o atributo `SameSite` como `None` para um cookie explícito de site cruzado. - `'strict'` definirá o atributo `SameSite` como `Strict` para uma aplicação estrita do mesmo site.

Valores de Retorno

Retorna um Ref<T> do Vue representando o valor do cookie. Atualizar o ref atualizará o cookie (a menos que readonly esteja definido). O ref é amigável ao SSR e funcionará tanto no cliente quanto no servidor.

Exemplos

Uso Básico

O exemplo abaixo cria um cookie chamado counter. Se o cookie não existir, ele é inicialmente definido para um valor aleatório. Sempre que atualizarmos a variável counter, o cookie será atualizado de acordo.

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

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

if (user.value) {
  // o cookie real `userInfo` não será atualizado
  user.value.score++
}
</script>

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

Cookies Graváveis

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

function add() {
  list.value?.push(Math.round(Math.random() * 1000))
  // o cookie list não será atualizado com esta mudança
}

function save() {
  if (list.value) {
    // o cookie real `list` será atualizado
    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 em Rotas de API

Você pode usar getCookie e setCookie do pacote h3 para definir cookies em rotas de API do servidor.

server/api/counter.ts

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

  // Aumentar cookie counter em 1
  setCookie(event, 'counter', ++counter)

  // Enviar resposta JSON
  return { counter }
})

Editar e visualizar o código de exemploexamples > advanced > use-cookie

※Esta página é uma tradução não oficial da documentação oficial do Nuxt.js.

A página correspondente na documentação oficial está aqui:
https://nuxt.com/docs/3.x/api/composables/use-cookie