Window.localStorage

Властивість localStorage надає доступ до об’єкта Storage, пов'язаного з джерелом поточного документа. Сховище localStorage є схожим на sessionStorage, але не має обмежень тривалості зберігання даних, тоді як дані sessionStorage видаляються по закритті сторінки (насправді, лише після закриття всіх сторінок з цього джерела, якщо їх кілька відкрито в переглядачі).

Варто також зазначити, що сторінки, завантажені з різних джерел (важить все: ім'я хоста, порт, та навіть протокол — http/https), з міркувань безпеки мають незалежні окремі сховища, тож до даних одне одного доступу не мають.

Синтакс

myStorage = window.localStorage;

Значення

Об’єкт типу Storage, який можна використовувати для доступу до чинного для поточної сторінки сховища.

Винятки

SecurityError

Виникає в разі порушення встановлених правил або коли джерелом сторінки є неприйнятний протокол/хост/порт (наприклад, коли протоколом джерела є file: чи data:). Зокрема, користувач може заборонити збереження даних з окремих джерел в налаштуваннях переглядача.

Приклад

Розгляньмо основні дії зі сховищем: запис, читання, видалення окремого ключа та повне очищення всього сховища.

Цей приклад створює (чи змінює, якщо такий ключ вже існує) запис в чинному для поточної сторінки сховищі (через об'єкт типу Storage) за допомогою метода setItem():

localStorage.setItem('Кіт', 'Барсик');

Дістати значення за ключем дозволяє метод getItem():

var cat = localStorage.getItem('Кіт');

Для видалення раніше створеного запису за його ключем існує метод removeItem():

localStorage.removeItem('Кіт');

А для очищення сховища (видалення всіх створених записів) призначено метод clear():

localStorage.clear();

А тепер розгляньмо дещо змістовніший приклад:

function clearCart() {
  var count = parseInt(localStorage.getItem('cart-size')) || 0;
  for (var i = 1; i <= count; i++) {
    localStorage.removeItem('cart-item-' + i)
  }
  localStorage.removeItem('cart-size');
}


function addCartItem(itemId) {
  var count = parseInt(localStorage.getItem('cart-size')) || 0;
  localStorage.setItem('cart-item-' + (count + 1), itemId);
  localStorage.setItem('cart-size', count + 1);
}

function getCartItems() {
  var items = [];
  var count = parseInt(localStorage.getItem('cart-size')) || 0;

  for (var i = 1; i <= count; i++) {
    var itemId = localStorage.getItem('cart-item-' + i);
    items.push(parseInt(itemId));
  }

  return items;
}


addCartItem(111);
addCartItem(222);

console.log(getCartItems());  // виводить [111, 222]
clearCart();
console.log(getCartItems());  // виводить []

Варто зауважити, що сховище працює лише з рядками (як ключ, так і значення мусить бути рядком, або його буде перетворено на рядок неявним викликом toString()). Тому для зберігання структурованих даних доведеться спершу подбати про їх перетворення в текстовий рядок — наприклад, JSON:

function setLocalStorageObjectItem(key, value) {
  if (value === undefined) {
    localStorage.removeItem(key);
  } else {
    localStorage.setItem(key, JSON.stringify(value));
  }
}

function getLocalStorageObjectItem(key) {
  var json = localStorage.getItem(key);
  if (json === undefined) {
    return undefined;
  }
  return JSON.parse(json);
}

setLocalStorageObjectItem('foo', {a: {x: 123}});
console.log(getLocalStorageObjectItem('foo'));  // виводить {a: {x: 123}}

Специфікації

Підтримка веб-переглядачами

Див. також

• Використання Web Storage API
• LocalStorage
• SessionStorage
• Window.sessionStorage