useCookie

ページ、コンポーネント、プラグイン内で、クッキーの読み書きを行う SSR フレンドリーなコンポーザブル useCookie を使用できます。

const cookie = useCookie(name, options)

useCookie は、Nuxt コンテキストでのみ機能します。

useCookie ref は、クッキーの値を JSON に自動的にシリアル化およびデシリアル化します。

例

以下の例では、counter というクッキーを作成します。クッキーが存在しない場合、最初はランダムな値に設定されます。counter 変数を更新するたびに、クッキーもそれに応じて更新されます。

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>

ドキュメント > 例 > 高度な設定 > useCookieで、ライブ例を参照・編集できます。

refreshCookie を使用して、クッキーが変更されたときに useCookie の値を手動で更新します。

オプション

Cookie コンポーザブルは、クッキーの動作を変更できるいくつかのオプションを受け入れます。

ほとんどのオプションは、cookie パッケージに直接渡されます。

`maxAge` / `expires`

これらのオプションを使用して、クッキーの有効期限を設定します。

maxAge: Max-Age Set-Cookie 属性の値として、number（秒単位）を指定します。指定された数値は、切り捨てによって整数に変換されます。デフォルトでは、最大有効期限は設定されません。

expires: Expires Set-Cookie 属性の値として、Date オブジェクトを指定します。デフォルトでは、有効期限は設定されません。ほとんどのクライアントはこれを「非永続的なクッキー」と見なし、Webブラウザアプリケーションを終了するなどの条件で削除します。

クッキーストレージモデル仕様では、expires と maxAge の両方が設定されている場合、maxAge が優先されるとされていますが、すべてのクライアントがこれを遵守するとは限りません。そのため、両方が設定されている場合は、同じ日時を指す必要があります！

expires と maxAge のどちらも設定されていない場合、クッキーはセッション専用となり、ユーザーがブラウザを閉じると削除されます。

`httpOnly`

HttpOnly Set-Cookie 属性のboolean値を指定します。真の場合、HttpOnly 属性が設定されます。それ以外の場合は設定されません。デフォルトでは、HttpOnly 属性は設定されません。

これを true に設定する際は注意してください。準拠しているクライアントでは、クライアント側の JavaScript が document.cookie でクッキーを参照できなくなります。

`secure`

Secure Set-Cookie 属性のboolean値を指定します。真の場合、Secure 属性が設定されます。それ以外の場合は設定されません。デフォルトでは、Secure 属性は設定されません。

これを true に設定する際は注意してください。準拠しているクライアントでは、ブラウザが HTTPS 接続を持っていない場合、将来サーバーにクッキーが送り返されなくなります。これにより、ハイドレーションエラーが発生する可能性があります。

`partitioned`

Partitioned Set-Cookie 属性の boolean 値を指定します。真の場合、Partitioned 属性が設定されます。それ以外の場合は設定されません。デフォルトでは、Partitioned 属性は設定されません。

これはまだ完全に標準化されていない属性であり、将来変更される可能性があります。つまり、多くのクライアントはこれを理解するまで、この属性を無視する可能性があります。提案で詳細情報を確認できます。

`domain`

Domain Set-Cookie 属性の値を指定します。デフォルトでは、ドメインは設定されず、ほとんどのクライアントは現在のドメインのみにクッキーを適用すると見なします。

`path`

Path Set-Cookie 属性の値を指定します。デフォルトでは、パスは"デフォルトパス"と見なされます。

`sameSite`

SameSite Set-Cookie 属性のbooleanまたはstring値を指定します。

true は、厳格な同一サイト強制のために SameSite 属性を Strict に設定します。
false は、SameSite 属性を設定しません。
'lax' は、緩やかな同一サイト強制のために SameSite 属性を Lax に設定します。
'none' は、明示的なクロスサイトクッキーのために SameSite 属性を None に設定します。
'strict' は、厳格な同一サイト強制のために SameSite 属性を Strict に設定します。

異なる強制レベルの詳細については、仕様書を参照してください。

`encode`

クッキーの値のエンコードに使用される関数を指定します。クッキーの値には文字セットが制限されているため（単純な文字列でなければならない）、この関数を使用して値をクッキーの値に適した文字列にエンコードできます。

デフォルトのエンコーダーは JSON.stringify + encodeURIComponent です。

`decode`

クッキーの値のデコードに使用される関数を指定します。クッキーの値には文字セットが制限されているため（単純な文字列でなければならない）、この関数を使用して、以前にエンコードされたクッキーの値を JavaScript の文字列またはその他のオブジェクトにデコードできます。

デフォルトのデコーダーは decodeURIComponent + destr です。

この関数からエラーがスローされた場合、元のデコードされていないクッキーの値がクッキーの値として返されます。

true - クッキー ref データの変更とそのネストされたプロパティを監視します（デフォルト）。
shallow - 最上位のプロパティのみのクッキー ref データの変更を監視します。
false - クッキー ref データの変更を監視しません。

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 ルートでのクッキー

h3 パッケージの getCookie と setCookie を使用して、サーバー側の API ルートでクッキーを設定できます。

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 }
})

ドキュメント > 例 > 高度な設定 > useCookieで、ライブ例を参照・編集できます。

useAsyncData

useAsyncDataは、SSRフレンドリーなコンポーザブルで非同期に解決されるデータへのアクセスを提供します。

useError

useErrorコンポーザブルは、処理されているグローバルなNuxtエラーを返します。

例