阅读 463

cookieStore:操作cookie的原生API

什么是Cookie Store API?

Cookie Store API它为开发者提供了document.cookie的异步替代方案。

  1. 通过异步访问 cookie,避免主线程卡顿。
  2. 避免轮询 cookie,因为可以观察到 cookie 的变化。
  3. 向service workers(PWA)公开HTTP cookies.

如何使用

documents和service workers都可以通过全局对象上的cookieStore访问相同的API。

Cookie Store API中的所有方法都返回Promise。

非安全域名cookieStore is not defined(localhost除外)。set,delete方法必须在https环境下才能使用。

获取cookie


  1. await cookieStore.get 获取一个cookie。返回值为CookieListItem对象。
  2. await cookieStore.getAll 获取全部cookie。返回值为CookieListItem的数组

await命令后面的Promise对象,运行结果可能是rejected,所以最好把await命令放在try...catch代码块中。

  dictionary CookieListItem {
    USVString name;
    USVString value;
    USVString? domain;
    USVString path;
    DOMTimeStamp? expires;
    boolean secure;
    CookieSameSite sameSite; // Cookie 允许服务器要求某个 Cookie 在跨站请求时不会被发送 none | strict | lax
  }
复制代码

这两个方法参数可以使用字符串或者对象。当使用对象时,key只能为name或者url(必须为document.URL,不是则会报错)。

  interface Option {
    name?: string,
    url?: document.URL
  }
  
  try {
    const cookie = await cookieStore.get(name:String|options:Option)
  } catch(e) {
    console.error(`获取cookie失败: ${e}`)
  }
复制代码

当key的值不为两者之一时,CookieStore会认为它是一个空对象。

get-error.png

修改cookie


set和delete只能在https环境下操作,不然会报错。

await cookieStore.set 设置cookie。返回值null

  try {
    await cookieStore.set('test', '1');
  } catch (e) {
    console.error(`写入cookie失败: ${e}`);
  }
复制代码

上面的写法其实是以下内容的简写。

  await cookieStore.set({
    name: 'test',
    value: '1',
    expires: null,  // 不设置时间,默认为session cookie.

    // 默认为当前域名.
    domain: self.location.host,
    path: '/',

    // 默认情况下在安全来源上创建安全 cookie。 
    secure: self.location.protocol === 'https:',
    sameSite: 'lax',
});
复制代码

expires仅接受时间戳(自 UNIX 纪元以来的毫秒数)来回避日期解析问题.

await cookieStore.delete 删除cookie。返回值null

  try {
    await cookieStore.delete('test');
  } catch (e) {
    console.error(`删除cookie失败: ${e}`);
  }
复制代码

也可以通过直接将过期时间设置到其之前进行删除。

  try {
    await cookieStore.set({
      name: 'test', 
      value: 1, 
      expires: Date.now() - 2 *  24 * 60 * 60 * 1000
    })
  } catch (e) {
    console.error(`删除cookie失败: ${e}`);
  }
复制代码

change事件


cookieStore包括一个用于观察 cookie 更改的 API,旨在解决当前需要轮询 document.cookie 的所有用例。 该 API 具有以下步骤:

  1. 观察 cookie 的变化
  2. 处理 cookie 更改事件
  cookieStore.addEventListener('change', (event) => {
    console.log(`${event.changed.length} changed cookies`);
    for (const cookie in event.changed) {
      console.log(`Cookie ${cookie.name} changed to ${cookie.value}`);
    } 
    console.log(`${event.deleted.length} deleted cookies`);
    for (const cookie in event.deleted) {
      console.log(`Cookie ${cookie.name} deleted`);
    }
      
});
复制代码

兼容性

只是Cookie Store API兼容性还不太好,仅仅是是 Chrome 体系支持了 cookieStore。Chrome也在 Chrome87 版本后才加入。距离真正使用还得等待些时日。

cookieStore.png

总结

Cookie Store API比document.cookie写法简便了很多,也更容易理解。缺点还是很明显,如兼容性问题,只能在https环境使用。还是很期待能正式使用。

以上内容让我们简单了解了Cookie Store API的使用方法,如有表述不准确的地方,请大家指正。

参考

  1. cookie总结
  2. Cookie Store API
  3. Cookie Store API Explainer
文章分类
前端
文章标签