Перевод не завершен. Пожалуйста, помогите перевести эту статью с английского.

Web Storage API предоставляет механизм, при помощи которого броузер может безопасно хранить пары ключей/значениий в намного более интуитивной форме, чем используя cookies. Эта статья предоставляет пошаговое руководство о том, как использовать эту простую технологию.

Основные концепции

Storage объекты простые хранилища вида ключ-значение, похожие чем-то на объекты, но они остаются неизменными при загрузке страницы.  Ключи и значения всегда являются строками (обратите внимание, что числовые ключи будут автоматически конвертироваться в строку, точно также как объекты).  Вы можете получить доступ к этим значениям как в объектах, или getItem() и setItem() методами.  Все три строки ниже устанавливают одинаковое значение в  colorSetting:

localStorage.colorSetting = '#a4509b';
localStorage['colorSetting'] = '#a4509b';
localStorage.setItem('colorSetting', '#a4509b');

В основе Веб хранилища лежат два механизма:

  • (sessionStorage) обслуживает область хранения данных для каждого домена, доступное на протяжении сессии. (пока браузер открыт, даже в случае перезагрузки страницы)
  • (localStorage) делает то же самое, но сохраняет данные даже в случае, если переоткрыть браузер. 

Оба механизма доступны через  Window.sessionStorage и Window.localStorage свойства (если быть более точным, в броузерах, поддерживающих хранилища объект Window  выполняет объекты WindowLocalStorageи WindowSessionStorage, которые содержат свойства localStorageи sessionStorage) — вызов одного из них создает экземляр объекта Storage, через который можно устанавливать, редактировать и удалять данные. Разные Storage объекты будут использовать sessionStorage и localStorage поэтому они используются и управляются раздельно 

Так, например, изначально вызов localStorage в документе возвращает Storage объект; вызов sessionStorage в документе возвращает другой Storage объект. Оба обхекта могут управляться одинаково, но отдельно.

Функция обнаружения localStorage

Чтобы использовать localStorage, мы должны сперва проверить, что localStorage поддерживается и доступно в текущем браузере.

Проверка на наличие

Броузеры поддерживаемые localStorage будут иметь свойство localStorage объекта window. Тем не менее по различным причинам, просто утверждая что свойства существует можно пораждать исключение. Если localStorage существует это еще не дает гарантии, что оно доступно,  т.к. различные броузеры обладают настройками которые отключают его. Поэтому браузер может поддерживать localStorage, но не делает его доступным для скриптов на странице. Один из таких примеров браузер Safari, который в Private Browsing mode возвращает нам пустой localStorage объект, фактически делая его непригодным для использования . Наша функция должна принимать во внимание этот сценарий. 

Функция, которая проверяет браузеры на подержку и доступность localStorage:

function storageAvailable(type) {
	try {
		var storage = window[type],
			x = '__storage_test__';
		storage.setItem(x, x);
		storage.removeItem(x);
		return true;
	}
	catch(e) {
		return false;
	}
}

Вот как вы бы могли использовать это:

if (storageAvailable('localStorage')) {
	// Yippee! We can use localStorage awesomeness
}
else {
	// Too bad, no localStorage for us
}

Вы можете протестировать sessionStorage вместо этого используйте storageAvailable('sessionStorage')Смотрите здесь краткую историю функции-обнаружения localStorage

Пример

Чтобы проилюстрировать типичное использование Web storage, мы создали простой пример, назвав его Web Storage Demo. На целевой странице представлены элементы управления, которые можно использовать для настройки цвета, шрифта и декоративного изображения:

Когда вы выбираете различные опции, страница немедленно перезагружается; в дополнение, ваш выбор сохраняется в localStorage, таким образом когда вы покидаете страницу и загружаете ее снова спустя некоторое время, ваши параметры сохраняются.

Мы также предоставили страницу вывода событий - если вы загрузите эту страницу в другой вкладке, затем сделайте некоторые изменений в landing page,  вы увидите обновленную информацию о хранилище.

Примечание: Помимо просмотра примеров выше, используя приведенные ссылки выше , вы можете также просмотреть исходный код.

Проверка на заполненность хранилища

Начнем с main.js, мы проверим был ли уже заполнен объект Storage (т.е страница была ранее доступна)

if(!localStorage.getItem('bgcolor')) {
  populateStorage();
} else {
  setStyles();
}

Метод Storage.getItem() используется для получения данных из storage; в этом примере мы проверяем, чтобы увидеть существует ли bgcolor; если нет, мы запускаем populateStorage(), чтобы добавить значение по-умолчанию в storage. Если значения уже есть там, мы запускаем setStyles(), для обновления стиля страница с сохраненными значениями.
Примечание: Вы можете также использовать Storage.length для проверки storage object.

Получение данных из Storage

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.

Setting values in storage

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();
}

The 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 is updated whenever a form value is changed:

bgcolorForm.onchange = populateStorage;
fontForm.onchange = populateStorage;
imageForm.onchange = populateStorage;

Responding to storage changes with the StorageEvent

The StorageEvent is fired whenever a change is made to the Storage object. 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 = e.storageArea;
});

Here we add an event listener to the window object that fires when the Storage 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.

Удаление записанных данных

Web Storage также предоставляет несколько простых методов для удаления данных. Мы не используем эти методы в нашем дема, но они очень простые, чтобы добавить их в проект:

  • Storage.removeItem() принимает единственный аргумент - ключ элемента данных, который вы хотите удалить - и удаляет его из объекта хранения для этого домена. 
  • Storage.clear() не принимает аргументов, полностью очищает объекта storage  для данного домена.

Specifications

Specification Status Comment
Unknown Неизвестно  

Browser compatibility

We're converting our compatibility data into a machine-readable JSON format. This compatibility table still uses the old format, because we haven't yet converted the data it contains. Find out how you can help!

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
localStorage 4 3.5 8 10.50 4
sessionStorage 5 2 8 10.50 4
Feature Android Firefox Mobile (Gecko) IE Phone Opera Mobile Safari Mobile
Basic support 2.1 ? 8 11 iOS 3.2

All browsers have varying capacity levels for both localStorage and sessionStorage. Here is a detailed rundown of all the storage capacities for various browsers.

Note: since iOS 5.1, Safari Mobile stores localStorage data in the cache folder, which is subject to occasional clean up, at the behest of the OS, typically if space is short.

See also

Метки документа и участники

Внесли вклад в эту страницу: oxmap, vlad-meskalin, AlexBBB
Обновлялась последний раз: oxmap,