Cookie useCookie

useCookie 是一个 SSR 友好的可组合对象，用于读取和写入 cookie。

useCookie

在您的页面、组件和插件中，您可以使用useCookie，这是一个 SSR 友好的可组合项，用于读取和写入 cookie。

const cookie = useCookie(name, options)

useCookie 仅在 setup 或 Lifecycle Hooks 期间有效。

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

示例

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

vue

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

案例演示：在StackBlitz编辑

选项

Cookie 可组合项接受多个选项，让您可以修改 cookie 的行为。

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

maxAge / expires

maxAge 将 number(以秒为单位)指定为 Max-Age Set-Cookie 属性。给定的数字将通过向下舍入转换为整数。默认情况下，没有设置最大年龄。

expires：将 Date 对象指定为 Expires Set-Cookie 属性. 默认情况下，没有设置过期时间。大多数客户会认为这是一个“非持久性 cookie”，并且将在退出网络浏览器应用程序等情况下将其删除。

注意： cookie 存储模型规范指出
如果 expires 和 maxAge 被设置，然后 maxAge 优先，但不是所有的客户端都可以遵守这个，所以如果两者都设置了，它们应该指向相同的日期和时间！

如果 expires 和 maxAge 均未设置，则 cookie 将仅用于会话，并在用户关闭浏览器时删除。

httpOnly

该选项指定了 HttpOnly Set-Cookie 属性的布尔值参考。

当值为true时，会设置 HttpOnly 属性，否则不会设置。默认情况下，不设置 HttpOnly 属性。

当将httpOnly选项设置为true时要小心，因为符合标准的客户端将不允许客户端JavaScript通过document.cookie查看cookie。
换句话说，将此选项设置为true会增加cookie的安全性，但也会限制对cookie的可见性和可访问性。

secure

指定 Secure Set-Cookie 属性的boolean 值。当设置为true时，Secure属性会被设置，否则不会。

默认情况下，Secure属性未被设置。

如果被设置，浏览器会要求在使用此Cookie时必须通过HTTPS连接发送请求，以确保其只在加密的连接中传输，从而增强了Cookie的安全性。

注意： 当将 secure 属性设置为 true 时，遵循标准的客户端将不会在未使用 HTTPS 连接的情况下将 cookie 发送回服务器，这可能会导致数据预取期间的一些错误。因此在设置 secure 为 true 时需要谨慎，需要确保浏览器和服务器都在使用 HTTPS 连接。

domain

指定 Domain Set-Cookie 属性的值。
默认情况下，没有域已设置，大多数客户端会考虑仅将 cookie 应用于当前域。

path

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

sameSite

指定 SameSite Set-Cookie 属性的布尔值或字符串值。

true 会将 SameSite 属性设置为 Strict 以严格执行同一站点。
false 不会设置 SameSite 属性。
'lax' 会将 SameSite 属性设置为 Lax 以实现宽松的同站点执行。
'none' 会将显式跨站点 cookie 的 SameSite 属性设置为 None。
'strict' 会将 SameSite 属性设置为 Strict 以严格执行同一站点。

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

encode

指定将用于对 cookie 的值进行编码的函数。由于 cookie 的值具有有限的字符集(并且必须是简单的字符串)，因此可以使用此函数将值编码为适合 cookie 值的字符串。

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

decode

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

默认解码器是 decodeURIComponent + destr。

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

default

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

watch

指定 watch cookie 引用数据的“布尔”或“字符串”值。

true - 将观察 cookie 引用数据的变化及其嵌套属性。 (默认)
shallow - 将仅观察顶级属性的 cookie 引用数据更改
false 不会观察 cookie 引用数据的变化。

示例 1:

vue

<script setup>
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:

vue

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

function add() {
  list.value?.push(Math.round(Math.random() * 1000))
  // 列出 cookie 不会随此更改更新
}

function save() {
  if (list.value && list.value !== null)
    list.value = [...list.value]
    // 使用此更改列出 cookie 更新
}
</script>

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

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

示例:

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

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

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

案例演示：