Использование API Web Storage

API Web Storage предоставляет механизмы, с помощью которых браузеры могут безопасно хранить пары «ключ/значение».

В этой статье представлено пошаговое руководство по использованию этой технологии.

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

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

Два механизма внутри Web Storage таковы:

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

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

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

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

Браузеры, поддерживающие localStorage, имеют свойство с именем localStorage в объекте window. Однако просто утверждение о существовании свойства может выбросить исключение. Если объект localStorage существует, нет гарантии, что API localStorage фактически доступен, так как различные браузеры предлагают настройки, которые отключают localStorage. Таким образом, браузер может *поддерживать* localStorage, но не делать его *доступным* для скриптов на странице.

Например, для документа, просматриваемого в режиме приватного просмотра браузера, некоторые браузеры могут вернуть пустой объект localStorage с квотой нуль, что фактически делает его непригодным для использования. И наоборот, мы можем получить законный QuotaExceededError, что означает, что мы использовали всё доступное хранилище, но хранилище *фактически* *доступно*. Наша проверка должна учитывать эти сценарии.

Вот функция, определяющая, поддерживается ли и доступен ли localStorage:

function storageAvailable(type) {
  let storage;
  try {
    storage = window[type];
    const x = "__storage_test__";
    storage.setItem(x, x);
    storage.removeItem(x);
    return true;
  } catch (e) {
    return (
      e instanceof DOMException &&
      e.name === "QuotaExceededError" &&
      // acknowledge QuotaExceededError only if there's something already stored
      storage &&
      storage.length !== 0
    );
  }
}

И вот как её использовать:

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

Для проверки sessionStorage вместо этого можно вызвать storageAvailable('sessionStorage').

См. здесь краткую историю обнаружения localStorage.

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

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

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

Начнём с main.js, где проверяется, был ли объект хранения заполнен (то есть страница ранее была обработана):

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

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

Как указано выше, значения можно извлечь из хранилища с помощью Storage.getItem(). Это принимает ключ элемента данных в качестве аргумента и возвращает значение данных.

Например:

function setStyles() {
  const currentColor = localStorage.getItem("bgcolor");
  const currentFont = localStorage.getItem("font");
  const 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);
}

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

Storage.setItem() используется как для создания новых элементов данных, так и (если элемент данных уже существует) для обновления существующих значений. Это принимает два аргумента — ключ элемента данных для создания/модификации и значение для хранения в нём.

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() устанавливает три элемента в локальном хранилище — цвет фона, шрифт и путь к изображению. Затем она выполняет функцию setStyles() для обновления стилей страницы и т. д.

Мы также включили обработчик onchange для каждого элемента формы, чтобы данные и стили обновлялись при изменении значения формы:

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

Storage поддерживает только хранение и извлечение строк. Если вы хотите сохранить другие типы данных, вам нужно преобразовать их в строки. Для обычных объектов и массивов вы можете использовать JSON.stringify().

const person = { name: "Alex" };
localStorage.setItem("user", person);
console.log(localStorage.getItem("user")); // "[object Object]"; not useful!
localStorage.setItem("user", JSON.stringify(person));
console.log(JSON.parse(localStorage.getItem("user"))); // { name: "Alex" }

Однако нет универсального способа хранения произвольных типов данных. Кроме того, полученный объект является *полной копией* исходного объекта, и изменения в нём не влияют на исходный объект.

Событие StorageEvent срабатывает всякий раз, когда в объекте Storage вносятся изменения (обратите внимание, что это событие не срабатывает при изменении sessionStorage). Это не будет работать на той же странице, которая вносит изменения — это действительно способ для других страниц на домене использовать хранилище для синхронизации внесённых изменений. Страницы на других доменных именах не могут получить доступ к тем же объектам хранилища.

На странице событий (см. events.js) единственный JavaScript-код выглядит следующим образом:

window.addEventListener("storage", (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,
  );
});

Здесь мы добавляем обработчик события к объекту window, который срабатывает при изменении объекта Storage, связанного с текущим источником. Как вы можете видеть выше, объект события, связанный с этим событием, имеет ряд свойств, содержащих полезную информацию — ключ изменённых данных, старое значение до изменения, новое значение после изменения, URL документа, изменившего хранилище, и сам объект хранилища (который мы сериализовали в строку, чтобы вы могли увидеть его содержимое).

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

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

• Главная страница API Web Storage