这是对标准化 document.cookie 的封装器。

¥This is a wrapper over the standardized document.cookie.

// quasar.config file

return {
  framework: {
    plugins: [
      'Cookies'
    ]
  }
}

关于 SSR(Notes on SSR)

¥Notes on SSR

构建 SSR 应用时，请仅使用 $q.cookies 表单。或者，在服务器端时，这是另一个如何使用它的示例：

¥When building for SSR, use only the $q.cookies form. Alternatively, when on server-side, this is one more example of how you can use it:

import { Cookies } from 'quasar'

// you need access to `ssrContext`
function (ssrContext) {
  const cookies = process.env.SERVER
    ? Cookies.parseSSR(ssrContext)
    : Cookies // otherwise we're on client

  // "cookies" is equivalent to the global import as in non-SSR builds
}

ssrContext 可在 @quasar/app-vite Boot File 或 @quasar/app-webpack Boot File 中使用。在 @quasar/app-vite preFetch 或 @quasar/app-webpack preFetch 功能中，它作为参数提供。

¥The ssrContext is available in @quasar/app-vite Boot File or @quasar/app-webpack Boot File. And also in the @quasar/app-vite preFetch or @quasar/app-webpack preFetch feature, where it is supplied as a parameter.

这样做的原因是，在纯客户端应用中，每个用户都会在其浏览器中使用应用的新实例。对于服务器端渲染，我们想要的是相同的：每个请求都应该有一个全新的、独立的应用实例，这样就不会出现跨请求状态污染。因此 Cookies 需要单独绑定到每个请求。

¥The reason for this is that in a client-only app, every user will be using a fresh instance of the app in their browser. For server-side rendering we want the same: each request should have a fresh, isolated app instance so that there is no cross-request state pollution. So Cookies needs to be bound to each request separately.

读取一个 Cookie(Read a Cookie)

¥Read a Cookie

import { Cookies } from 'quasar'
const value = Cookies.get('cookie_name')

如果未设置 Cookie，则返回值为 null。

¥When cookie is not set, the return value is null.

import { useQuasar } from 'quasar'

setup () {
  const $q = useQuasar()
  const value = $q.cookies.get('cookie_name')
}

读取所有 Cookie(Read All Cookies)

¥Read All Cookies

import { Cookies } from 'quasar'
const cookies = Cookies.getAll()

cookies 变量将是一个包含键值对 (cookie_name : cookie_value) 的对象。

¥cookies variable will be an object with key-value pairs (cookie_name : cookie_value).

import { useQuasar } from 'quasar'

setup () {
  const $q = useQuasar()
  const allCookies = $q.cookies.getAll()
}

验证是否设置了 Cookie(Verify if Cookie is Set)

¥Verify if Cookie is Set

import { Cookies } from 'quasar'
Cookies.has('cookie_name') // Boolean

import { useQuasar } from 'quasar'

setup () {
  const $q = useQuasar()
  const hasIt = $q.cookies.has('cookie_name')
}

编写 Cookie(Write a Cookie)

¥Write a Cookie

import { Cookies } from 'quasar'

Cookies.set('cookie_name', cookie_value)

// or pass in options also:
Cookies.set('cookie_name', cookie_value, options)

import { Cookies } from 'quasar'

Cookies.set('quasar', 'framework', {
  secure: true
})

import { useQuasar } from 'quasar'

setup () {
  const $q = useQuasar()

  $q.cookies.set('cookie_name', cookie_value)
  // or pass in options also:
  $q.cookies.set('cookie_name', cookie_value, options)
}

（可选）options 参数是一个对象，我们将在下面逐个属性进行解释。

¥The (optional) options parameter is an Object which is explained below, property by property.

选项：expires(Option: expires)

¥Option: expires

expires: 10 // in 10 days
expires: -1 // yesterday
expires: 'Mon, 06 Jan 2020 12:52:55 GMT'
expires: new Date() // some JS Date Object
expires: '1d 3h 5m' // in 1 day, 3 hours, 5 minutes
expires: '2d' // in 2 days
expires: '15m 10s' // in 15 minutes, 10 seconds

定义 Cookie 的生命周期。值可以是数字（将被解释为自创建时间起的天数）、日期对象、原始字符串化日期 (“2020 年 1 月 6 日星期一 12:52:55 GMT”) 或特殊字符串格式（“1d”、“15m”、“13d”、“1d 15 分钟”、“1 天 3 小时 5 分 3 秒”）。如果省略，该 cookie 将成为会话 cookie。

¥Define lifetime of the cookie. Value can be a Number which will be interpreted as days from time of creation or a Date object or a raw stringified Date (“Mon, 06 Jan 2020 12:52:55 GMT”) or a special string format (“1d”, “15m”, “13d”, “1d 15m”, “1d 3h 5m 3s”). If omitted, the cookie becomes a session cookie.

选项：path(Option: path)

¥Option: path

path: '/'

定义 Cookie 有效的路径。默认情况下，Cookie 的路径是创建 Cookie 的页面的路径（标准浏览器行为）。例如，如果你想使其在整个域中可用，请使用路径：‘/’。默认值：创建 Cookie 的页面路径。

¥Define the path where the cookie is valid. By default the path of the cookie is the path of the page where the cookie was created (standard browser behavior). If you want to make it available for instance across the entire domain use path: ‘/’. Default: path of page where the cookie was created.

选项：domain(Option: domain)

¥Option: domain

domain: 'quasar.dev'

定义 Cookie 有效的域。默认值：创建 Cookie 的页面域名。

¥Define the domain where the cookie is valid. Default: domain of page where the cookie was created.

选项：sameSite(Option: sameSite)

¥Option: sameSite

sameSite: 'Strict'
// or
sameSite: 'Lax'

SameSite Cookie 允许服务器要求 Cookie 不应与跨站点（其中 Site 由可注册域名定义）请求一起发送，这在一定程度上可以防止跨站点请求伪造攻击 (CSRF)。

¥SameSite cookies let servers require that a cookie shouldn’t be sent with cross-site (where Site is defined by the registrable domain) requests, which provides some protection against cross-site request forgery attacks (CSRF).

严格 - 如果同站 Cookie 具有此属性，则浏览器仅会在请求源自设置 Cookie 的网站时发送 Cookie。如果请求来自与当前位置 URL 不同的 URL，则不会包含任何带有 Strict 属性标记的 cookie。

¥Strict - If a same-site cookie has this attribute, the browser will only send cookies if the request originated from the website that set the cookie. If the request originated from a different URL than the URL of the current location, none of the cookies tagged with the Strict attribute will be included.

Lax - 如果该属性设置为 Lax，则跨站子请求（例如加载图片或框架的调用）会保留同站 Cookie，但当用户从外部站点导航到 URL（例如通过点击链接）时，会发送同站 Cookie。

¥Lax - If the attribute is set to Lax, same-site cookies are withheld on cross-site subrequests, such as calls to load images or frames, but will be sent when a user navigates to the URL from an external site, for example, by following a link.

有关 same-site 设置的更多信息，请转到 此处。

¥For more information on the same-site setting, go here.

选项：httpOnly(Option: httpOnly)

¥Option: httpOnly

httpOnly: true

为了帮助缓解跨站点脚本 (XSS) 攻击，JavaScript 的 Document.cookie API 无法访问 HttpOnly Cookie；它们仅发送到服务器。例如，持久化服务器端会话的 Cookie 不需要对 JavaScript 可用，并且应该设置 HttpOnly 标志。

¥To help mitigate cross-site scripting (XSS) attacks, HttpOnly cookies are inaccessible to JavaScript’s Document.cookie API; they are only sent to the server. For example, cookies that persist server-side sessions don’t need to be available to JavaScript, and the HttpOnly flag should be set.

选项：secure(Option: secure)

¥Option: secure

secure: true

如果为 true，则 Cookie 传输需要安全协议 (HTTPS)，并且不会通过 HTTP 发送。默认值为 false。

¥If true, the cookie transmission requires a secure protocol (HTTPS) and will NOT be sent over HTTP. Default value is false.

选项：other(Option: other)

¥Option: other

other: 'SomeNewProp'

其他 Cookie 选项的原始字符串。作为 Quasar 中目前尚未实现的可能较新的 props 的最后手段。

¥Raw string for other cookie options. To be used as a last resort for possible newer props that are currently not yet implemented in Quasar.

移除 Cookie(Remove a Cookie)

¥Remove a Cookie

import { Cookies } from 'quasar'

Cookies.remove('cookie_name')

// if cookie was set with specific options like path and/or domain
// then you need to also supply them when removing:
Cookies.remove('cookie_name', options)

import { useQuasar } from 'quasar'

setup () {
  const $q = useQuasar()

  $q.cookies.remove('cookie_name')

  // if cookie was set with specific options like path and/or domain
  // then you need to also supply them when removing:
  $q.cookies.remove('cookie_name', options)
}