useCookie

在您的頁面、元件和外掛中，您可以使用 useCookie，這是一個 SSR 友好的可組合函式，用於讀取和寫入 cookies。

const cookie = useCookie(name, options)

useCookie 僅在 Nuxt 情境中運作。

useCookie ref 會自動將 cookie 值序列化和反序列化為 JSON。

範例

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

app.vue

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

counter.value = 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>

在文件 > 範例 > 進階 > 使用 Cookie 中讀取和編輯實際範例。

當 cookie 發生變更時，請使用 refreshCookie 手動重新整理 useCookie 的值。

選項

Cookie 可組合函式接受多個選項，可讓您修改 cookie 的行為。

大多數選項將直接傳遞到 cookie 套件。

`maxAge` / `expires`

使用這些選項設定 cookie 的到期時間。

maxAge：指定 Max-Age Set-Cookie 屬性的值，以秒為單位。給定的數字會被向下捨入為整數。預設情況下，不會設定最大期限。

expires：指定 Expires Set-Cookie 屬性的值，以 Date 物件表示。預設情況下，不會設定到期時間。大多數客戶端會將其視為「非持續性 cookie」，並會在退出網路瀏覽器應用程式等情況下刪除它。

cookie 儲存模型規格指出，如果同時設定了 expires 和 maxAge，則 maxAge 優先，但並非所有客戶端都可能遵守此規定，因此如果兩者都設定，它們應指向相同的日期和時間！

如果未設定 expires 和 maxAge，則 cookie 將僅限於會話，並在使用者關閉瀏覽器時移除。

`httpOnly`

指定 HttpOnly Set-Cookie 屬性的 boolean 值。當為 true 時，會設定 HttpOnly 屬性；否則不會設定。預設情況下，不會設定 HttpOnly 屬性。

當將此設定為 true 時要小心，因為符合規範的客戶端將不允許用戶端 JavaScript 在 document.cookie 中看到 cookie。

`secure`

指定 Secure Set-Cookie 屬性的 boolean 值。當為 true 時，會設定 Secure 屬性；否則不會設定。預設情況下，不會設定 Secure 屬性。

當將此設定為 true 時要小心，因為如果瀏覽器沒有 HTTPS 連線，符合規範的客戶端將來不會將 cookie 送回伺服器。這可能會導致水合錯誤。

`partitioned`

指定 Partitioned Set-Cookie 屬性的 boolean 值。當為 true 時，會設定 Partitioned 屬性，否則不會設定。預設情況下，不會設定 Partitioned 屬性。

這是一個尚未完全標準化的屬性，將來可能會變更。這也表示許多客戶端可能會忽略此屬性，直到他們了解它為止。更多資訊請參閱提案。

`domain`

指定 Domain Set-Cookie 屬性的值。預設情況下，不會設定網域，而且大多數客戶端會認為 cookie 僅適用於目前的網域。

`path`

指定 Path Set-Cookie 屬性的值。預設情況下，路徑被視為「預設路徑」。

`sameSite`

指定 SameSite Set-Cookie 屬性的 boolean 或 string 值。

true 將 SameSite 屬性設定為 Strict，以進行嚴格的同網站強制執行。
false 將不會設定 SameSite 屬性。
'lax' 將 SameSite 屬性設定為 Lax，以進行寬鬆的同網站強制執行。
'none' 將 SameSite 屬性設定為 None，以進行明確的跨網站 Cookie。
'strict' 將 SameSite 屬性設定為 Strict，以進行嚴格的同網站強制執行。

有關不同強制執行等級的更多資訊，請參閱規範。

`encode`

指定一個用於編碼 Cookie 值的函數。由於 Cookie 的值具有有限的字元集（且必須是簡單的字串），因此可以使用此函數將值編碼為適合 Cookie 值的字串。

預設編碼器為 JSON.stringify + encodeURIComponent。

`decode`

指定一個用於解碼 Cookie 值的函數。由於 Cookie 的值具有有限的字元集（且必須是簡單的字串），因此可以使用此函數將先前編碼的 Cookie 值解碼為 JavaScript 字串或其他物件。

預設解碼器為 decodeURIComponent + destr。

如果此函數拋出錯誤，則會將原始的、未解碼的 Cookie 值作為 Cookie 的值返回。

true - 將監看 Cookie ref 資料的變更及其巢狀屬性（預設）。
shallow - 將僅監看最上層屬性的 Cookie ref 資料變更。
false - 將不監看 Cookie ref 資料的變更。

當 cookie 發生變更時，請使用 refreshCookie 手動重新整理 useCookie 的值。

範例 1

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

if (user.value && user.value !== null) {
  user.value.score++; // userInfo cookie not update with this change
}
</script>

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

範例 2

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

function add() {
  list.value?.push(Math.round(Math.random() * 1000))
  // list cookie not update with this change
}

function save() {
  if (list.value && list.value !== null) {
    list.value = [...list.value]
    // list cookie update with this change
  }
}
</script>

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

API 路由中的 Cookie

您可以使用 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 }
})

在文件 > 範例 > 進階 > 使用 Cookie 中讀取和編輯實際範例。

useAsyncData

useAsyncData 提供對在 SSR 友善的可組合元件中非同步解析的資料的存取權。

useError

useError 可組合元件會傳回正在處理的全域 Nuxt 錯誤。

範例

選項