useCookie
useCookie 是一个 SSR 友好的可组合函数，用于读取和写入 cookies。
用法
在页面、组件和插件中，你可以使用 useCookie 以一种支持 SSR 的方式读取和写入 cookies。
用法
const cookie = useCookie(name, options)
useCookie 仅在 Nuxt 上下文 中可用。返回的 ref 会自动将 cookie 值序列化和反序列化为 JSON。
类型
Signature
import type { Ref } from 'vue'
import type { CookieParseOptions, CookieSerializeOptions } from 'cookie-es'
export interface CookieOptions<T = any> extends Omit<CookieSerializeOptions & CookieParseOptions, 'decode' | 'encode'> {
decode?(value: string): T
encode?(value: T): string
default?: () => T | Ref<T>
watch?: boolean | 'shallow'
readonly?: boolean
refresh?: boolean
}
export interface CookieRef<T> extends Ref<T> {}
export function useCookie<T = string | null | undefined> (
name: string,
options?: CookieOptions<T>,
): CookieRef<T>
参数
name：cookie 的名称。
options：用于控制 cookie 行为的选项。该对象可以包含以下属性：
大多数选项将直接传递给 cookie 包。
| Property | Type | Default | Description |
|---|---|---|---|
decode | (value: string) => T | decodeURIComponent + destr. | 用于解码 cookie 值的自定义函数。由于 cookie 的值具有有限的字符集（并且必须是一个简单字符串），因此该函数可用于将先前编码的 cookie 值解码为 JavaScript 字符串或其他对象。 **注意：**如果该函数抛出错误，将返回原始的、未解码的 cookie 值作为该 cookie 的值。 |
encode | (value: T) => string | JSON.stringify + encodeURIComponent | 用于编码 cookie 值的自定义函数。由于 cookie 的值具有有限的字符集（并且必须是一个简单字符串），因此该函数可用于将一个值编码为适合作为 cookie 值的字符串。 |
default | () => T | Ref<T> | undefined | 当 cookie 不存在时返回默认值的函数。该函数也可以返回一个 Ref。 |
watch | boolean | 'shallow' | true | 是否监听变化并更新 cookie。true 表示深度监听，'shallow' 表示浅层监听，即只监测顶层属性的数据变化，false 表示禁用。**注意：**当 cookie 发生变化时，可使用 refreshCookie 手动刷新 useCookie 的值。 |
refresh v4.4 | boolean | false | 如果为 true，则每次显式写入时（例如 cookie.value = cookie.value），都会刷新 cookie 的过期时间，即使值本身没有变化。注意：过期时间不会自动刷新——你必须给 .value 赋值才能触发它。 |
readonly | boolean | false | 如果为 true，则禁止向 cookie 写入。 |
maxAge | number | undefined | cookie 的最长存活时间（秒），即 Max-Age Set-Cookie 属性 的值。给定的数字会通过向下取整转换为整数。默认不设置最大存活时间。 |
expires | Date | (() => Date | undefined) | undefined | cookie 的过期日期，或一个返回该日期的 getter。当提供函数时，它会在每次写入 cookie 时执行，因此在值被重新设置时可以刷新过期时间。返回 undefined 会创建一个会话 cookie。getter 应该是纯函数（无副作用）。默认不设置过期时间。大多数客户端会将其视为“非持久性 cookie”，并会在诸如退出浏览器应用等情况下将其删除。注意：cookie 存储模型规范 说明，如果同时设置了 expires 和 maxAge，则 maxAge 优先，但并非所有客户端都遵循这一点，因此如果两者都设置了，它们应指向相同的日期和时间！如果 expires 和 maxAge 都未设置，则 cookie 仅在会话期间有效，并会在用户关闭浏览器时移除。 |
httpOnly | boolean | false | 设置 HttpOnly 属性。 **注意：**将其设置为 true 时要小心，因为符合规范的客户端不会允许客户端 JavaScript 在 document.cookie 中看到该 cookie。 |
secure | boolean | false | 设置 Secure Set-Cookie 属性。**注意：**将其设置为 true 时要小心，因为如果浏览器没有 HTTPS 连接，符合规范的客户端将不会在未来把 cookie 发送回服务器。这可能导致 hydration 错误。 |
partitioned | boolean | false | 设置 Partitioned Set-Cookie 属性。**注意：**这是一个尚未完全标准化的属性，未来可能会发生变化。 这也意味着在许多客户端理解它之前，可能会忽略该属性。 更多信息可查看 proposal。 |
domain | string | undefined | 设置 Domain Set-Cookie 属性。默认不设置域，大多数客户端会认为该 cookie 仅应用于当前域。 |
path | string | '/' | 设置 Path Set-Cookie 属性。默认情况下，路径被视为 "默认路径"。 |
sameSite | boolean | string | undefined | 设置 SameSite Set-Cookie 属性。- true 会将 SameSite 属性设置为 Strict，以实现严格的同站策略。- false 不会设置 SameSite 属性。- 'lax' 会将 SameSite 属性设置为 Lax，以实现宽松的同站策略。- 'none' 会将 SameSite 属性设置为 None，以显式允许跨站 cookie。- 'strict' 会将 SameSite 属性设置为 Strict，以实现严格的同站策略。 |
返回值
返回一个表示 cookie 值的 Vue Ref<T>。更新该 ref 将更新 cookie（除非设置了 readonly）。该 ref 支持 SSR，可在客户端和服务端使用。
Example
基本用法
下面的示例创建了一个名为 counter 的 cookie。如果该 cookie 不存在，则最初将其设置为一个随机值。每当我们更新 counter 变量时，cookie 将相应更新。
app/app.vue
<script setup lang="ts">
const counter = useCookie('counter')
counter.value ||= Math.round(Math.random() * 1000)
</script>
<template>
<div>
<h1>Counter: {{ counter || '-' }}</h1>
<button @click="counter = null">
重置
</button>
<button @click="counter--">
-
</button>
<button @click="counter++">
+
</button>
</div>
</template>
只读 Cookies
app/app.vue
<script setup lang="ts">
const user = useCookie(
'userInfo',
{
default: () => ({ score: -1 }),
watch: false,
},
)
if (user.value) {
// 实际的 `userInfo` cookie 不会被更新
user.value.score++
}
</script>
<template>
<div>用户分数：{{ user?.score }}</div>
</template>
可写 Cookies
app/app.vue
<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 () {
// 实际的 `list` cookie 会被更新
list.value &&= [...list.value]
}
</script>
<template>
<div>
<h1>列表</h1>
<pre>{{ list }}</pre>
<button @click="add">
添加
</button>
<button @click="save">
保存
</button>
</div>
</template>
刷新 Cookies
app/app.vue
<script setup lang="ts">
const session = useCookie(
'session', {
maxAge: 60 * 60, // 1 小时
refresh: true,
default: () => 'active',
})
// 即使值没有改变，
// 每次设置器被调用时，
// cookie 的过期时间都会被刷新
session.value = 'active'
</script>
<template>
<div>会话：{{ session }}</div>
</template>
使用 Getter 动态设置过期时间
当你希望 cookie 每次被写入时都拥有一个新的过期日期时，请为 expires 使用一个函数（例如，滑动会话或令牌）：
app/app.vue
<script setup lang="ts">
const token = useCookie('token', {
// 每次写入时都会重新计算——请保持这个 getter 纯净
expires: () => new Date(Date.now() + 60 * 60 * 1000), // 1 小时后
})
// 赋予新值也会刷新 cookie 的过期时间
token.value = 'new-token'
</script>
API 路由中的 Cookies
你可以在服务端 API 路由中使用来自 h3 包的 getCookie 和 setCookie 来设置 cookies。
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 > 4 X > Examples > Advanced > Use Cookie.