Cookies
Nuxt 为读取和写入 cookies 提供了一套针对服务端渲染友好的组合式 api
使用
在你的页面、组件或者是插件中,针对一条特定的 cookie 记录,可以使用useCookie
创建一条响应式的引用。
const cookie = useCookie(name, options)
👉useCookie
只在setup
或Lifecycle Hooks
中有效
😌useCookie
ref 将自动转义 cookie 的值成 JSON 格式。
示例
下面的例子创建了一条称为 counter 的 cookie 记录。如果这条 cookie 记录不存在,那么在初始化这条记录时可以把它设置成一个任意值。无论何时当我们更新了 counter 变量的值的时候,这条 cookie 记录也会相应的自动更新。
<template>
<div>
<h1>Counter: {{ counter || '-' }}</h1>
<button @click="counter = null">reset</button>
<button @click="counter--">-</button>
<button @click="counter++">+</button>
</div>
</template>
<script setup>
const counter = useCookie('counter')
counter.value = counter.value || Math.round(Math.random() * 1000)
</script>
注意
示例报错 reading 'default',需要 const counter = useCookie('counter', { default: ()=>0 })
配置项
组合式 Cookie 接受几个配置项来让你修改 cookie 的行为。
大部分配置项是直接引用的 cookie 包中的内容。
maxAge
/ expires
maxAge
明确规定了响应头中Set-Cookie
的Max-Age
属性值,该属性接收number
类型,单位秒。默认不设置最大超时时间。
expires
:明确规定了响应头中Set-Cookie
的Expires
属性值,该属性接收Date
类型。默认不设置该值。 大部分客户端将它视为“持久化的 cookie”,只在例如退出 web 浏览器应用程序时才会删除 cookie。
💡注意: cookie 的存储模型规定如果同时设置了expires
和maxAge
,以maxAge
优先。但是并不是所有的客户端都遵守这一规定,所以同时设置时应该让他们都指向相同的日期和时间!
如果都不社会expires
和maxAge
,那么 cookie 将仅用于会话,当用户关闭浏览器的时候被移除。
httpOnly
明确规定了响应头中Set-Cookie
的HttpOnly
属性值,该属性接收boolean
类型。当httpOnly
为“真值” 时HttpOnly
属性被设置,反之不设置。默认HttpOnly
属性不设置。
💡注意: 小心当该值被设置成true
时,合格的客户端是不允许用户侧通过 javaScript 脚本的方式查看documnet.cookie
。
secure
明确规定了响应头中Set-Cookie
的Secure
属性值,该属性接受boolean
类型。当 secure 设置为true
时,Secure
被设置,反之不设置。默认Secure
不设置。
💡注意: 小心当该值被设置成true
时,如果当浏览器和服务器没有建立 https 连接,合格的客户端将不会传输 cookie。这可能会导致错误。
domain
明确规定了响应头中Set-Cookie
的Domain
属性值。默认domain
不设置,大部分客户端认为 cookie 仅适用于当前域。
path
明确规定了响应头中Set-Cookie
的Path
属性值。默认值为“default path”。
sameSite
明确规定了响应头中Set-Cookie
的SameSite
属性值
true
将SameSite
属性值设为Strict
,以严格执行同站请求。false
不设置SameSite
属性。'lax'
将 SameSite 属性值设为Lax
,允许部分第三方请求携带Cookie
。'none'
允许跨站发送Cookie
。'strict'
将 SameSite 属性值设为Strict
,以严格执行同站请求。
关于不同实施级别的更多信息可以在 规范 中查阅。
encode
指定 cookie 值的编码函数。因为 cookie 的值是一个有限的字符集(必须是一个简单的字符串),所以该函数需要将值编码为适合 cookie 的字符串。
默认编码方式是 JSON.stringify
+ encodeURIComponent
。
decode
指定 cookie 值的解码函数。因为 cookie 值为一个有限的字符集(必须是一串简单的字符串),该函数需要将编码的 cookie 值解码成 javaScript 中的字符串或对象类型。
默认解码函数是 decodeURIComponent
+ destr .
💡注意: 如果在该函数抛出异常,那么原始的未经解码的 cookie 值将会作为 value 值返回。
API 路由中处理 cookies
你可以使用h3
包中的useCookie
和setCookie
在访问服务器的 API 路由时候处理 cookie 的值。
示例:
import { useCookie, setCookie } from 'h3'
export default (req, res) => {
// Read counter cookie
let counter = useCookie(req, 'counter') || 0
// Increase counter cookie by 1
setCookie(res, 'counter', ++counter)
// Send JSON response
return { counter }
}