/ ↲
    Расширенный поиск

    JavaScript

    localStorage

    Время чтения: меньше 5 мин

    1. Кратко
    2. Пример
    3. Как это понять
    4. Как пишется
      1. Запись
      2. Чтение
      3. Удаление
      4. Очистка хранилища
      5. Количество полей в хранилище
      6. Получение ключа по индексу
      7. События
    5. На практике
      1. Павел Минеев

    Кратко

    Это объект, хранящийся в window, который позволяет долговременно сохранять данные в браузере. Работает как хранилище данных в формате ключ-значение — при сохранении данных мы указываем имя поля, в которое должны быть сохранены данные, и затем используем это имя для их получения.

    • Значения хранятся в виде строк. При попытке сохранения других типов данных, они будут приведены к строке. Например, если записать число, то при чтении нам вернётся число, записанное в строку.
    • Не имеет ограничений по времени хранения, может быть очищен пользователем вручную или браузером при переполнении автоматически (браузеры на основе движка WebKit, например Safari, очищают localStorage, если к нему не обращались в течение 7 дней).
    • Максимальный объем данных ограничен размером 5MB.

    Пример

    Записываем данные:

            
          
          window.localStorage.setItem("name", "Doka Dog")
          window.localStorage.setItem("name", "Doka Dog")

    При чтении ранее записанных данных по ключу name мы получим Doka Dog:

            
          
          const name = window.localStorage.getItem("name")console.log(name)
          const name = window.localStorage.getItem("name")
console.log(name)

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

            
          
          window.localStorage.setItem("name", "Dog Doka")const name = window.localStorage.getItem("name")console.log(name)
          window.localStorage.setItem("name", "Dog Doka")
const name = window.localStorage.getItem("name")
console.log(name)

    Как это понять

    Если вам нужно сохранить данные в браузере на долгое время и объем этих данных достаточно большой, то localStorage — то, что вам нужно. Данные будут храниться бессрочно и могут быть стёрты только в двух случаях: при превышении лимита по размеру данных или очистке хранилища пользователем или программно.

    Как пишется

    Запись

    Для записи используйте метод setItem("ключ", "значение"), который принимает два строковых параметра: ключ, по которому будет сохранено значение, и само значение.

            
          
          window.localStorage.setItem("name", "Doka Dog")
          window.localStorage.setItem("name", "Doka Dog")

    Чтение

    За чтение отвечает getItem("ключ") c одним параметром, который указывает на ключ для чтения и возвращает полученное значение из хранилища. Если по этому ключу нет значения, то метод вернёт null.

            
          
          window.localStorage.getItem("name") // вернет "Doka Dog"window.localStorage.getItem("user") // вернет `null`
          window.localStorage.getItem("name") // вернет "Doka Dog"
window.localStorage.getItem("user") // вернет `null`

    Удаление

    Удаляет запись из хранилища removeItem("ключ"). Он успешно выполнится даже если указанного ключа не существует в хранилище.

            
          
          window.localStorage.removeItem("name")window.localStorage.removeItem("user")
          window.localStorage.removeItem("name")
window.localStorage.removeItem("user")

    Очистка хранилища

    Метод clear() очищает хранилище полностью.

            
          
          window.localStorage.clear()
          window.localStorage.clear()

    Количество полей в хранилище

    Используя свойство length, можно узнать, сколько всего полей было записано в хранилище.

            
          
          window.localStorage.length
          window.localStorage.length

    Получение ключа по индексу

    Метод key() получает ключ по индексу. Значения в хранилище хранятся в порядке их добавления, поэтому значение, добавленное первым, будет храниться в позиции 0 и так далее.

            
          
          window.localStorage.setItem("name", "Doka Dog")window.localStorage.key(0) // вернет "name"
          window.localStorage.setItem("name", "Doka Dog")
window.localStorage.key(0) // вернет "name"

    Таким образом, используя количество полей в хранилище и получение ключа по индексу, можно организовать перебор всех значений в хранилище.

            
          
          const localStorageSize = window.localStorage.lengthfor (let i = 0; i < localStorageSize; i++) {  console.log(window.localStorage.getItem(localStorage.key(i)))}
          const localStorageSize = window.localStorage.length
for (let i = 0; i < localStorageSize; i++) {
  console.log(window.localStorage.getItem(localStorage.key(i)))
}

    События

    При установке значения в хранилище срабатывает глобальное событие storage, с помощью которого можно отслеживать изменения в хранилище.

    💡 Событие происходит только на других открытых страницах текущего сайта.

    Событие содержит свойства:

    • key - ключ, который был изменён (при вызове метода clear(), ключ будет null);
    • oldValue - старое значение, записанное в поле;
    • newValue - новое значение, записанное в поле;
    • url - адрес страницы, на которой вызвано изменение.
            
          
          window.addEventListener("storage", function (evt) {  console.log(evt)})
          window.addEventListener("storage", function (evt) {
  console.log(evt)
})

    На практике

    Павел Минеев

    🛠 При помощи localStorage можно сохранять данные, относящиеся к пользователю, не храня их на сервере. В следующем примере мы будем запоминать размер шрифта на сайте и восстанавливать размер из хранилища, если он был изменён до этого.

    Открыть демо в новой вкладке

    🛠 Можно использовать для синхронизации нескольких открытых в браузере вкладок. При изменении размера шрифта в одной вкладке мы узнаем об этом во всех остальных и тоже изменим размер.

            
          
          function changePageFontSize(size) {  document.style.fontSize = `${size}px`}window.addEventListener("storage", function (evt) {  if (evt.key === "pageFontSize") {    changePageFontSize(evt.newValue)  }})
          function changePageFontSize(size) {
  document.style.fontSize = `${size}px`
}

window.addEventListener("storage", function (evt) {
  if (evt.key === "pageFontSize") {
    changePageFontSize(evt.newValue)
  }
})

    🛠 Иногда нам нужно сохранить не просто текст, а целую структуру данных, и в этом нам поможет JSON.stringify.

            
          
          const user = {  name: "Doka Dog",  avatarUrl: "mascot-doka.svg"}localStorage.setItem("user", JSON.stringify(user))
          const user = {
  name: "Doka Dog",
  avatarUrl: "mascot-doka.svg"
}

localStorage.setItem("user", JSON.stringify(user))

    И после чтения парсим:

            
          
          function readUser() {  const userJSON = localStorage.getItem("user")  if (userJSON === null) {    return undefined  }  // Если вдруг в хранилище оказался невалидный JSON предохраняемся от этого  try {    return JSON.parse(userJSON)  } catch (e) {    localStorage.removeItem("user")    return undefined  }}
          function readUser() {
  const userJSON = localStorage.getItem("user")

  if (userJSON === null) {
    return undefined
  }

  // Если вдруг в хранилище оказался невалидный JSON предохраняемся от этого
  try {
    return JSON.parse(userJSON)
  } catch (e) {
    localStorage.removeItem("user")
    return undefined
  }
}

    🛠 Если ваш сайт использует скрипты аналитики или другие внешние библиотеки, то они также имеют доступ к хранилищу. Поэтому лучше именовать ключи для записи в хранилище с префиксом в едином стиле. Например, при записи чего-либо на таком сайте я бы выбрал префикс YD_{название ключа}, тогда можно сгруппировать только нужные значения или отфильтровать их в инструментах разработчика.

    🛠 Используйте функции-обёртки для предотвращения ошибок, связанных с неудачными попытками записи, отсутствием localStorage в браузере и дублированием кода.

            
          
          function getItem(key, value) {  try {    return window.localStorage.getItem(key)  } catch (e) {    console.log(e)  }}function setItem(key, value) {  try {    return window.localStorage.setItem(key, value)  } catch (e) {    console.log(e)  }}function setJSON(key, value) {  try {    const json = JSON.stringify(value)    setItem(key, json)  } catch (e) {    console.error(e)  }}function getJSON(key) {  try {    const json = getItem(key)    return JSON.parse(json)  } catch (e) {    console.error(e)  }}
          function getItem(key, value) {
  try {
    return window.localStorage.getItem(key)
  } catch (e) {
    console.log(e)
  }
}

function setItem(key, value) {
  try {
    return window.localStorage.setItem(key, value)
  } catch (e) {
    console.log(e)
  }
}

function setJSON(key, value) {
  try {
    const json = JSON.stringify(value)

    setItem(key, json)
  } catch (e) {
    console.error(e)
  }
}

function getJSON(key) {
  try {
    const json = getItem(key)

    return JSON.parse(json)
  } catch (e) {
    console.error(e)
  }
}