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>

:::danger 注意 示例报错reading ‘default’,需要 const counter = useCookie(‘counter’, { default: ()=>0 }) :::

StackBlitz打开

配置项

组合式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 }
}