@alicloud/cookie

@alicloud/cookie

（又一个）Cookie 的操作工具。

何时使用

需要读写浏览器 Cookie 时。本工具包有如下特点：

• 无任何额外的依赖。
• 考虑了安全传输（HTTPS）和跨站点访问（iframe）的问题，以最佳实践设定 SameSite 和 Secure 字段。了解更多：《在 HTTPS 和 iframe 下关于 SameSite + Secure 行为的研究》
• 考虑了三方 Cookie 禁用的问题，以最佳实践设定 Partitioned 字段。

API

getCookies()

获取当前页面可以访问到的全部 Cookie。

function getCookies(): Record<string, string>;
function getAllCookies(): Record<string, string>;

getAllCookies() 是一个别名。

getCookie()

获取当前页面可以访问到的某一个特定的 Cookie。

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

setCookie()

写 Cookie。

function setCookie(name: string, value: string, extra: {
  // 默认为当前页面的二级域名，如 `.aliyun.com`
  // 如果是 IP 则为 IP，如 `127.0.0.1`
  domain?: string; 
  // 默认 '/'
  path?: string; 
  // 默认 180，若传入 0 则 Cookie 的 expires 为空，即成为 Session Cookie
  // 若传入 -1 则相当于删除 Cookie
  days?: number; 
  // 默认 true，传入 false 可保存原始的值（比如 value 已经由 base64 编码过）
  encoding?: boolean; 
} = {}): void;

deleteCookie()

删除特定 Cookie。本质上是设置 expires 为过去的时间，浏览器会自动清理过期的 Cookie。

function deleteCookie(name: string, extra: {
  domain?: string;
  path?: string;
} = {}): void;

canSetCookies()

嗅探是否可以在当前页写 Cookie。

注意，如果浏览器只是禁用了三方 Cookie（而非完全禁用 Cookie 功能），那还是可以通过 CHIPS 方案在兼容的浏览器下写 Partitioned Cookie。

由于本方法不接受参数，所以命名为复数，而非用来特指的单数。

function canSetCookies(): boolean;