Lock.name — Eigenschaft · JavaScript-Referenz

Signatur

Lock.name

Beschreibung

Die Eigenschaft name eines Lock-Objekts gibt die Zeichenkette zurück, die beim Anfordern des Locks als erstes Argument an LockManager.request() übergeben wurde. Dieser Name steht für die Ressource, die der Lock schützt, etwa "sync-db" oder "token-refresh". Alle Tabs, Worker und Frames desselben Ursprungs (Origin), die denselben Namen anfordern, stimmen sich über diesen Lock ab.

Der Name hat keine vorgegebene Bedeutung, der Browser vergleicht ihn nur als Zeichenkette. Hilfreich ist name vor allem beim Protokollieren und bei Hilfsfunktionen, die mehrere Locks über denselben Callback verwalten. Dort erkennt man daran, welcher Lock gerade vergeben ist.

Den Lock bekommt man nur als Argument des Callbacks von request(). Wenn die Option ifAvailable: true gesetzt ist und der Lock nicht frei ist, bekommt der Callback null statt eines Lock-Objekts. Dann lässt sich name nicht auslesen.

Rückgabewert

Typ

string

Beschreibung

Der Name des Locks, genau so, wie er an LockManager.request() übergeben wurde.

Beispiele

Namen des angeforderten Locks ausgeben

await navigator.locks.request('sync-db', async (lock) => {
  console.log(`Lock erhalten: ${lock.name}`);
  // exklusiver Zugriff auf die Ressource
  await new Promise((r) => setTimeout(r, 500));
});

Lock erhalten: sync-db

Hilfsfunktion mit Protokollierung

const withLock = (name, task) =>
  navigator.locks.request(name, async (lock) => {
    const start = performance.now();
    try {
      return await task();
    } finally {
      console.log(`[${lock.name}] gehalten für ${Math.round(performance.now() - start)} ms`);
    }
  });

const token = await withLock('token-refresh', async () => {
  const res = await fetch('/api/token', { method: 'POST' });
  return res.json();
});

[token-refresh] gehalten für 123 ms

Null-Prüfung bei ifAvailable

await navigator.locks.request('report-export', { ifAvailable: true }, async (lock) => {
  if (!lock) {
    console.log('Export läuft bereits in einem anderen Tab.');
    return;
  }
  console.log(`Starte Export unter Lock "${lock.name}" (${lock.mode})`);
});

Starte Export unter Lock "report-export" (exclusive)

// Wichtig · Fallstricke

Nur lesbar: Wenn man lock.name einen neuen Wert zuweist, wird die Zuweisung ignoriert, im Strict Mode gibt es einen TypeError. Der Name lässt sich nachträglich nicht ändern.
Reservierte Namen: Namen, die mit "-" beginnen, sind reserviert. Bei so einem Namen lehnt request() die Anfrage mit einem NotSupportedError ab.
null möglich: Mit ifAvailable: true kann der Callback null bekommen. Vor dem Zugriff auf lock.name also immer prüfen, ob ein Lock da ist.
Geltungsbereich: Namen gelten nur innerhalb eines Ursprungs (Origin). Andere Websites können denselben Namen nicht blockieren und auch nicht sehen.
Kompatibilität: Funktioniert nur in sicheren Kontexten (HTTPS) und in Window- und Worker-Umgebungen. In Node.js gibt es keine Unterstützung.

Siehe auch

Lock Lock.mode LockManager.request() LockManager.query() LockManager CSSLayerBlockRule.name SVGNumber.value