胖蔡说技术
随便扯扯

一款轻量级处理cookie的javascript库推荐,无依赖

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

关于

如果你还想要了解js-cookie更多信息,可参考下方信息进行获取了解:

  • github仓库地址:https://github.com/js-cookie/js-cookie
  • 百度网盘下载地址
链接:https://pan.baidu.com/s/1NLYm6mbikUF_WLpsjcQq1A
提取码:1qct

当前版本为v3.0.1, 如需更新版本请访问github自行下载。

赞(2) 打赏
转载请附上原文出处链接:胖蔡说技术 » 一款轻量级处理cookie的javascript库推荐,无依赖
分享到: 更多 (0)

请小编喝杯咖啡~

支付宝扫一扫打赏

微信扫一扫打赏