Skip to content

index.md

Latest commit

 

History

History
108 lines (87 loc) · 4.87 KB

index.md

File metadata and controls

108 lines (87 loc) · 4.87 KB
title storage.onChanged
slug Mozilla/Add-ons/WebExtensions/API/storage/onChanged
page-type webextension-api-event
browser-compat webextensions.api.storage.onChanged
sidebar addonsidebar

Fires when one or more items in any of the {{WebExtAPIRef('storage.StorageArea', 'storage areas'}} changes. If you only need to listen for changes in one storage area, use {{WebExtAPIRef('storage.StorageArea.onChanged')}} instead.

Fired when {{WebExtAPIRef('storage.StorageArea.set','storageArea.set')}}, {{WebExtAPIRef('storage.StorageArea.remove','storageArea.remove')}}, or {{WebExtAPIRef('storage.StorageArea.clear','storageArea.clear')}} executes against any of the {{WebExtAPIRef('storage.StorageArea', 'storage areas'}}.

Note

In Firefox, the listener receives all the keys from a storage area where {{WebExtAPIRef('storage.StorageArea.set','storageArea.set')}} executes. The listener may be invoked when there is no change to the data. To find details of the changed items, examine each key's {{WebExtAPIRef('storage.StorageChange')}} object. See Firefox bug 1833153.

Note

Firefox does not fire this event for changes to storage.managed because managed storage is only read on browser startup (from the JSON manifest (native manifest) file or 3rdparty enterprise policy).

Syntax

browser.storage.onChanged.addListener(listener)
browser.storage.onChanged.removeListener(listener)
browser.storage.onChanged.hasListener(listener)

Events have three functions:

  • addListener(listener)
    • : Adds a listener to this event.
  • removeListener(listener)
    • : Stop listening to this event. The listener argument is the listener to remove.
  • hasListener(listener)
    • : Check whether listener is registered for this event. Returns true if it is listening, false otherwise.

addListener syntax

Parameters

  • listener
    • : The function called when this event occurs. The function is passed these arguments:
      • changes
        • : object. Object describing the change. The name of each property is the name of each key. The value of each key is a {{WebExtAPIRef('storage.StorageChange')}} object describing the change to that item.
      • areaName
        • : string. The name of the storage area ("local", "managed", "session", or "sync") to which the changes were made.

Examples

/*
Log the storage area that changed,
then for each item changed,
log its old value and its new value.
*/
function logStorageChange(changes, area) {
  console.log(`Change in storage area: ${area}`);

  const changedItems = Object.keys(changes);

  for (const item of changedItems) {
    console.log(`${item} has changed:`);
    console.log("Old value: ", changes[item].oldValue);
    console.log("New value: ", changes[item].newValue);
  }
}

browser.storage.onChanged.addListener(logStorageChange);

{{WebExtExamples}}

Browser compatibility

{{Compat}}

Note

This API is based on Chromium's chrome.storage API. This documentation is derived from storage.json in the Chromium code.