Pobieranie, ustawianie i usuwanie elementów

Zarówno localStorage, jak i sessionStorage udostępniają te same cztery podstawowe metody: getItem(key), setItem(key, value), removeItem(key) i clear(). Są to proste magazyny klucz-wartość obsługiwane przez przeglądarkę.

localStorage.setItem("theme", "dark") utrwala ciąg znaków pod kluczem "theme". Zarówno klucz, jak i wartość muszą być ciągami znaków — wartości innego typu są przed zapisaniem konwertowane za pomocą String(), co może po cichu zniekształcić obiekty i tablice.

Aby przechowywać dane strukturalne, należy przeprowadzić ich serializację za pomocą JSON: localStorage.setItem("user", JSON.stringify(user)). Odczyt danych wygląda następująco: const user = JSON.parse(localStorage.getItem("user")). Parsowanie należy zawsze umieszczać w bloku try/catch na wypadek, gdyby zapisana wartość była niepoprawna.

getItem("missing") zwraca null, gdy klucz nie istnieje — nigdy undefined. Operatora nullish coalescing należy używać do zapewniania wartości domyślnych: const theme = localStorage.getItem("theme") ?? "light".

Można również używać notacji nawiasowej i kropkowej: localStorage.theme = "dark" oraz localStorage["theme"]. Obie działają, ale zacierają intencję — lepiej używać jawnych wywołań metod, które wyraźnie wskazują, że chodzi o trwały magazyn, a nie właściwość obiektu.

localStorage.removeItem("theme") usuwa pojedynczy klucz. localStorage.clear() usuwa wszystkie klucze dla bieżącego originu. clear() jest operacją destrukcyjną — nie należy jej wywoływać bez ważnego powodu, ponieważ usuwa dane ustawione przez każdy skrypt na stronie.

Użyj localStorage.length i localStorage.key(index), aby przejść przez wszystkie zapisane klucze, albo rozwiń Object.keys(localStorage). Jest to przydatne podczas migracji, debugowania i czyszczenia według prefiksu, na przykład przy usuwaniu wszystkich kluczy zaczynających się od "cache:".

Przeglądarki przydzielają około 5–10 MB na origin. Przekroczenie limitu powoduje zgłoszenie błędu QuotaExceededError. Podczas przechowywania potencjalnie dużych wartości, takich jak pamięci podręczne obrazów lub wersje robocze dokumentów, należy opakować setItem w try/catch, aby błąd nie spowodował awarii aplikacji.

Magazyn jest współdzielony w obrębie całego originu. Aby uniknąć kolizji z innymi skryptami, bibliotekami stron trzecich i rozszerzeniami przeglądarki działającymi w tym samym originie, należy poprzedzać klucze nazwą aplikacji lub funkcji (app:settings, cart:items).

API Storage jest w pełni synchroniczne — każde wywołanie blokuje wątek główny do zakończenia operacji wejścia/wyjścia na dysku. Należy unikać przechowywania bardzo dużych obiektów blob oraz wywoływania setItem w ciasnych pętlach; zamiast tego warto łączyć aktualizacje w jeden serializowany obiekt.

Ten sam interfejs API, inny czas życia. sessionStorage jest czyszczony po zamknięciu karty, a localStorage pozostaje zachowany po ponownym uruchomieniu przeglądarki. sessionStorage należy wybrać do ulotnego stanu kreatora, a localStorage do preferencji użytkownika, które powinny przetrwać ponowne załadowanie strony.

Co zwraca localStorage.getItem("missing-key"), gdy klucz nigdy nie został ustawiony?

getItem, setItem, removeItem i clear to cztery podstawowe elementy Web Storage. Wartości są zawsze ciągami znaków, dlatego dane strukturalne należy opakowywać za pomocą JSON. Trzeba uwzględnić zwracanie null, błąd QuotaExceededError oraz stosować przestrzenie nazw, aby współdzielić origin z innymi skryptami bez konfliktów.