useCookie · Nuxt Composables v4

使用

在你的頁面、元件和外掛中，你可以使用 useCookie 以 SSR 友好的方式讀取和寫入 cookie。

const cookie = useCookie(name, options)

useCookie 僅在 Nuxt 上下文中有效。

返回的 ref 會自動將 cookie 值序列化和反序列化為 JSON。

型別

簽名

import type { Ref } from 'vue'
import type { CookieParseOptions, CookieSerializeOptions } from 'cookie-es'

export interface CookieOptions<T = any> extends Omit<CookieSerializeOptions & CookieParseOptions, 'decode' | 'encode'> {
  decode?(value: string): T
  encode?(value: T): string
  default?: () => T | Ref<T>
  watch?: boolean | 'shallow'
  readonly?: boolean
}

export interface CookieRef<T> extends Ref<T> {}

export function useCookie<T = string | null | undefined> (
  name: string,
  options?: CookieOptions<T>
): CookieRef<T>

引數

name：cookie 的名稱。

options：控制 cookie 行為的選項。該物件可以具有以下屬性：

大多數選項將直接傳遞給cookie包。

屬性	型別	預設	描述
`decode`	`(value: string) => T`	`decodeURIComponent` + destr.	用於解碼 cookie 值的自定義函式。由於 cookie 的值具有有限的字元集（並且必須是簡單的字串），此函式可用於將先前編碼的 cookie 值解碼為 JavaScript 字串或其他物件。注意：如果此函式丟擲錯誤，則將返回原始的、未解碼的 cookie 值作為 cookie 的值。
`encode`	`(value: T) => string`	`JSON.stringify` + `encodeURIComponent`	用於編碼 cookie 值的自定義函式。由於 cookie 的值具有有限的字元集（並且必須是簡單的字串），此函式可用於將值編碼為適合 cookie 值使用的字串。
`預設`	`() => T \| Ref<T>`	`未定義`	如果 cookie 不存在，則返回預設值的函式。該函式還可以返回一個 `Ref`。
`watch`	`boolean \| 'shallow'`	`true`	是否監聽更改並更新 cookie。`true` 表示深度監聽，`'shallow'` 表示淺層監聽，即只監聽頂層屬性的資料更改，`false` 表示停用。注意：當 cookie 發生更改時，使用 `refreshCookie` 手動重新整理 `useCookie` 值。
`readonly`	`boolean`	`false`	如果為 `true`，則停用寫入 cookie。
`maxAge`	`number`	`未定義`	cookie 的最大年齡（秒），即 `Set-Cookie` 屬性中的 `Max-Age` 值。給定數字將透過四捨五入轉換為整數。預設情況下，不設定最大年齡。。給定數字將透過向下取整轉換為整數。預設情況下，不設定最大年齡。
`expires`	`Date`	`未定義`	cookie 的過期日期。預設情況下，不設定過期日期。大多數客戶端會將其視為“非永續性 cookie”，並在退出 Web 瀏覽器應用程式等條件下刪除它。注意：cookie 儲存模型規範規定，如果同時設定了 `expires` 和 `maxAge`，則 `maxAge` 優先，但並非所有客戶端都可能遵守此規定，因此如果兩者都設定，它們應該指向相同的日期和時間！如果 `expires` 和 `maxAge` 都未設定，則 cookie 將僅限於會話，並在使用者關閉瀏覽器時刪除。
`httpOnly`	`boolean`	`false`	設定 HttpOnly 屬性。注意：將其設定為 `true` 時請小心，因為遵循規範的客戶端將不允許客戶端 JavaScript 在 `document.cookie` 中看到 cookie。
`secure`	`boolean`	`false`	設定`Secure` `Set-Cookie` 屬性. 注意：將其設定為 `true` 時請小心，因為遵循規範的客戶端如果瀏覽器沒有 HTTPS 連線，將來將不會把 cookie 傳送回伺服器。這可能導致水合錯誤。
`partitioned`	`boolean`	`false`	設定`Partitioned` `Set-Cookie` 屬性. 注意：這是一個尚未完全標準化的屬性，將來可能會發生變化。這也意味著許多客戶端可能會忽略此屬性，直到他們理解它。更多資訊可以在提案.
`domain`	`string`	`未定義`	設定`Domain` `Set-Cookie` 屬性中找到。預設情況下，不設定域，大多數客戶端會認為 cookie 只適用於當前域。
`path`	`string`	`'/'`	設定`Path` `Set-Cookie` 屬性。預設情況下，路徑被認為是“預設路徑”.
`sameSite`	`boolean \| string`	`未定義`	設定`SameSite` `Set-Cookie` 屬性. - `true` 將 `SameSite` 屬性設定為 `Strict` 以強制執行嚴格的同站策略。 - `false` 將不設定 `SameSite` 屬性。 - `'lax'` 將 `SameSite` 屬性設定為 `Lax` 以強制執行寬鬆的同站策略。 - `'none'` 將 `SameSite` 屬性設定為 `None` 用於明確的跨站 cookie。 - `'strict'` 將 `SameSite` 屬性設定為 `Strict` 以強制執行嚴格的同站策略。

返回值

返回一個表示 cookie 值的 Vue Ref<T>。更新 ref 將更新 cookie（除非設定了 readonly）。該 ref 對 SSR 友好，可在客戶端和伺服器上工作。

示例

基本用法

以下示例建立了一個名為 counter 的 cookie。如果 cookie 不存在，它最初被設定為一個隨機值。每當我們更新 counter 變數時，cookie 也會相應更新。

app/app.vue

<script setup lang="ts">
const counter = useCookie('counter')

counter.value ||= Math.round(Math.random() * 1000)
</script>

<template>
  <div>
    <h1>Counter: {{ counter || '-' }}</h1>
    <button @click="counter = null">
      reset
    </button>
    <button @click="counter--">
      -
    </button>
    <button @click="counter++">
      +
    </button>
  </div>
</template>

只讀 Cookies

<script setup lang="ts">
const user = useCookie(
  'userInfo',
  {
    default: () => ({ score: -1 }),
    watch: false,
  },
)

if (user.value) {
  // the actual `userInfo` cookie will not be updated
  user.value.score++
}
</script>

<template>
  <div>User score: {{ user?.score }}</div>
</template>

可寫 Cookies

<script setup lang="ts">
const list = useCookie(
  'list',
  {
    default: () => [],
    watch: 'shallow',
  },
)

function add () {
  list.value?.push(Math.round(Math.random() * 1000))
  // list cookie won't be updated with this change
}

function save () {
  // the actual `list` cookie will be updated
  list.value &&= [...list.value]
}
</script>

<template>
  <div>
    <h1>List</h1>
    <pre>{{ list }}</pre>
    <button @click="add">
      Add
    </button>
    <button @click="save">
      Save
    </button>
  </div>
</template>

API 路由中的 Cookies

你可以使用來自h3包的 getCookie 和 setCookie 在伺服器 API 路由中設定 cookie。

server/api/counter.ts

export default defineEventHandler((event) => {
  // Read counter cookie
  let counter = getCookie(event, 'counter') || 0

  // Increase counter cookie by 1
  setCookie(event, 'counter', ++counter)

  // Send JSON response
  return { counter }
})

在 Docs > 4 X > Examples > Advanced > Use Cookie 中閱讀和編輯即時示例。

這有幫助嗎？

報告問題或在 GitHub 上編輯此頁面

useAsyncData

useAsyncData 提供對非同步解析資料的訪問，這是一個 SSR 友好的組合式函式。

useError

useError 組合式函式返回正在處理的全域性 Nuxt 錯誤。