useStorage

LocalStorage または SessionStorage にアクセスおよび変更するためのリアクティブな ref を作成します。

デフォルトでは localStorage を使用しますが、他のストレージソースは第三引数で指定できます。

使用法

::: tip Nuxt 3 で使用する場合、この関数は Nitro の組み込みの useStorage() を優先するため、自動インポートされません。VueUse からこの関数を使用したい場合は、明示的にインポートしてください。 :::

import { useStorage } from '@vueuse/core'

// オブジェクトをバインド
const state = useStorage('my-store', { hello: 'hi', greeting: 'Hello' })

// ブール値をバインド
const flag = useStorage('my-flag', true) // Ref<boolean> を返します

// 数値をバインド
const count = useStorage('my-count', 0) // Ref<number> を返します

// SessionStorage で文字列をバインド
const id = useStorage('my-id', 'some-string-id', sessionStorage) // Ref<string> を返します

// ストレージからデータを削除
state.value = null

デフォルトのマージ

デフォルトでは、useStorage はストレージに値が存在する場合、その値を使用し、デフォルト値を無視します。デフォルト値にプロパティを追加する際、クライアントのストレージにそのキーがない場合、キーが undefined になる可能性があることに注意してください。

import { useStorage } from '@vueuse/core'
// ---cut---
localStorage.setItem('my-store', '{"hello": "hello"}')

const state = useStorage('my-store', { hello: 'hi', greeting: 'hello' }, localStorage)

console.log(state.value.greeting) // ストレージに値が存在しないため undefined

これを解決するには、mergeDefaults オプションを有効にすることができます。

import { useStorage } from '@vueuse/core'
// ---cut---
localStorage.setItem('my-store', '{"hello": "nihao"}')

const state = useStorage(
  'my-store',
  { hello: 'hi', greeting: 'hello' },
  localStorage,
  { mergeDefaults: true } // <--
)

console.log(state.value.hello) // ストレージから 'nihao'
console.log(state.value.greeting) // マージされたデフォルト値から 'hello'

これを true に設定すると、オブジェクトに対して浅いマージを行います。カスタムマージ（例：深いマージ）を行うための関数を渡すこともできます。例えば：

import { useStorage } from '@vueuse/core'
// ---cut---
const state = useStorage(
  'my-store',
  { hello: 'hi', greeting: 'hello' },
  localStorage,
  { mergeDefaults: (storageValue, defaults) => deepMerge(defaults, storageValue) } // <--
)

カスタムシリアライゼーション

デフォルトでは、useStorage は提供されたデフォルト値のデータ型に基づいて対応するシリアライザを賢く使用します。例えば、オブジェクトには JSON.stringify / JSON.parse、数値には Number.toString / parseFloat などが使用されます。

独自のシリアライゼーション関数を useStorage に提供することもできます：

import { useStorage } from '@vueuse/core'

useStorage(
  'key',
  {},
  undefined,
  {
    serializer: {
      read: (v: any) => v ? JSON.parse(v) : null,
      write: (v: any) => JSON.stringify(v),
    },
  },
)

デフォルト値として null を提供した場合、useStorage はそのデータ型を推測できません。この場合、カスタムシリアライザを提供するか、組み込みのものを明示的に再利用することができます。

import { StorageSerializers, useStorage } from '@vueuse/core'

const objectLike = useStorage('key', null, undefined, { serializer: StorageSerializers.object })
objectLike.value = { foo: 'bar' }