useCookie

在您的页面、组件和插件中，您可以使用 useCookie，这是一个服务器端渲染 (SSR) 友好的可组合函数，用于读取和写入 Cookie。

const cookie = useCookie(name, options)

useCookie 仅在 Nuxt 上下文中有效。

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

在文档 > 示例 > 高级 > 使用 Cookie 中查看和编辑实时示例。

当 Cookie 发生更改时，可以使用 refreshCookie 手动刷新 useCookie 值。

选项

Cookie 可组合函数接受多个选项，您可以使用这些选项修改 Cookie 的行为。

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

`maxAge` / `expires`

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

maxAge：指定 数字（以秒为单位），作为 Max-Age Set-Cookie 属性的值。给定的数字将通过向下取整转换为整数。默认情况下，不设置最大生存期。

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

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

如果未设置 expires 和 maxAge 中的任何一个，则 Cookie 将仅限于会话，并在用户关闭浏览器时删除。

`httpOnly`

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

在将此设置为 true 时要小心，因为符合标准的客户端不允许客户端 JavaScript 在 document.cookie 中查看 Cookie。

`secure`

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

在将此设置为 true 时要小心，因为符合标准的客户端在将来如果浏览器没有 HTTPS 连接，则不会将 Cookie 发送回服务器。这可能导致水合错误。

`partitioned`

指定 Partitioned Set-Cookie 属性的 布尔 值。如果为真，则设置 Partitioned 属性；否则不设置。默认情况下，不设置 Partitioned 属性。

这是一个尚未完全标准化的属性，将来可能会更改。这也意味着许多客户端可能会忽略此属性，直到它们了解它为止。更多信息可以在提案中找到。

`domain`

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

`path`

指定 Path Set-Cookie 属性的值。默认情况下，路径被认为是 “默认路径”。

`sameSite`

指定 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 的值返回。

true - 将监视 Cookie ref 数据更改及其嵌套属性（默认值）。
shallow - 将仅监视 Cookie ref 数据更改的顶级属性。
false - 不会监视 Cookie ref 数据更改。

当 Cookie 发生更改时，可以使用 refreshCookie 手动刷新 useCookie 值。

示例 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 not update with this change
}
</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 not update with this change
}

function save() {
  if (list.value && list.value !== null) {
    list.value = [...list.value]
    // list cookie update with this change
  }
}
</script>

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

API 路由中的 Cookie

您可以使用 h3 包中的 getCookie 和 setCookie 在服务器 API 路由中设置 Cookie。

server/api/counter.ts

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

  // Increase counter cookie by 1
  setCookie(event, 'counter', ++counter)

  // Send JSON response
  return { counter }
})

在文档 > 示例 > 高级 > 使用 Cookie 中查看和编辑实时示例。

useAsyncData

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

useError

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

示例

选项