The Web Storage API provides mechanisms by which browsers can securely store key/value pairs.
This article provides a walkthrough of how to make use of this technology.
Storage objects are simple key-value stores, similar to objects, but they stay intact through page loads. The keys and the values are always strings (note that, as with objects, integer keys will be automatically converted to strings). You can access these values like an object, or with the
Storage.getItem()
and
Storage.setItem()
methods. These three lines all set the (same) colorSetting entry:
localStorage.colorSetting = '#a4509b';
localStorage['colorSetting'] = '#a4509b';
localStorage.setItem('colorSetting', '#a4509b');
注意
: It's recommended to use the Web Storage API (
setItem
,
getItem
,
removeItem
,
key
,
length
) to prevent the
pitfalls
associated with using plain objects as key-value stores.
2 种 Web 存储机制如下：
sessionStorage
maintains a separate storage area for each given origin that's available for the duration of the page session (as long as the browser is open, including page reloads and restores).
localStorage
does the same thing, but persists even when the browser is closed and reopened.
These mechanisms are available via the
Window.sessionStorage
and
Window.localStorage
properties (to be more precise, in supporting browsers the
Window
object implements the
WindowLocalStorage
and
WindowSessionStorage
objects, which the
localStorage
and
sessionStorage
properties are members of) — invoking one of these will create an instance of the
存储
object, through which data items can be set, retrieved, and removed. A different Storage object is used for the
sessionStorage
and
localStorage
for each origin — they function and are controlled separately.
So, for example, initially calling
localStorage
on a document will return a
存储
object; calling
sessionStorage
on a document will return a different
存储
object. Both of these can be manipulated in the same way, but separately.
To be able to use localStorage, we should first verify that it is supported and available in the current browsing session.
Note: This API is available in current versions of all major browsers. Testing for availability is necessary only if you must support very old browsers, such as Internet Explorer 6 or 7, or in the limited circumstances described below.
Browsers that support localStorage have a property on the window object named
localStorage
. However, just asserting that that property exists may throw exceptions. If the
localStorage
object does exist, there is still no guarantee that the localStorage API is actually available, as various browsers offer settings that disable localStorage. So a browser may
support
localStorage, but not make it
available
to the scripts on the page.
For example, Safari browser in Private Browsing mode gives us an empty localStorage object with a quota of zero, effectively making it unusable. Conversely, we might get a legitimate
QuotaExceededError
, which means that we've used up all available storage space, but storage
is
actually
available
. Our feature detection should take these scenarios into account.
Here is a function that detects whether localStorage is both supported and available:
function storageAvailable(type) {
var storage;
try {
storage = window[type];
var x = '__storage_test__';
storage.setItem(x, x);
storage.removeItem(x);
return true;
}
catch(e) {
return e instanceof DOMException && (
// everything except Firefox
e.code === 22 ||
// Firefox
e.code === 1014 ||
// test name field too, because code might not be present
// everything except Firefox
e.name === 'QuotaExceededError' ||
// Firefox
e.name === 'NS_ERROR_DOM_QUOTA_REACHED') &&
// acknowledge QuotaExceededError only if there's something already stored
(storage && storage.length !== 0);
}
}
And here is how you would use it:
if (storageAvailable('localStorage')) {
// Yippee! We can use localStorage awesomeness
}
else {
// Too bad, no localStorage for us
}
You can test for sessionStorage instead by calling
storageAvailable('sessionStorage')
.
See here for a brief history of feature-detecting localStorage .
To illustrate some typical web storage usage, we have created an example, imaginatively called Web 存储演示 。 landing page provides controls that can be used to customize the color, font, and decorative image:
When you choose different options, the page is instantly updated; in addition, your choices are stored in
localStorage
, so that when you leave the page and load it again, later on, your choices are remembered.
We have also provided an
event output page
— if you load this page in another tab, then make changes to your choices in the landing page, you'll see the updated storage information outputted as a
StorageEvent
is fired.
注意 : As well as viewing the example pages live using the above links, you can also check out the source code .
To start with, in main.js , we test whether the storage object has already been populated (i.e., the page was previously accessed):
if(!localStorage.getItem('bgcolor')) {
populateStorage();
} else {
setStyles();
}
Storage.getItem()
method is used to get a data item from storage; in this case, we are testing to see whether the
bgcolor
item exists; if not, we run
populateStorage()
to add the existing customization values to the storage. If there are already values there, we run
setStyles()
to update the page styling with the stored values.
注意
: You could also use
Storage.length
to test whether the storage object is empty or not.
As noted above, values can be retrieved from storage using
Storage.getItem()
. This takes the key of the data item as an argument, and returns the data value. For example:
function setStyles() {
var currentColor = localStorage.getItem('bgcolor');
var currentFont = localStorage.getItem('font');
var currentImage = localStorage.getItem('image');
document.getElementById('bgcolor').value = currentColor;
document.getElementById('font').value = currentFont;
document.getElementById('image').value = currentImage;
htmlElem.style.backgroundColor = '#' + currentColor;
pElem.style.fontFamily = currentFont;
imgElem.setAttribute('src', currentImage);
}
Here, the first three lines grab the values from local storage. Next, we set the values displayed in the form elements to those values, so that they keep in sync when you reload the page. Finally, we update the styles/decorative image on the page, so your customization options come up again on reload.
Storage.setItem()
is used both to create new data items, and (if the data item already exists) update existing values. This takes two arguments — the key of the data item to create/modify, and the value to store in it.
function populateStorage() {
localStorage.setItem('bgcolor', document.getElementById('bgcolor').value);
localStorage.setItem('font', document.getElementById('font').value);
localStorage.setItem('image', document.getElementById('image').value);
setStyles();
}
populateStorage()
function sets three items in local storage — the background color, font, and image path. It then runs the
setStyles()
function to update the page styles, etc.
We've also included an
onchange
handler on each form element so that the data and styling are updated whenever a form value is changed:
bgcolorForm.onchange = populateStorage; fontForm.onchange = populateStorage; imageForm.onchange = populateStorage;
StorageEvent
is fired whenever a change is made to the
存储
object (note that this event is not fired for sessionStorage changes). This won't work on the same page that is making the changes — it is really a way for other pages on the domain using the storage to sync any changes that are made. Pages on other domains can't access the same storage objects.
On the events page (see events.js ) the only JavaScript is as follows:
window.addEventListener('storage', function(e) {
document.querySelector('.my-key').textContent = e.key;
document.querySelector('.my-old').textContent = e.oldValue;
document.querySelector('.my-new').textContent = e.newValue;
document.querySelector('.my-url').textContent = e.url;
document.querySelector('.my-storage').textContent = JSON.stringify(e.storageArea);
});
Here we add an event listener to the
window
object that fires when the
存储
object associated with the current origin is changed. As you can see above, the event object associated with this event has a number of properties containing useful information — the key of the data that changed, the old value before the change, the new value after that change, the URL of the document that changed the storage, and the storage object itself (which we've stringified so you can see its content).
Web Storage also provides a couple of simple methods to remove data. We don't use these in our demo, but they are very simple to add to your project:
Storage.removeItem()
takes a single argument — the key of the data item you want to remove — and removes it from the storage object for that domain.
Storage.clear()
takes no arguments, and simply empties the entire storage object for that domain.
| 规范 | 状态 | 注释 |
|---|---|---|
| HTML 实时标准 | 实时标准 |
Window.localStorage
| 桌面 | 移动 | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
localStorage
|
Chrome 4 | Edge 12 | Firefox 3.5 | IE 8 | Opera 10.5 | Safari 4 | WebView Android ≤37 | Chrome Android 18 | Firefox Android 4 | Opera Android 11 | Safari iOS 3.2 | Samsung Internet Android 1.0 |
完整支持
Window.sessionStorage
| 桌面 | 移动 | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
sessionStorage
|
Chrome 5 | Edge 12 | Firefox 2 | IE 8 | Opera 10.5 | Safari 4 | WebView Android ≤37 | Chrome Android 18 | Firefox Android 4 | Opera Android 11 | Safari iOS 3.2 | Samsung Internet Android 1.0 |
完整支持
All browsers have varying capacity levels for both localStorage and sessionStorage. Here is a detailed rundown of all the storage capacities for various browsers .