useCookie · Nuxt Composables

在你的页面、组件和插件中，你可以使用useCookie，一个适用于服务器端渲染（SSR）的组合函数，用于读取和写入cookie。

const cookie = useCookie(name, options)

useCookie的ref会自动将cookie值序列化和反序列化为JSON。

示例

下面的示例创建了一个名为counter的cookie。如果该cookie不存在，它将被初始设置为一个随机值。每当我们更新counter变量时，cookie也会相应地更新。

app.vue

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

counter.value = 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>

Read and edit a live example in Docs > Examples > Advanced > Use Cookie.

选项

Cookie组合函数接受几个选项，可以修改cookie的行为。

大多数选项将直接传递给cookie包。

`maxAge` / `expires`

使用这些选项来设置cookie的过期时间。

maxAge：指定一个number（以秒为单位）作为Max-Age Set-Cookie属性的值。给定的数字将被四舍五入为整数。默认情况下，不设置最大年龄。

expires：指定一个Date对象作为Expires Set-Cookie属性的值。默认情况下，不设置过期时间。大多数客户端将把它视为“非持久cookie”，并在条件（比如退出Web浏览器应用程序）下删除它。

cookie存储模型规范指出，如果同时设置了expires和maxAge，则maxAge优先，但并非所有客户端都遵守这一规定，因此，如果两者都设置了，它们应该指向相同的日期和时间！

如果expires和maxAge都没有设置，那么cookie将仅在会话期间存在，并在用户关闭浏览器时被删除。

`httpOnly`

指定一个boolean值作为HttpOnly Set-Cookie属性的值。如果为真，则设置HttpOnly属性；否则不设置。默认情况下，不设置HttpOnly属性。

当将此值设置为true时，请小心，因为符合规范的客户端将不允许客户端JavaScript看到document.cookie中的cookie。

`secure`

指定一个boolean值作为Secure Set-Cookie属性的值。如果为真，则设置Secure属性；否则不设置。默认情况下，不设置Secure属性。

当将此值设置为true时，请小心，因为符合规范的客户端将不会在将来将cookie发送回服务器，如果浏览器没有HTTPS连接，这可能导致hydration错误。

`domain`

指定一个值作为Domain Set-Cookie属性的值。默认情况下，不设置域，大多数客户端将仅将cookie应用于当前域。

`path`

指定一个值作为Path Set-Cookie属性的值。默认情况下，路径被认为是"默认路径"。

`sameSite`

指定一个boolean或string值作为SameSite Set-Cookie属性的值。

true将SameSite属性设置为Strict以进行严格的同站点执行。
false不设置SameSite属性。
'lax'将SameSite属性设置为Lax以进行宽松的同站点执行。
'none'将SameSite属性设置为None以进行明确的跨站点cookie。
'strict'将SameSite属性设置为Strict以进行严格的同站点执行。

有关不同执行级别的更多信息，请参见规范。

`encode`

指定一个函数，用于编码cookie的值。由于cookie的值具有有限的字符集（必须是简单字符串），因此此函数可用于将一个值编码为适合cookie值的字符串。

默认编码器是JSON.stringify + encodeURIComponent。

`decode`

指定一个函数，用于解码cookie的值。由于cookie的值具有有限的字符集（必须是简单字符串），因此此函数可用于将先前编码的cookie值解码为JavaScript字符串或其他对象。

默认解码器是decodeURIComponent + destr。

如果从此函数抛出错误，则将返回原始的、未解码的cookie值作为cookie的值。

`default`

指定一个返回cookie的默认值的函数。该函数还可以返回一个Ref。

`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 }}</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>

API路由中的Cookies

你可以使用h3包中的getCookie和setCookie来在服务端API路由中设置cookie。

server/api/counter.ts

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

   // 将counter cookie增加1
  setCookie(event, 'counter', ++counter)

  // 发送JSON响应
  return { counter }
})

Read and edit a live example in Docs > Examples > Advanced > Use Cookie.

useAsyncData

useAsyncData提供了一种在SSR友好的组合式中访问异步解析数据的方式。

useError

useError可组合函数返回正在处理的全局Nuxt错误。