JavaScript свойство Window.localStorage

Определение и применение

JavaScript свойство localStorage объекта Window возвращает ссылку на локальный объект хранения (объект Storage), используемый для хранения данных, которые могут быть доступны только создавшему его источнику.

Интерфейс Storage, принадлежащий API веб-хранилища предоставляет доступ к локальному объекту хранения (localStorage), или объекту хранения текущего сеанса (sessionStorage) для определенного домена (создавшего объект хранения источника):

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

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

Для localStorage и sessionStorage для каждого домена используется отдельный объект хранения — они функционируют и управляются отдельно друг от друга.

Обращаю Ваше внимание, что объем веб-хранилища ограничен размером, и может составлять от 5 до 10 мегабайт, в зависимости от производителя браузера. Это значительно больший объем места на диске в сравнении с cookie, которому доступно всего 4 Кбайта.

Поддержка браузерами

Свойство	Chrome	Firefox	Opera	Safari	IExplorer	Edge
`localStorage`	Да	Да	Да	Да	Да	Да

JavaScript синтаксис:

let myLocalStorage = window.localStorage;

Спецификация

HTML Living Standard

Исключения

Тип исключения	Описание
SecurityError	Возникает в том случае, если запрос нарушает решение политики или источник не является допустимым. Например, у пользователя может быть настроен браузер для отказа в разрешении на сохранение данных для указанного источника.

Тип исключения

Описание

SecurityError

Возникает в том случае, если запрос нарушает решение политики или источник не является допустимым. Например, у пользователя может быть настроен браузер для отказа в разрешении на сохранение данных для указанного источника.

Пример использования

<!DOCTYPE html>
<html>
	<head>
		<title>Использование методов getItem(), setItem() и clear() объекта Storage</title>
	</head>
	<body onload = "init()"> <!-- добавляем атрибут событий onload -->
		<button onclick = "clearLocalStorage()">Clear localStorage</button> <!-- добавляем атрибут событий onclick -->
		<span id = "info"></span>
		<select id = "colorPicker" onchange = "setStyles()"> <!-- добавляем атрибут событий onchange -->
		        <option value = ""></option>
		        <option value = "violet">violet</option>
		        <option value = "green">green</option>
		        <option value = "blue">blue</option>
		</select>
		<script>
	function clearLocalStorage() {
	  localStorage.clear(); // производим очистку всех ключей из объекта хранилища
	  document.getElementById("colorPicker").value = ""; // устанавливаем элементу с переданным id "пустое" значение
	  document.body.style.background = "#fff"; // устанавливаем элементу <body> белый цвет заднего фона
	  updateLocalStorageLength(); // обновляем информацию о числе элементов данных, хранящихся в хранилище
	}

	function setStyles() {
	  const val = document.getElementById("colorPicker").value; // находим элемент по id и инициализируем переменную значением этого элемента
	  try { // пытаемся выполнить код
	    localStorage.setItem("demo_bgcolor", val); // добавляем или обновляем ключ со значением, содержащимся в переменной val
	    document.body.style.background = val; // устанавливаем элементу <body> цвет заднего фона
	  } catch(error) { // перехватываем и обрабатываем ошибку
	    console.log("Ошибочка вышла", error) // выводим в консоль ошибку
	  }
	  updateLocalStorageLength(); // обновляем информацию о числе элементов данных, хранящихся в хранилище 
	} 

	function init() {
	  const demo_bgcolor = localStorage.getItem("demo_bgcolor"); // получаем значение из хранилища по указанному ключу

	  if(demo_bgcolor) { // если переменная содержит значение по указанному ключу (не равна null)
	    document.body.style.background = demo_bgcolor; // устанавливаем элементу <body> цвет заднего фона
	    document.getElementById("colorPicker").value = demo_bgcolor; // устанавливаем элементу с переданным id значение, содержащееся в переменной demo_bgcolor
	  }
	  updateLocalStorageLength(); // обновляем информацию о числе элементов данных, хранящихся в хранилище  
	}
	function updateLocalStorageLength() {
	  document.getElementById("info").innerHTML = localStorage.length; // устанаваливаем в качестве содержимого элемента с определенным id числовое значение, которое соответствует числу элементов данных, хранящихся в хранилище
	}
		</script>
	</body>
</html>

В этом примере с использованием атрибута событий onload, установленном на элементе <body>, мы задаем срабатывание функции init() после завершения полной загрузки страницы. Эта функция с помощью метода getItem() пытается получить значение из локального хранилища (localStorage) по указанному ключу и инициализировать переменную этим значением. Если переменная содержит значение по указанному ключу (не равна null), то мы устанавливаем элементу <body> цвет заднего фона соответствующий значению этой переменной. С помощью JavaScript метода getElementById() объекта Document выбираем элемент с определенным глобальным атрибутом id и устанавливаем этому элементу значение, содержащееся в переменной. Кроме того, мы вызываем функцию updateLocalStorageLength(), которая находит элемент с определенным id и устанаваливает в качестве содержимого элемента числовое значение, которое соответствует числу элементов данных, хранящихся в хранилище.

С использованием атрибута событий onchange, установленном на элементе <select> мы при изменении значений элемента вызываем функцию setStyles(). Эта функция находит элемент <select> по id и инициализирует переменную значением этого элемента. После этого внутри конструкции try...catch с использованием метода setItem() мы пытаемся добавить или обновить ключ со значением внутри локального хранилища, содержащимся в переменной, и устанавливаем элементу <body> цвет заднего фона, соответствующий этому же значению. Если по каким-то причинам произойдет ошибка, то мы выведем эту ошибку в консоль (перехватим). Обратите внимание, что мы вызываем функцию updateLocalStorageLength().

С использованием атрибута событий onclick при нажатии на кнопку (HTML элемент <button>) вызываем функцию, которая с помощью метода clear() производит очистку всех ключей из объекта локального хранилища. Кроме того, находим элемент <select> по id и устанавливаем пустое значение, элементу <body> устанавливаем белый цвет заднего фона. После этого мы вызываем функцию updateLocalStorageLength() и обновляем информацию о числе элементов данных, хранящихся в хранилище.

Результат нашего примера:

Пример использования методов getItem(), setItem() и clear() объекта Storage

В следующем примере мы рассмотрим совместное использование методов getItem(), setItem() и removeItem() объекта Storage.

<!DOCTYPE html>
<html>
	<head>
		<title>Использование методов removeItem(), setItem() и removeItem() объекта Storage</title>
	</head>
	<body>
		<button onclick = "checkKey()">Check key</button> <!-- добавляем атрибут событий onclick -->
		<span id = "info"></span>
		<script>
	function checkKey() {
	  const demo_bgcolor = localStorage.getItem("demo_bgcolor"), // получаем значение из хранилища по указанному ключу
                info = document.getElementById("info"); // производим поиск элемента по id и инициализируем переменную

	  if(demo_bgcolor) { // если переменная содержит значение по указанному ключу (не равна null)
	    localStorage.removeItem("demo_bgcolor"); // удаляем ключ из объекта хранилища
	    info.innerHTML = "Ключ удалён"; // изменяем содержимое элемента
	  } else {
	    try { // пытаемся выполнить код
	      localStorage.setItem("demo_bgcolor", "green"); // добавляем ключ с произвольным строковым значением 
	      info.innerHTML = "Ключ установлен"; // изменяем содержимое элемента
	    } catch (error) { // перехватываем и обрабатываем ошибку
	      info.innerHTML = "Произошла ошибка " + error.message; // изменяем содержимое элемента
	    }
	  }
	}
		</script>
	</body>
</html>

В этом примере с использованием атрибута событий onclick при нажатии на кнопку (HTML элемент <button>) вызываем функцию, которая:

Инициализирует две переменные, первая переменная содержит результат вызова метода getItem(), который позволяет получить значение из хранилища по указанному ключу, а вторая содержит ссылку на элемент с определенным глобальным атрибутом id.
Если первая переменная содержит значение по указанному ключу (не равна null), то мы с помощью метода removeItem() удаляем указанный ключ из объекта хранилища и устанавливаем новое текстовое содержимое элементу, ссылку на который содержит вторая переменная.
Если значение первой переменной соответствует значению null, то внутри конструкции try...catch с использованием метода setItem() мы пытаемся добавить ключ с произвольным строковым значениеми и устанавливаем новое текстовое содержимое элементу <span>. Если по каким-то причинам произойдет ошибка, то мы её перехватим, а информацию о ней добавим в качестве нового текстового содержимого элемента <span>.

Результат нашего примера:

Пример использования методов removeItem(), setItem() и removeItem() объекта Storage — Пример использования методов getItem(), setItem() и removeItem() объекта Storage

JavaScript Window