Skip to content
A simple utilities for browser cookies APIs.
JavaScript TypeScript
Branch: master
Clone or download

Latest commit

Fetching latest commit…
Cannot retrieve the latest commit at this time.

Files

Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
dist
npm
src
.editorconfig
.gitignore
LICENSE
README.md
package.json
rollup.config.js
tsconfig.json

README.md

cookick

A simple utilities for browser cookies APIs

npm definitionTypes gzip download issues license github github github

为什么

已经有非常多的 cookie 相关工具了,甚至多年以前,在我初次接触 js 学习之处,也折腾过 COOKIE 这么个小玩意儿。

但是当我现在需要一个足够简单(现代 web 开发中,有着更多强大、丰富的本地存储方案,js 对于 cookie 的依赖越来越少)、支持标准的 cookie 工具时,我发现目前我能找到的各类 cookie 库(例如 js-cookiejquery-cookie甚至还有react-cookie???)都或多或少存在一些问题,有些破坏了标准,有些不支持较新的标准,有些是过度设计,过于繁重(COOKIE就是过度设计了)。

而直到我发现了 jshttp/cookie 这个标准库,虽然其是针对 HTTP cookies 规范定制,但是可以几乎完整适用于浏览器端。所以我基于该库做了稍微的修改定制,也就有了现在这个 cookick(名字由 cookiekick 组合而来)

补充与universal-cookie的对比:

universal-cookie是我阅读react-cookie时发现的这个库(当然,我认为任何 react/vue-cookie 这种库都不应该存在,作者都是被驴踢了脑袋),非常意外的发现其实现思路与cookick惊人一致。如果我早两个小时前发现这个库,cookick 就不会产生了。但是我也在阅读了 universal-cookie的源码后,基于以下的几点不同,我还是倾向于 cookick 是一个更好的实现

  • universal-cookiecookick都是基于jsHTTP/cookie实现,所以两者对于 cookie 的操作都是一致的,并且操作 cookie 的方式、对标准的支持也都是一致的
  • cookickpath做了更多支持优化,默认为根路径: /,也支持相对路径;universal-cookie 则是默认行为,即当前页面路径。经验来看,默认/还是更符合通用场景的
  • cookick 更加适合 ES Module 规范下的子导出使用,因为其方法名都是明确的 cookie 相关命名,例如getCookie setCookie等;而universal-cookie这是简洁的get set等名称,只适合与对象访问式调用
  • universal-cookie考虑了服务端调用,所以其使用需要先初始化后调用、还支持绑定 cookie 变动监听;cookick没有这些考虑,并且认为服务端使用应当直接使用jsHTTP/cookie,而 cookie 变动监听属于过度设计,在 cookie 在 web 开发中日渐式微的状况下,这种设计“纯属想多了”
  • universal-cookie 名字很长,cookick名字较短

安装

cookick

// use npm
$ npm install cookick --save

// use yarn
$ yarn add cookick

注意cookick也提供了umd格式的包,你可以将cookickumd包传到服务器上,然后通过script标签在页面中引入,直接通过window.cookick调用。

<!-- from self hosted cdn -->
<script src="{{ YOUR_CDN_URL }}/cookick.umd.production.js"></script>

<!-- from unpkg -->
<script src="https://unpkg.com/cookick/dist/cookick.umd.production.js"></script>

<!-- from jsDelivr -->
<script src="https://cdn.jsdelivr.net/npm/cookick/dist/cookick.umd.production.js"></script>

运行环境要求

cookick采用TypeScript开发,并用rollupbabel进行构建成 ES5 代码后发布。要保证cookick在所有平台都能正常运行,请确保你的运行环境中支持以下必要条件:

  • Object.assign IE*要求
  • Object.defineProperty < IE9要求
  • Object.freeze < IE9要求

注:在create-react-app或者vue-cli构建的项目中,都是可以安全运行cookick的。

如何使用

cookick提供了一组方法用于获取或者设置 cookie。

getCookie

declare function getCookie(name: string): string | undefined;

使用示例:

import { getCookie } from 'cookick';

getCookie('foo'); // 获取名称为 foo 的cookie

setCookie

interface CookieOptions {
    path?: string;
    domain?: string;
    expires?: Date; // 必须是Date对象
    maxAge?: number; // 整数,表示maxAge秒后过期。建议总是使用maxAge,不要使用expires。maxAge和expires如果同时存在,会忽略expires参数
    httpOnly?: boolean;
    secure?: boolean;
    sameSite?: boolean | 'lax' | 'strict' | 'none';
}

declare function setCookie(name: string, val: string | number, options?: CookieOptions): void;

使用示例:

import { setCookie } from 'cookick';

// 默认调用:在当前域下,path=/, 创建foo=bar的cookie
setCookie('foo', 'bar');

// 指定path参数
setCookie('foo', 'bar', {
    path: '/sub'
    // 甚至可以使用相对路径
    // path: '../another/sub'
});

// 设置doamin
setCookie('foo', 'bar', {
    domain: 'cookie.com'
});

// 设置过期时间,建议使用maxAge参数,设置过期秒数: https://javascript.info/cookie#expires-max-age
setCookie('foo', 'bar', {
    maxAge: 60 * 60 * 24 * 7
});

// 设置 secure、httpOnly、sameSite等
// 这些属性并不是所有浏览器都支持,有些目前仅在 server-http 协议支持,请使用前慎重考虑
setCookie('foo', 'bar', {
    secure: true,
    httpOnly: true,
    sameSite: 'strict'
});

delCookie

declare function delCookie(name: string, options?: CookieOptions): void;

使用示例:

import { delCookie } from 'cookick';

delCookie('foo'); // 删除名称为 foo 的cookie

// 如果cookie在其他子路径或者domain下,需要指定明确的path或者domain才能删除
delCookie('foo', {
    path: '/sub'
});

getAllCookies

declare function getAllCookies(): {
    [P: string]: string | undefined;
};

使用示例:

import { getAllCookies } from 'cookick';

getAllCookies(); // 解析所有的cookie为一个object对象

setDefault

设置默认参数

declare function setDefault(options: CookieOptions): CookieOptions;

使用示例:

import { setDefault } from 'cookick';

// 在调用 setCookie 没有传递path、domain情况下,会总是将cookie根据默认参数进行设置
setDefault({
    path: '/basename',
    domain: '.root.domain'
});

参考文档

document.cookie MDN 规范说明

maxAge sameSite等新属性的兼容性

You can’t perform that action at this time.