StorageAccessHandle.locks — Eigenschaft · JavaScript-Referenz

Signatur

StorageAccessHandle.locks

Beschreibung

Die schreibgeschützte Eigenschaft locks einer StorageAccessHandle-Instanz liefert einen nicht partitionierten LockManager, also dasselbe Objekt, das die Seite im First-Party-Kontext unter navigator.locks bekommen würde. Damit können Drittanbieter-Iframes (z. B. eingebettete Widgets, Login- oder Chat-Komponenten) Web Locks mit Tabs und Fenstern ihres eigenen Ursprungs teilen und koordinieren.

Im Drittanbieter-Kontext ist navigator.locks normalerweise nach der Top-Level-Site partitioniert. Ein Lock, das ein Iframe von widget.example auf shop.example anfordert, ist deshalb für einen Tab, in dem widget.example direkt geöffnet ist, nicht sichtbar. Über document.requestStorageAccess({ locks: true }) erhält man einen StorageAccessHandle, dessen locks-Eigenschaft diese Grenze aufhebt.

Der Zugriff funktioniert nur, wenn beim Aufruf von requestStorageAccess() ausdrücklich locks: true (oder all: true) übergeben und der Zugriff gewährt wurde. Wurde locks nicht angefordert, löst schon das Lesen der Eigenschaft eine DOMException vom Typ SecurityError aus.

Rückgabewert

Typ

LockManager

Beschreibung

Ein nicht partitionierter LockManager mit den Methoden request() und query(). Wurde der Zugriff nicht angefordert oder nicht gewährt, wird eine DOMException (SecurityError) ausgelöst.

Beispiele

Nicht partitionierten LockManager anfordern und ein Lock halten

// Im Drittanbieter-Iframe, z. B. als Reaktion auf einen Klick
const button = document.querySelector('#sync');

button.addEventListener('click', async () => {
  const handle = await document.requestStorageAccess({ locks: true });

  // Exklusives Lock, das über alle Tabs des Ursprungs hinweg gilt
  await handle.locks.request('token-refresh', async (lock) => {
    console.log('Lock erhalten:', lock.name, lock.mode);
    await fetch('/api/refresh-token', { method: 'POST', credentials: 'include' });
  });

  console.log('Lock wieder freigegeben');
});

Lock erhalten: token-refresh exclusive Lock wieder freigegeben

Aktive und wartende Locks abfragen

const handle = await document.requestStorageAccess({ locks: true });

const { held, pending } = await handle.locks.query();
console.log('Gehalten:', held.map((l) => l.name));
console.log('Wartend:', pending.length);

Gehalten: ["token-refresh"] Wartend: 0

SecurityError abfangen, wenn locks nicht angefordert wurde

const handle = await document.requestStorageAccess({ localStorage: true });

try {
  const locks = handle.locks; // wirft, da locks nicht angefordert
  await locks.request('demo', async () => {});
} catch (err) {
  if (err instanceof DOMException && err.name === 'SecurityError') {
    console.warn('Kein Zugriff auf nicht partitionierte Locks – nutze navigator.locks');
    await navigator.locks.request('demo', async () => {});
  }
}

Kein Zugriff auf nicht partitionierte Locks – nutze navigator.locks

// Wichtig · Fallstricke

Kompatibilität: Die Erweiterung von requestStorageAccess() um Speichertypen und damit StorageAccessHandle gibt es bisher nur in Chromium-Browsern (ab etwa Version 125). Firefox und Safari unterstützen nur die cookiebasierte Variante. Vorher mit 'locks' in handle bzw. über Feature-Erkennung prüfen.
Ausdrücklich anfordern: Ohne { locks: true } oder { all: true } wirft schon der Lesezugriff einen SecurityError, nicht erst der Aufruf von request().
Nutzeraktivierung: Wenn noch keine Berechtigung vorliegt, braucht requestStorageAccess() in der Regel eine Nutzergeste (z. B. einen Klick). Das Promise kann abgelehnt werden. Deshalb immer mit try/catch absichern.
Nicht mit navigator.locks verwechseln: Im Iframe bleibt navigator.locks weiterhin partitioniert. Locks aus beiden Managern schließen sich gegenseitig nicht aus.
Nur in sicheren Kontexten (HTTPS) verfügbar.

Siehe auch

Navigator.locks StorageAccessHandle.caches StorageAccessHandle.localStorage StorageAccessHandle.indexedDB StorageAccessHandle.sessionStorage