JavaScript метод Storage.setItem()

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

JavaScript метод setItem() объекта Storage при передаче имени и значения ключа этот ключ добавляется в хранилище (объект Storage) или обновляется, если он уже существует.

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

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

Метод	Chrome	Firefox	Opera	Safari	IExplorer	Edge
`setItem()`	Да	Да	Да	Да	8.0	Да

JavaScript синтаксис:

localStorage.setItem(keyName, keyValue);
sessionStorage.setItem(keyName, keyValue);

keyName - String
keyValue - String
localStorage, sessionStorage - Storage

Версия JavaScript

HTML Living Standard

Значения параметров

Параметр	Описание
keyName	Строковое значение, содержащее имя ключа, который Вы хотите создать, или обновить. Обязательный параметр.
keyValue	Строковое значение, содержащее значение, которое вы хотите присвоить ключу при создании, или обновлении. Обязательный параметр.

Исключения

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

Кроме того, некоторые браузеры, например, Safari, в режиме инкогнито выбрали такое решение при котором хранилище доступно, но пусто и имеет квоту 0 байт, что фактически делает невозможным запись в него данных. В результате чего при попытке записи будет генерироваться исключение. Разработчики должны учитывать эти нюансы и перехватывать подобные исключения для корректной работы программ.

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

<!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().

<!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

В следующем примере мы рассмотрим совместное использование методов setItem(), key() и свойства length.

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

	  for(let i = 0; i < 5; i ++) { // создаем цикл с пятью итерациями
	    let key = "demo_key_" + i; // инициализируем строковую переменную
	    let val = i; // инициализируем переменную со значением i
	    try { // пытаемся выполнить код
	      sessionStorage.setItem(key, val); // добавляем ключ и значение в хранилище сессии
	    } catch (error) { // перехватываем и обрабатываем ошибку
	      info.innerHTML = "Произошла ошибка " + error.message; // изменяем содержимое элемента
	    }
	  }
    
	  for(let i = 0; i < sessionStorage.length; i++) { // проходим циклом по всем элементам хранилища
	    let currentKeyValue = sessionStorage.key(i); // возвращает имя ключа по определенному индексу в хранилище
	    info.innerHTML += "	<p>Ключ под индексом " + i + " равен	<b>" + currentKeyValue + "</b></p>"; // добавляем содержимое элементу
	  }
	}
		</script>
	</body>
</html>

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

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

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

JavaScript Storage