useStorage

分类

导出大小

2 kB

上次更改

2 个月前

演示

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

用法

提示

在 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

合并默认值

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

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 选项。

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 时，它将对对象执行浅合并。您可以传入一个函数来执行自定义合并（例如深合并），例如：

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

自定义序列化

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

您还可以为 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 无法从中推断数据类型。在这种情况下，您可以提供自定义序列化器或显式重用内置序列化器。

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

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

类型声明

显示类型声明

export interface Serializer
<T
> {
  read
: (raw
: string) => T

  write
: (value
: T
) => string
}
export interface SerializerAsync
<T
> {
  read
: (raw
: string) => Awaitable
<T
>
  write
: (value
: T
) => Awaitable
<string>
}
export declare const StorageSerializers
: Record
<
  "boolean" | "object" | "number" | "any" | "string" | "map" | "set" | "date",
  Serializer
<any>
>
export declare const customStorageEventName
 = "vueuse-storage"
export interface StorageEventLike {
  storageArea
: StorageLike
 | null
  key
: StorageEvent["key"]
  oldValue
: StorageEvent["oldValue"]
  newValue
: StorageEvent["newValue"]
}
export interface UseStorageOptions
<T
>
  extends ConfigurableEventFilter,
    ConfigurableWindow,
    ConfigurableFlush {
  /**
   * Watch for deep changes
   *
   * @default true
   */
  deep
?: boolean
  /**
   * Listen to storage changes, useful for multiple tabs application
   *
   * @default true
   */
  listenToStorageChanges
?: boolean
  /**
   * Write the default value to the storage when it does not exist
   *
   * @default true
   */
  writeDefaults
?: boolean
  /**
   * Merge the default value with the value read from the storage.
   *
   * 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:
   *
   * @default false
   */
  mergeDefaults
?: boolean | ((storageValue
: T
, defaults
: T
) => T
)
  /**
   * Custom data serialization
   */
  serializer
?: Serializer
<T
>
  /**
   * On error callback
   *
   * Default log error to `console.error`
   */
  onError
?: (error
: unknown) => void
  /**
   * Use shallow ref as reference
   *
   * @default false
   */
  shallow
?: boolean
  /**
   * Wait for the component to be mounted before reading the storage.
   *
   * @default false
   */
  initOnMounted
?: boolean
}
export declare function useStorage
(
  key
: MaybeRefOrGetter
<string>,
  defaults
: MaybeRefOrGetter
<string>,
  storage
?: StorageLike
,
  options
?: UseStorageOptions
<string>,
): RemovableRef
<string>
export declare function useStorage
(
  key
: MaybeRefOrGetter
<string>,
  defaults
: MaybeRefOrGetter
<boolean>,
  storage
?: StorageLike
,
  options
?: UseStorageOptions
<boolean>,
): RemovableRef
<boolean>
export declare function useStorage
(
  key
: MaybeRefOrGetter
<string>,
  defaults
: MaybeRefOrGetter
<number>,
  storage
?: StorageLike
,
  options
?: UseStorageOptions
<number>,
): RemovableRef
<number>
export declare function useStorage
<T
>(
  key
: MaybeRefOrGetter
<string>,
  defaults
: MaybeRefOrGetter
<T
>,
  storage
?: StorageLike
,
  options
?: UseStorageOptions
<T
>,
): RemovableRef
<T
>
export declare function useStorage
<T
 = unknown>(
  key
: MaybeRefOrGetter
<string>,
  defaults
: MaybeRefOrGetter
<null>,
  storage
?: StorageLike
,
  options
?: UseStorageOptions
<T
>,
): RemovableRef
<T
>