Властивість 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();

Заувага: повний приклад див. у статті Використання Web Storage API.

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

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

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

Специфікація Статус Коментар
HTML Living Standard
The definition of 'localStorage' in that specification.
Living Standard  

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

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidEdge MobileFirefox for AndroidOpera for AndroidiOS SafariSamsung Internet
Basic supportChrome Full support 4Edge Full support YesFirefox Full support 3.5IE Full support 8Opera Full support 10.5Safari Full support 4WebView Android Full support YesChrome Android Full support YesEdge Mobile Full support YesFirefox Android Full support YesOpera Android Full support 11Safari iOS Full support 3.2Samsung Internet Android ?

Legend

Full support  
Full support
Compatibility unknown  
Compatibility unknown

Див. також

Мітки документа й учасники

Зробили внесок у цю сторінку: asmforce, igor-budzin, a1b0r, AndriiZ, yuraantonov
Востаннє оновлена: asmforce,