Cookie Store API 提供了异步地管理 Cookie 的方式,同时允许在 ServiceWorker 中使用
在该 API 之前,使用 cookie 的方式是通过读写 document.cookie 属性,但其是单线程同步的,可能会阻碍事件循环;并且其无法在 ServiceWorker 中使用
Cookie 的读写 Window 环境中通过 Window 接口的 cookieStore 属性使用
Window 环境中通过 ServiceWorkerGlobalScope 接口的 cookieStore 属性使用
1 2 window .cookieStore self.cookieStore
读取单条 Cookie CookieStore 接口的 get() 方法用于获取单条 Cookie
方法接收一个字符串,代表 Cookie 的名称;或接收一个对象,其 name 参数与 url 参数均需指定
方法返回一个 Promise 的 CookieListItem 结构,代表匹配到的 Cookie 信息;反之返回 undefined
1 2 3 4 5 const cookie = await window .cookieStore .get ('cookie' )const cookie = await window .cookieStore .get ({ name : 'cookie' , url : 'https://www.example.com' , })
读取多条 Cookie CookieStore 接口的 getAll() 方法用于获取单条 Cookie
方法接收一个字符串,代表 Cookie 的名称;或接收一个对象,其 name 参数与 url 参数均需指定
方法返回一个 Promise 的 CookieList 结构,代表匹配到的所有 Cookie
1 2 3 4 5 const cookies = await window .cookieStore .getAll ('key' )const cookies = await window .cookieStore .getAll ({ name : 'key' , url : 'https://www.example.com' , })
设置 Cookie CookieStore 接口的 set() 方法用于设置 Cookie
方法可以接收两个字符串,分别代表 Cookie 的名称与值;亦可以接收一个配置项,各项如下所示:
name 属性必需
value 属性必需
expires 属性可选,默认 null
domain 属性可选,默认 null
path 属性可选,默认 "/"
sameSite 属性可选,默认 "strict"
partitioned 属性可选,默认 false
方法返回一个 Promise
1 2 3 4 5 6 7 8 9 10 await window .cookieStore .set ('key' , 'value' )await window .cookieStore .set ({ name : 'key' , value : 'value' , expires : null , domain : null , path : '/' , sameSite : 'strict' , partitioned : false , })
移除 Cookie CookieStore 接口的 delete() 方法用于移除 Cookie
方法接收一个字符串,代表 Cookie 的名称;或接收一个对象,其 name 参数必需指定;path 参数 domain 参数 partitioned 参数可选
方法返回一个 Promise
1 2 3 4 5 6 7 await window .cookieStore .delete ('key' )await window .cookieStore .delete ({ name : 'key' , path : '/' , domain : null , partitioned : false , })
Cookie 详细信息 CookieList 结构相当于 CookieListItem 结构的数组
CookieListItem 结构反映了 Cookie 的详细信息
CookieListItem 结构的 name 属性返回一个字符串,代表 Cookie 的名称
CookieListItem 结构的 value 属性返回一个字符串,代表 Cookie 的值
CookieListItem 结构的 domain 属性返回一个字符串,代表 Cookie 的域,该属性可能返回 null
CookieListItem 结构的 path 属性返回一个字符串,代表 Cookie 的路径
CookieListItem 结构的 expires 属性返回一个数字,代表 Cookie 的过期时间,该属性可能返回 null
CookieListItem 结构的 secure 属性返回一个布尔值,代表 Cookie 的严格上下文策略
CookieListItem 结构的 sameSite 属性返回一个字符串,代表 Cookie 的同域策略,为 "strict" "lax" "none" 之一
CookieListItem 结构的 partitioned 属性返回一个布尔值,代表 Cookie 的分区策略
监听 Cookie 变化 CookieStore 接口的 change 事件在任一 Cookie 变化时触发,返回一个 CookieChangeEvent 事件
CookieChangeEvent 接口的 changed 属性返回一个 CookieListItem 结构只读数组,表示被修改的 Cookie
CookieChangeEvent 接口的 deleted 属性返回一个 CookieListItem 结构只读数组,表示被移除的 Cookie
1 2 3 4 window .cookieStore .addEventListener ('change' , (e ) => { e.changed e.deleted })
但该事件仅在 Window 环境中可用
订阅 Cookie 变化 ServiceWorker 中允许通过 CookieStoreManager 接口的方法动态控制 Cookie 变化的订阅
可通过 ServiceWorkerRegistration 接口的 cookies 属性获取到 CookieStoreManager 实例
1 self.registration .cookies
获取订阅 CookieStoreManager 接口的 getSubscriptions() 方法用于获取当前所有的订阅
方法返回一个对象数组,数组各项包含 name 参数和 url 参数
1 const subscriptions = await self.registration .cookies .getSubscriptions ()
添加订阅 CookieStoreManager 接口的 subscribe() 方法用于添加订阅
方法传入一个对象数组参数,各项的 name 参数与 url 参数均需指定
方法返回一个 Promise
1 2 3 4 5 6 self.registration .cookies .subscribe ([ { name : 'key' , url : '/' , }, ])
移除订阅 CookieStoreManager 接口的 unsubscribe() 方法用于移除订阅
方法传入一个对象数组参数,各项的 name 参数与 url 参数均需指定
方法返回一个 Promise
1 2 3 4 5 6 self.registration .cookies .unsubscribe ([ { name : 'key' , url : '/' , }, ])
监听 Cookie 变化 ServiceWorkerGlobalScope 接口的 cookiechange 事件在订阅的 Cookie 发生变化时触发,返回一个 ExtendableCookieChangeEvent 事件
ExtendableCookieChangeEvent 接口的 changed 属性返回一个 CookieListItem 结构只读数组,表示被修改的 Cookie
ExtendableCookieChangeEvent 接口的 deleted 属性返回一个 CookieListItem 结构只读数组,表示被移除的 Cookie
1 2 3 4 self.addEventListener ('cookiechange' , (e ) => { e.changed e.deleted })
示例
Name
Value
Domain
Path
Expires
Secure
SameSite
Partition Key
Operation
类型 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 interface CookieStore extends EventTarget { get (name : string ): Promise <CookieListItem | undefined > get (options?: CookieStoreGetOptions ): Promise <CookieListItem | undefined > getAll (name : string ): Promise <CookieList > getAll (options?: CookieStoreGetOptions ): Promise <CookieList > set (name : string , value : string ): Promise <undefined > set (options : CookieInit ): Promise <undefined > delete (name : string ): Promise <undefined > delete (options : CookieStoreDeleteOptions ): Promise <undefined > onchange : ((this : CookieStore, ev: CookieChangeEvent ) => any ) | null } interface CookieStoreGetOptions { name : string url : string } enum CookieSameSite { "strict" , "lax" , "none" } interface CookieInit { name : string value : string expires?: DOMHighResTimeStamp | null domain?: string | null path?: string sameSite?: CookieSameSite partitioned?: boolean } interface CookieStoreDeleteOptions { name : string domain?: string | null path?: string partitione?: boolean } interface CookieListItem { name : string value : string domain?: string path : string expires?: DOMHighResTimeStamp secure : boolean sameSite : CookieSameSite partitioned : boolean } type CookieList = Array <CookieListItem >interface CookieStoreManager { subscribe (subscriptions : Array <CookieStoreGetOptions >): Promise <undefined > getSubscriptions (): Promise <Array <CookieStoreGetOptions >> unsubscribe (subscriptions : Array <CookieStoreGetOptions >): Promise <undefined > } interface ServiceWorkerRegistration { readonly cookies : CookieStoreManager } interface CookieChangeEvent extends Event { constructor (type : string , eventInitDict?: CookieChangeEventInit ) readonly changed : ReadonlyArray <CookieListItem > readonly deleted : ReadonlyArray <CookieListItem > } interface CookieChangeEventInit extends EventInit { changed : CookieList deleted : CookieList } interface ExtendableCookieChangeEvent extends ExtendableEvent { constructor (type : string , eventInitDict?: ExtendableCookieChangeEventInit ) readonly changed : ReadonlyArray <CookieListItem > readonly deleted : ReadonlyArray <CookieListItem > } interface ExtendableCookieChangeEventInit extends ExtendableEventInit { changed : CookieList deleted : CookieList } interface Window { readonly cookieStore : CookieStore } interface ServiceWorkerGlobalScope { readonly cookieStore : CookieStore oncookiechange : ((this : ServiceWorkerGlobalScope, ev: ExtendableCookieChangeEvent ) => any ) | null }
链接