LockManager: request() 方法

name

要请求的锁的标识符。

options 可选

描述要创建的锁的特征的对象。有效值为

mode 可选

"exclusive" 或 "shared"。默认值为 "exclusive"。

ifAvailable 可选

如果为 true，则只有在锁未被持有时才授予锁请求。如果无法授予，则回调函数将被调用，并返回 null 而不是 Lock 实例。默认值为 false。

steal 可选

如果为 true，则会释放任何具有相同名称的持有锁，并授予请求，优先于任何排队的请求。默认值为 false。

警告：谨慎使用！以前在锁内运行的代码将继续运行，并且可能与现在持有锁的代码发生冲突。

signal 可选

一个 AbortSignal（signal 属性为 AbortController）；如果指定并 AbortController 被中止，则锁请求将被丢弃，前提是它尚未被授予。

callback

当授予锁时调用的方法。当回调函数返回（或抛出异常）时，锁会自动释放。通常，回调函数是一个异步函数，这会导致锁仅在异步函数完全完成时才释放。

一个 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 选项来进行读写操作。

请注意，这两个函数都使用名为 my_resource 的锁。do_read() 请求 'shared' 模式的锁，这意味着多个调用可以在不同的事件处理程序、标签或工作线程中同时发生。

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

do_write() 函数使用相同的锁，但使用 'exclusive' 模式，这将延迟 do_read() 中的 request() 调用的调用，直到写入操作完成。这适用于事件处理程序、标签或工作线程。

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

要仅在锁未被持有时才获取锁，请使用 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 选项。

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