LockManager: request() 方法

語法

request(name, callback)
request(name, options, callback)

引數

name

您想要請求的鎖的識別符號。

options 可選

一個描述您想要建立的鎖的特性的物件。有效值為：

mode 可選

可以是 "exclusive"（獨佔）或 "shared"（共享）。預設值為 "exclusive"。

ifAvailable 可選

如果為 true，則僅當鎖尚未被持有（可用）時，才會授予鎖請求。如果無法授予，回撥函式將以 null 而非 Lock 例項的形式被呼叫。預設值為 false。

steal 可選

如果為 true，則會釋放所有具有相同名稱的已持有鎖，並授予當前請求，從而優先於任何排隊中的相同請求。預設值為 false。

警告： 請謹慎使用！先前在鎖內執行的程式碼將繼續執行，並且可能會與當前持有鎖的程式碼發生衝突。

signal 可選

一個 AbortSignal（AbortController 的 signal 屬性）；如果指定了並且 AbortController 被中止，則如果鎖請求尚未被授予，它將被丟棄。

回撥

在鎖被授予時呼叫的方法。當回撥函式返回（或丟擲異常）時，鎖會自動釋放。通常回調函式是一個非同步函式，這會導致只有在非同步函式完全完成後鎖才會被釋放。

返回值

一個 Promise，它會在鎖釋放後、隨著回撥函式的執行結果而解析（或拒絕），或者在請求被中止時拒絕。

異常

此方法可能返回一個拒絕的 Promise，拒絕原因是一個 DOMException，其型別可能為以下之一：

InvalidStateError DOMException

當環境的文件不完全處於活動狀態時丟擲。

SecurityError DOMException

當無法為當前環境獲取鎖管理器時丟擲。

NotSupportedError DOMException

當 name 以連字元（-）開頭，同時設定了 steal 和 ifAvailable 選項為 true，或者當 signal 選項存在且 steal 或 ifAvailable 選項之一為 true 時丟擲。

AbortError DOMException

當 signal 選項存在且被中止時丟擲。

示例

通用示例

以下示例展示了 request() 方法的基本用法，其中回撥函式為一個非同步函式。一旦回撥函式被呼叫，此源上的任何其他正在執行的程式碼都無法持有 my_resource，直到回撥函式返回為止。

await navigator.locks.request("my_resource", async (lock) => {
  // The lock was granted.
});

mode 示例

以下示例展示瞭如何為讀者和寫者使用 mode 選項。

請注意，這兩個函式都使用名為 my_resource 的鎖。do_read() 請求一個 'shared' 模式的鎖，這意味著跨不同事件處理程式、標籤頁或 worker 的多個呼叫可能會同時發生。

async function do_read() {
  await navigator.locks.request(
    "my_resource",
    { mode: "shared" },
    async (lock) => {
      // Read code here.
    },
  );
}

do_write() 函式使用相同的鎖，但模式為 'exclusive'，這將延遲 do_read() 中 request() 呼叫的執行，直到寫入操作完成。這同樣適用於事件處理程式、標籤頁或 worker。

async function do_write() {
  await navigator.locks.request(
    "my_resource",
    { mode: "exclusive" },
    async (lock) => {
      // Write code here.
    },
  );
}

ifAvailable 示例

要僅在鎖未被佔用時獲取鎖，請使用 ifAvailable 選項。在此函式中，await 意味著該方法在回撥函式完成之前不會返回。由於該鎖僅在可用時才會被授予，因此此呼叫避免了需要等待鎖在別處被釋放。

await navigator.locks.request(
  "my_resource",
  { ifAvailable: true },
  async (lock) => {
    if (!lock) {
      // The lock was not granted - get out fast.
      return;
    }

    // The lock was granted, and no other running code in this origin is holding
    // the 'my_res_lock' lock until this returns.
  },
);

signal 示例

要僅為鎖等待一小段時間，請使用 signal 選項。

const controller = new AbortController();
// Wait at most 200ms.
setTimeout(() => controller.abort(), 200);

try {
  await navigator.locks.request(
    "my_resource",
    { signal: controller.signal },
    async (lock) => {
      // The lock was acquired!
    },
  );
} catch (ex) {
  if (ex.name === "AbortError") {
    // The request aborted before it could be granted.
  }
}

規範

瀏覽器相容性