useCookie
在您的页面、组件和插件中,您可以使用 useCookie
,这是一个支持 SSR 的组合式 API,用于读取和写入 cookies。
const cookie = useCookie(name, options)
useCookie
仅在 Nuxt 上下文 中有效。useCookie
引用将自动将 cookie 值序列化和反序列化为 JSON。示例
下面的示例创建了一个名为 counter
的 cookie。如果 cookie 不存在,它会最初设置为一个随机值。每当我们更新 counter
变量时,cookie 也会相应地更新。
<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>
refreshCookie
手动刷新 useCookie
值。选项
cookie 组合式 API 接受多个选项,您可以通过这些选项修改 cookie 的行为。
大多数选项将被直接传递给 cookie 包。
maxAge
/ expires
使用这些选项设置 cookie 的过期时间。
maxAge
: 指定一个 number
(以秒为单位),作为 Max-Age
Set-Cookie
属性 的值。
给定的数字将通过向下取整转换为整数。 默认情况下,不设置最大年龄。
expires
: 指定一个 Date
对象作为 Expires
Set-Cookie
属性 的值。
默认情况下,不设置过期。大多数客户端将把此视为“非持久 cookie”,并在关闭 web 浏览器应用程序时删除它。
expires
也未设置 maxAge
,则 cookie 将仅限于会话,并在用户关闭浏览器时删除。httpOnly
为 HttpOnly
Set-Cookie
属性 指定一个 boolean
值。当为真时,设置 HttpOnly
属性;否则不设置。默认为不设置 HttpOnly
属性。
true
,因为合规的客户端将不允许客户端 JavaScript 在 document.cookie
中看到 cookie。secure
为 Secure
Set-Cookie
属性 指定一个 boolean
值。当为真时,设置 Secure
属性;否则不设置。默认为不设置 Secure
属性。
true
,因为合规的客户端如果浏览器没有 HTTPS 连接将不会将 cookie 发送回服务器。这可能导致水合错误。partitioned
为 Partitioned
Set-Cookie
属性指定一个 boolean
值。当为真时,设置 Partitioned
属性;否则不设置。默认为不设置 Partitioned
属性。
domain
为 Domain
Set-Cookie
属性 指定值。默认情况下不设置域,大多数客户端将只对当前域应用 cookie。
path
为 Path
Set-Cookie
属性 指定值。默认情况下,路径被视为“默认路径”(https://tools.ietf.org/html/rfc6265#section-5.1.4)。
sameSite
为 SameSite
Set-Cookie
属性 指定一个 boolean
或 string
值。
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。
default
指定一个返回 cookie 默认值的函数。该函数也可以返回一个 Ref
。
readonly
允许访问 cookie 值,而没有设置它的能力。
watch
指定一个 boolean
或 string
值,用于 watch cookie 引用数据。
true
- 将监视 cookie 引用数据的变化及其嵌套属性(默认)。shallow
- 仅监视 cookie 引用数据的顶层属性变化。false
- 不监视 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 不会随着这个变化而更新
}
</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 路由中的 cookies。
export default defineEventHandler(event => {
// 读取 counter cookie
let counter = getCookie(event, 'counter') || 0
// 将 counter cookie 增加 1
setCookie(event, 'counter', ++counter)
// 发送 JSON 响应
return { counter }
})