useStorage

Category

狀態

匯出大小

1.78 kB

Last Changed

5 days ago

Related

useColorModeuseDarkuseLocalStorageuseSessionStorageuseStorageAsync

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

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

Demo

source

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

Usage

TIP

When using with Nuxt 3, this function will NOT be auto imported in favor of Nitro's built-in useStorage(). Use explicit import if you want to use the function from 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

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

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

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

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.

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

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

Type Declarations

Show Type Declarations

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>

Source

原始碼 • 範例 • 文件

貢獻者

Anthony Fu

Fernando Fernández

Anthony Fu

IlyaL

sun0day

Jelf

Jeffrey Li

Robin

Yauheni Vasiukevich

OrbisK

Callum Macrae

Isaac Qadri

Matt Sanders

Doctorwu

Eduardo San Martin Morote

丶远方

Daniel Maixner

chenglu

David Ma

Daniel Mittereder

Clément Ollivier

James Garbutt

Yury Rudey

Puru Vijay

webfansplz

spking11

Maurici Abad Gutierrez

Guillaume Chau

Denis Blazhkun

Andreas Weber

Le Minh Tri

Jamie Warburton

Shinigami

Sasan Farrokh

Pig Fang

wheat

Alex Kozack

Nurettin Kaya

Pine

Antério Vieira

Ivan Demchuk

更新日誌

v12.8.0 於 2025/3/5

7432f - feat(types): 棄用 MaybeRef 和 MaybeRefOrGetter，改用 Vue 原生型別 (#4636)

v12.4.0 於 2025/1/10

eb679 - feat: 使 storage key 具有響應性 (#4464)

dd316 - feat: 在任何可能的地方使用被動事件處理器 (#4477)

v12.3.0 於 2025/1/2

59f75 - feat(toValue): 棄用 @vueuse/shared 中的 toValue，改用 Vue 原生型別

v12.0.0-beta.1 於 2024/11/21

0a9ed - feat!: 移除 Vue 2 支援，最佳化 bundles 並清理程式碼 (#4349)

v11.0.1 於 2024/8/19

a9b49 - fix: 在同一個文件內同步 (#4152)

v11.0.0-beta.2 於 2024/7/17

5a302 - feat: 根據使用的 storage 後端有條件地使用事件 (#3822)

v10.8.0 於 2024/2/20

f7ea1 - fix: 確保將值設定為 null 時同步到其他實例 (#3737)

a086e - fix: 更嚴格的型別

v10.7.0 於 2023/12/5

04220 - fix: 修復未定義的預設值 (#3597)

v10.6.0 於 2023/11/9

dc6f2 - feat: 為 SSR 新增 waitOnMounted 選項 (#3504)

b6d2b - fix: 修復預設值未解包的問題 (#3534)

v10.4.0 於 2023/8/25

6fabe - fix: 僅在物件序列化方式不同時讀取物件 (#2782) (#3091)

v10.0.0-beta.5 於 2023/4/13

cb644 - refactor!: 移除 isFunction 和 isString 工具函數

v10.0.0-beta.4 於 2023/4/13

4d757 - feat(types)!: 將 MaybeComputedRef 重新命名為 MaybeRefOrGetter

0a72b - feat(toValue): 將 resolveUnref 重新命名為 toValue

v9.13.0 於 2023/2/18

c6185 - fix: 發出自訂事件以支援自訂儲存區域 (#2630)