@just4/cookie v2.1.0

@just4/cookie

提供浏览器端的 cookie 操作接口。

特性

• 提供了浏览器端 cookie 读取、写入以及删除的接口。
• 写入 cookie 时，支持设置有效时间、主机名、路径、Secure、SameSite 等属性。

安装

npm i @just4/cookie

调用

安装完毕之后，就可以引入并调用相关的方法：

import {
  getCookie,
  setCookie,
  removeCookie
} from '@just4/cookie';

读取 cookie

getCookie('nickname');

默认情况下，读取 cookie 时分别是用 encodeURIComponent 和 decodeURIComponent 进行编码和解码的。如果要用其他编解码函数，可以通过 encode 和 decode 选项指定。

getCookie('nickname', {
  encode(content) {
    //...
  },
  decode(content) {
    //...
  }
});

写入 cookie

最简单的 cookie 写入只需指定 key 和 value 的值。

setCookie('nickname', 'Tom');

但 Cookie 还有多个属性（见 MDN 的《Set-Cookie》文档），除了 HttpOnly 以外，其他均可在浏览器端进行设置。可通过 setCookie 函数的选项参数对 cookie 的属性进行设置。

有效时间

有效时间有绝对时间和相对时间两种形式：

• 使用绝对时间时，要传入对应时间点的日期对象。
• 使用相对时间时，传入“数量 单位”格式的字符串，其中单位可以为单数也可以为复数。

// 相对时间
setCookie('nickname', 'Tom', {
  expires: '1 month'  // 有效时间为一个月
});

// 相对时间
setCookie('nickname', 'Tom', {
  expires: '2 years'  // 有效时间为两年
});

// 绝对时间
setCookie('nickname', 'Tom', {
  expires: new Date(2023, 0, 1)  // 2023 年 1 月 1 日 0 点过期
});

主机名和路径

setCookie('nickname', 'Tom', {
  domain: '.abc.com',
  path: '/'
});

仅在 https 请求中可用

setCookie('nickname', 'Tom', {
  secure: true
});

SameSite

关于 SameSite 的说明可以参阅 MDN 的《SameSite cookies》。

setCookie('nickname', 'Tom', {
  sameSite: 'strict'
});

// SameSite 设为 none 时需要同时设置 Secure
setCookie('nickname', 'Tom', {
  sameSite: 'none',
  secure: true
});

指定内容编码

默认情况下，写入 cookie 时是用 encodeURIComponent 进行编码的。如果要用其他编码函数，可以通过 encode 选项指定。

setCookie('nickname', '汤姆', {
  encode(content) {
    //...
  }
});

删除 cookie

removeCookie('nickname');

删除 cookie 实质上是把 cookie 设为过期，因此 removeCookie 支持 setCookie 的所有选项。

相关文档

• API 文档

Changelog

v2.1.0

• 获取 cookie 时，区分无 cookie 和 cookie 值为空字符串这两种情况。

v2.0.0

• 设置 cookie 有效时间时，对相对时间的处理修改为通过 @just4/util 中的 addRelativeTime 实现，因此：
  • 不再支持小数的数量（例如 0.5 month）。因为单位不一定是常量（例如一个月的总天数可能是 28、29、30、31），数量为小数时，表达的意思不明确。
  • 计算方式的变化。
    • 在 1.x 版本中，1 个月按 30 天算。如果有效时间为 1 个月，就是在当前时间的 30 天后过期；自本版本开始，变更为在下个月同一天同样的时间点过期。
    • 在 1.x 版本中，1 年按 365 天算。如果有效时间为 1 年，就是在当前时间的 365 天后过期；自本版本开始，变更为在下一年同一天同样的时间点过期。