useCookie
在您的页面、组件和插件中,您可以使用useCookie,这是一个 SSR 友好的可组合项,用于读取和写入 cookie。
const cookie = useCookie(name, options)
useCookie 仅在 setup 或 Lifecycle Hooks 期间有效。
useCookie ref 会自动将 cookie 值序列化和反序列化为 JSON。
示例
下面的示例创建了一个名为 counter 的 cookie。 如果 cookie 不存在,它最初被设置为一个随机值。 每当我们更新 counter 变量时,cookie 都会相应更新。
<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>
选项
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:
<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:
<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>
在 API 路由中处理 Cookie
您可以使用 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 }
})