useStorage

类别

State

导出大小

1.95 kB

最近修改

2 days ago

相关

useColorModeuseDarkuseLocalStorageuseSessionStorageuseStorageAsync

创建一个响应式引用，可用于访问和修改 本地存储 或 会话存储。

🌐 Create a reactive ref that can be used to access & modify LocalStorage or SessionStorage.

默认使用 localStorage，其他存储源可以通过第三个参数指定。

🌐 Uses localStorage by default, other storage sources be specified via third argument.

示例

源代码在线运行

name: Banana
color: Yellow
size: Medium
count: 0

用法

🌐 Usage

TIP

在与 Nuxt 3 一起使用时，该函数不会被自动导入，以便使用 Nitro 内置的 useStorage()。如果你想使用 VueUse 的函数，请显式导入。

import { useStorage } from '@vueuse/core'

// bind object
const state = useStorage('my-store', { hello: 'hi', greeting: 'Hello' })

// bind boolean
const flag = useStorage('my-flag', true) // returns Ref<boolean>

// bind number
const count = useStorage('my-count', 0) // returns Ref<number>

// bind string with SessionStorage
const id = useStorage('my-id', 'some-string-id', sessionStorage) // returns Ref<string>

// delete data from storage
state.value = null

合并默认值

🌐 Merge Defaults

默认情况下，如果存在存储的值，useStorage 将使用该值并忽略默认值。请注意，当你向默认值添加更多属性时，如果客户端存储中没有该键，该键可能是 undefined。

🌐 By default, useStorage will use the value from storage if it is present and ignores the default value. Be aware that when you are adding more properties to the default value, the key might be undefined if client's storage does not have that key.

localStorage.setItem('my-store', '{"hello": "hello"}')

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

console.log(state.value.greeting) // undefined, since the value is not presented in storage

为了解决这个问题，你可以启用 mergeDefaults 选项。

🌐 To solve that, you can enable mergeDefaults option.

TypeScript

localStorage.setItem('my-store', '{"hello": "nihao"}')

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

console.log(state.value.hello) // 'nihao', from storage
console.log(state.value.greeting) // 'hello', from merged default value

localStorage.setItem('my-store', '{"hello": "nihao"}')
const state = useStorage(
  'my-store',
  { hello: 'hi', greeting: 'hello' },
  localStorage,
  { mergeDefaults: true },
)
console.log(state.value.hello) // 'nihao', from storage
console.log(state.value.greeting) // 'hello', from merged default value

将其设置为 true 时，它将对对象执行浅合并。你可以传入一个函数来执行自定义合并（例如深度合并），例如：

🌐 When setting it to true, it will perform a shallow merge for objects. You can pass a function to perform custom merge (e.g. deep merge), for example:

TypeScript

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

const state = useStorage(
  'my-store',
  { hello: 'hi', greeting: 'hello' },
  localStorage,
  {
    mergeDefaults: (storageValue, defaults) =>
      deepMerge(defaults, storageValue),
  },
)

自定义序列化

🌐 Custom Serialization

默认情况下，useStorage 会根据提供的默认值的数据类型智能地使用相应的序列化器。例如，JSON.stringify / JSON.parse 会用于对象，Number.toString / parseFloat 会用于数字，等等。

🌐 By default, useStorage will smartly use the corresponding serializer based on the data type of provided default value. For example, JSON.stringify / JSON.parse will be used for objects, Number.toString / parseFloat for numbers, etc.

你也可以为 useStorage 提供你自己的序列化函数：

🌐 You can also provide your own serialization function to useStorage:

TypeScript

import { useStorage } from '@vueuse/core'

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

import { useStorage } from '@vueuse/core'
useStorage('key', {}, undefined, {
  serializer: {
    read: (v) => (v ? JSON.parse(v) : null),
    write: (v) => JSON.stringify(v),
  },
})

请注意，当你将 null 作为默认值提供时，useStorage 无法从中推断数据类型。在这种情况下，你可以提供自定义序列化器，或显式地重用内置序列化器。

🌐 Please note when you provide null as the default value, useStorage can't assume the data type from it. In this case, you can provide a custom serializer or reuse the built-in ones explicitly.

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

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

内置序列化器

🌐 Built-in Serializers

以下序列化器可通过 StorageSerializers 使用：

🌐 The following serializers are available via StorageSerializers:

类型	描述
string	普通字符串
number	数字（通过 parseFloat）
boolean	布尔值
object	JSON 对象/数组
map	JavaScript Map
set	JavaScript Set
date	JavaScript Date（通过 toISOString）
any	原始字符串直通

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

const myMap = useStorage('my-map', new Map(), undefined, {
  serializer: StorageSerializers.map,
})

选项

🌐 Options

useStorage('key', defaults, storage, {
  // Watch for deep changes in objects/arrays (default: true)
  deep: true,
  // Sync across tabs via storage events (default: true)
  listenToStorageChanges: true,
  // Write default value to storage if not present (default: true)
  writeDefaults: true,
  // Use shallowRef instead of ref (default: false)
  shallow: false,
  // Initialize only after component is mounted (default: false)
  initOnMounted: false,
  // Custom error handler (default: console.error)
  onError: e => console.error(e),
  // Watch flush timing (default: 'pre')
  flush: 'pre',
})

反应键

🌐 Reactive Key

存储键可以是 ref 或 getter，当键发生变化时数据将会更新：

🌐 The storage key can be a ref or getter, and the data will be updated when the key changes:

import { useStorage } from '@vueuse/core'

const userId = ref('user-1')
const userData = useStorage(
  () => `user-data-${userId.value}`,
  { name: '' },
)

// Changing the key will read from the new storage location
userId.value = 'user-2'