cookick
A simple utilities for browser cookies APIs
为什么
已经有非常多的 cookie 相关工具了,甚至多年以前,在我初次接触 js 学习之处,也折腾过 COOKIE
这么个小玩意儿。
但是当我现在需要一个足够简单(现代 web 开发中,有着更多强大、丰富的本地存储方案,js 对于 cookie 的依赖越来越少)、支持标准的 cookie 工具时,我发现目前我能找到的各类 cookie 库(例如 js-cookie
、jquery-cookie
甚至还有react-cookie
???)都或多或少存在一些问题,有些破坏了标准,有些不支持较新的标准,有些是过度设计,过于繁重(COOKIE
就是过度设计了)。
而直到我发现了 jshttp/cookie 这个标准库,虽然其是针对 HTTP cookies
规范定制,但是可以几乎完整适用于浏览器端。所以我基于该库做了稍微的修改定制,也就有了现在这个 cookick
(名字由 cookie
和 kick
组合而来)
安装
// use npm$ npm install cookick --save // use yarn$ yarn add cookick
注意:cookick
也提供了umd
格式的包,你可以将cookick
的umd
包传到服务器上,然后通过script
标签在页面中引入,直接通过window.cookick
调用。
<!-- from self hosted cdn --> <!-- from unpkg --> <!-- from jsDelivr -->
运行环境要求
cookick
采用TypeScript
开发,并用rollup
和babel
进行构建成 ES5 代码后发布。要保证cookick
在所有平台都能正常运行,请确保你的运行环境中支持以下必要条件:
Object.assign
IE*
要求Object.defineProperty
< IE9
要求Object.freeze
< IE9
要求
注:在
create-react-app
或者vue-cli
构建的项目中,都是可以安全运行cookick
的。
cookick
也可以在服务端中运行,但是不推荐。建议优先选择其它与服务端框架结合更紧密的其它 cookie 方法,例如 Express.js 推荐的cookie-parser
。
如何使用
cookick
提供了一组方法用于获取或者设置 cookie。
getCookie
服务端在调用该方法前,需要先调用
updateCookieSource
设置 cookie 解析来源。
declare ;
使用示例:
; getCookie'foo'; // 获取名称为 foo 的cookie
setCookie
仅在浏览器端生效,服务端应当利用其返回值自行设置响应头来处理 cookie。
declare ;
使用示例:
; // 默认调用:在当前域下,path=/, 创建foo=bar的cookiesetCookie'foo', 'bar'; // 指定path参数setCookie'foo', 'bar', ; // 设置doaminsetCookie'foo', 'bar', ; // 设置过期时间,建议使用maxAge参数,设置过期秒数: https://javascript.info/cookie#expires-max-agesetCookie'foo', 'bar', ; // 设置 secure、httpOnly、sameSite等// 这些属性并不是所有浏览器都支持,有些目前仅在 server-http 协议支持,请使用前慎重考虑setCookie'foo', 'bar', ; /*=================服务端==================*/req.setHeader'set-cookie', setCookie'foo', 'bar';
delCookie
仅在浏览器端生效,服务端应当利用其返回值自行设置响应头来处理 cookie。
declare ;
使用示例:
; delCookie'foo'; // 删除名称为 foo 的cookie // 如果cookie在其他子路径或者domain下,需要指定明确的path或者domain才能删除delCookie'foo', ; /*=================服务端==================*/req.setHeader'set-cookie', delCookie'foo';
getAllCookies
服务端在调用该方法前,需要先调用
updateCookieSource
设置 cookie 解析来源。
declare ;
使用示例:
; getAllCookies; // 解析所有的cookie为一个object对象
serialize
declare ;
序列化一个新的 cookie 为字符串,你可以将其用于在服务端或者浏览器端设置 cookie:
; // 浏览器端document.cookie = newCookieStr; // 服务端response.setHeader'set-cookie', newCookieStr;
setDefault
设置默认参数
declare ;
使用示例:
; // 在调用 setCookie 没有传递path、domain情况下,会总是将cookie根据默认参数进行设置setDefault;
updateCookieSource
该方法建议仅在服务端调用,在调用getCookie
getAllCookies
等方法前,通过该方法将服务端请求的 cookie 字符串更新到cookick
:
; app.get'/',;