Js-cookie是一款用于处理 cookie 的简单、轻量级 JavaScript API。接下来我们就来了解下js-cookie,并学会快速的使用它。

• 支持所有浏览器
• 接受任何类型编码字符
• 大量的测试用例
• 无依赖性，不需要依赖其他任何包
• 支持 ES 模块
• 支持 AMD/CommonJS
• RFC 6265 兼容
• 启用自定义编码/解码
• < 800 字节压缩！

安装

1、使用NPM安装

js-cookie 支持npm下载安装，安装代码如下：

$ npm i js-cookie

npm 包有一个 module 字段指向库的 ES 模块变体，主要是为 ES 模块感知捆绑器提供支持，而它的 browser 字段指向 UMD 模块以完全向后兼容。

2、直接下载引用

小伙伴可以直接点击访问js-cookie库的github仓库进行下载。文章的最后我也会提供百度网盘的下载链接给大家，以供哪些网速不是太好的同学使用。

需要注意的是，从版本 3 开始，发行版包含该库的两个变体，一个 ES 模块和一个 UMD 模块。注意不同的扩展名：.mjs 表示 ES 模块，而 .js 是 UMD 模块。如何在浏览器中加载 ES 模块的示例：

<script type="module" src="/path/to/js.cookie.mjs"></script>
<script type="module">
  import Cookies from '/path/to/js.cookie.mjs'

  Cookies.set('foo', 'bar')
</script>

并非所有浏览器都原生支持 ES 模块。出于这个原因，npm 包/发布提供了 ES 和 UMD 模块变体，您可能希望将 ES 模块与 UMD 后备一起包含以解决此问题：

<script type="module" src="/path/to/js.cookie.mjs"></script>
<script nomodule defer src="/path/to/js.cookie.js"></script>

这里我们以延迟方式加载 nomodule 脚本，因为 ES 模块默认是延迟的。根据您使用库的方式，这可能不是绝对必要的。有关nomodule的使用，可以参考之前写的：你真的会用script吗？noscript又是什么？这篇文章的介绍。

3、使用CDN

官方问题提供了一个JSDELiVR的CDN服务地址。大家可以点击访问。可以根据需求选择配置CDN包含的文件，我这边给一个包含完整js-cookie的CDN使用代码：

<script src="https://cdn.jsdelivr.net/npm/js-cookie@3.0.1/dist/js.cookie.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/js-cookie@3.0.1/index.min.js"></script>

ES Module

如何从另一个模块导入 ES 模块的示例：

import Cookies from 'js-cookie'

Cookies.set('foo', 'bar')

基本用法

• 创建一个在整个网站上有效的 cookie

Cookies.set('name', 'value')

• 创建一个从现在起 7 天后过期的 cookie，在整个站点中有效

Cookies.set('name', 'value', { expires: 7 })

• 创建一个过期cookie，对当前页面的路径有效

Cookies.set('name', 'value', { expires: 7, path: '' })

• 读取cookie

Cookies.get('name') // => 'value'
Cookies.get('nothing') // => undefined

• 读取所有可见cookie

Cookies.get() // => { name: 'value' }

注意：无法通过传递其中一个 cookie 属性（在写入相关 cookie 时可能会或可能不会使用）来读取特定 cookie：

Cookies.get('foo', { domain: 'sub.example.com' }) // `domain` won't have any effect...!

名称为 foo 的 cookie 仅在 .get() 上可用，前提是它从调用代码的位置可见；阅读时域和/或路径属性将不起作用。

• 删除cookie

Cookies.remove('name')

• 删除一个对当前页面路径有效的cookie

Cookies.set('name', 'value', { path: '' })
Cookies.remove('name') // fail!
Cookies.remove('name', { path: '' }) // removed!

非常重要的一点，删除 cookie 并且您不依赖默认属性时，您必须传递用于设置 cookie 的完全相同的路径和域属性：

Cookies.remove('name', { path: '', domain: '.yourdomain.com' })

注意：删除不存在的 cookie 既不会引发任何异常，也不会返回任何值。

命名空间冲突

如果存在与命名空间 Cookie 冲突的任何危险，则 noConflict 方法将允许您定义一个新的命名空间并保留原来的命名空间。这在第三方站点上运行脚本时特别有用，例如作为小部件或 SDK 的一部分。

// Assign the js-cookie api to a different variable and restore the original "window.Cookies"
var Cookies2 = Cookies.noConflict()
Cookies2.set('name', 'value')

注意： .noConflict 方法在使用 AMD 或 CommonJS 时不是必需的，因此它不会在这些环境中公开。

编码问题

该项目符合 RFC 6265。 cookie-name 或 cookie-value 中不允许的所有特殊字符都使用百分比编码使用每个对应的 UTF-8 Hex 进行编码。
cookie-name 或 cookie-value 中唯一允许且仍在编码的字符是百分比 % 字符，它被转义以便将百分比输入解释为文字。
请注意，默认的编码/解码策略意味着只能在 js-cookie 读取/写入的 cookie 之间进行互操作。要覆盖默认的编码/解码策略，您需要使用转换器。

Cookie属性

Cookie 属性默认值可以通过 withAttributes() 创建 api 实例来全局设置，或者通过将普通对象作为最后一个参数传递来单独为每次调用 Cookies.set(…) 设置。每次调用属性会覆盖默认属性。

expires

定义何时删除 cookie。值必须是一个数字，它将被解释为从创建之日算起的天数或一个 Date 实例。如果省略，cookie 将成为会话 cookie。

要创建在不到一天内过期的 cookie，您可以查看 Wiki 上的常见问题解答。

• 默认值：当用户关闭浏览器时，Cookie 被删除。

• 示例

Cookies.set('name', 'value', { expires: 365 })
Cookies.get('name') // => 'value'
Cookies.remove('name')

path

一个字符串，指示 cookie 可见的路径。

• 默认值：/

• 示例

Cookies.set('name', 'value', { path: '' })
Cookies.get('name') // => 'value'
Cookies.remove('name', { path: '' })

关于 Internet Explorer 的注意事项：

由于底层 WinINET InternetGetCookie 实现中的一个模糊错误，如果使用包含文件名的路径属性设置 IE 的 document.cookie，它将不会返回 cookie。

Internet Explorer Cookie Internals (FAQ)

这意味着不能使用 window.location.pathname 设置路径，以防此类路径名包含如下文件名：/check.html（或至少，无法正确读取此类 cookie）。

事实上，您绝不应该允许不受信任的输入来设置 cookie 属性，否则您可能会受到 XSS 攻击。

domain

一个字符串，指示 cookie 应该可见的有效域。该 cookie 也将对所有子域可见。

• 默认值：Cookie 仅对创建 cookie 的页面的域或子域可见，Internet Explorer 除外（见下文）。
• 示例：

假设在 enjoytoday.cn 上创建了一个 cookie：

Cookies.set('name', 'value', { domain: 'cookie.enjoytoday.cn' })
Cookies.get('name') // => undefined (need to read at 'cookie.enjoytoday.cn')

关于 Internet Explorer 默认行为的注意事项：

Q3：如果我没有为 cookie 指定 DOMAIN 属性，IE 还是会将它发送到所有嵌套的子域？
答：是的，example.com 上设置的 cookie 将被发送到 sub2.sub1.example.com。
Internet Explorer 在这方面不同于其他浏览器。

Internet Explorer Cookie Internals (FAQ)

这意味着如果您省略domain属性，它将在 IE 中对子域可见。

secure

true 或 false，指示 cookie 传输是否需要安全协议 (https)。

• 默认值：没有安全协议要求。
• 示例

Cookies.set('name', 'value', { secure: true })
Cookies.get('name') // => 'value'
Cookies.remove('name')

sameSite

一个字符串，允许控制浏览器是否与跨站点请求一起发送 cookie。

• 默认值：不设置
• 示例

Cookies.set('name', 'value', { sameSite: 'strict' })
Cookies.get('name') // => 'value'
Cookies.remove('name')

设置默认值：

const api = Cookies.withAttributes({ path: '/', domain: '.example.com' })

转换

读取

创建一个覆盖默认解码实现的新 api 实例。所有依赖于正确解码才能工作的 get 方法，例如 Cookies.get() 和 Cookies.get('name')，将为每个 cookie 运行给定的转换器。返回的值将用作 cookie 值。

读取只能使用转义函数解码的 cookie 之一的示例：

document.cookie = 'escaped=%u5317'
document.cookie = 'default=%E5%8C%97'
var cookies = Cookies.withConverter({
  read: function (value, name) {
    if (name === 'escaped') {
      return unescape(value)
    }
    // Fall back to default for all other cookies
    return Cookies.converter.read(value, name)
  }
})
cookies.get('escaped') // 北
cookies.get('default') // 北
cookies.get() // { escaped: '北', default: '北' }

写入

创建一个覆盖默认编码实现的新 api 实例：

Cookies.withConverter({
  write: function (value, name) {
    return value.toUpperCase()
  }
})

TypeScript 申明

js-cookie提供了typesrcipt的types包以供下载查阅。

$ npm i @types/js-cookie