后台提取简介

杰克·阿奇博尔德
Jake Archibald

2015 年,我们引入了后台同步,可让 Service Worker 推迟工作,直到用户连接到网络为止。这意味着,用户可以输入消息并点击“发送”,然后离开网站,知道消息将立即发送或在他们连接到网络后发送。

这是一项很有用的功能,但它要求 Service Worker 在提取期间处于活动状态。对于发送消息等简短的工作来说,这没有问题,但如果任务花费的时间太长,浏览器将终止 Service Worker,否则会给用户隐私和电池带来风险。

因此,如果您需要下载可能需要很长时间的内容(例如电影、播客或游戏关卡),该怎么办?这就是后台提取的用途。

从 Chrome 74 开始,后台提取功能默认可用。

以下为两分钟的简短演示,展示了与使用后台提取相比的传统状态:

亲自尝试演示浏览代码

运作方式

后台提取的工作原理如下:

  1. 您需要指示浏览器在后台执行一组提取。
  2. 浏览器提取这些内容,并向用户显示进度。
  3. 在提取完成或失败后,浏览器会打开您的 Service Worker 并触发一个事件,告诉您发生了什么。您可以在此处决定如何处理响应(如果有)。

如果用户在完成第 1 步后关闭了您网站中的网页,这也没有关系,下载会继续进行。由于提取操作高度可见且可轻松取消,因此执行时间过长的后台同步任务不会带来隐私问题。由于 Service Worker 不会持续运行,因此不必担心它可能会滥用系统,例如在后台挖掘比特币。

在某些平台(如 Android)上,浏览器可以在完成第 1 步后关闭,因为浏览器可以将提取任务转交给操作系统。

如果用户在离线时开始下载,或在下载过程中离线,后台提取会暂停并稍后恢复。

API

功能检测

与任何新功能一样,您需要检测浏览器是否支持此功能。对于后台提取,操作非常简单,如下所示:

if ('BackgroundFetchManager' in self) {
  // This browser supports Background Fetch!
}

启动后台提取

主 API 挂起Service Worker 注册,因此请务必先注册一个 Service Worker。然后,执行以下操作:

navigator.serviceWorker.ready.then(async (swReg) => {
  const bgFetch = await swReg.backgroundFetch.fetch('my-fetch', ['/ep-5.mp3', 'ep-5-artwork.jpg'], {
    title: 'Episode 5: Interesting things.',
    icons: [{
      sizes: '300x300',
      src: '/ep-5-icon.png',
      type: 'image/png',
    }],
    downloadTotal: 60 * 1024 * 1024,
  });
});

backgroundFetch.fetch 采用三个参数:

参数
id string
此后台提取的唯一标识符。

如果 ID 与现有后台提取匹配,backgroundFetch.fetch 将拒绝。

requests Array<Request|string>
要提取的内容。字符串将被视为网址,并通过 new Request(theString) 转换为 Request

您可以从其他来源提取内容,前提是相应资源允许通过 CORS 提取。

注意:Chrome 目前不支持需要 CORS 预检的请求。

options 一个对象,其中可能包含以下内容:
options.title string
与进度一起显示的浏览器标题。
options.icons Array<IconDefinition>
包含“src”“size”和“type”的对象数组。
options.downloadTotal number
响应正文(取消 gzip 处理后)的总大小。

虽然这是一项可选操作,但我们强烈建议您提供。它用于告知用户下载内容的大小,并提供进度信息。如果您未提供这项属性,浏览器会告知用户大小未知,在这种情况下,用户更有可能中止下载。

如果后台提取下载次数超过此处给出的数量,则会取消下载。下载量小于 downloadTotal 完全没有问题,因此,如果您不确定总下载量会是多少,最好谨慎行事。

backgroundFetch.fetch 会返回使用 BackgroundFetchRegistration 解析的 promise。我们稍后会对此进行详细介绍如果用户选择停用下载,或者提供的某个参数无效,则 promise 会拒绝。

通过为单个后台提取操作提供多个请求,您可以将在逻辑上对用户而言是单件事情的事物进行组合。例如,一部电影可能会拆分成数千个资源(通常使用 MPEG-DASH),并附带图片等其他资源。一个游戏的关卡可以分布在许多 JavaScript、图片和音频资源中。但对用户而言,则只有“电影”或“关卡”。

获取现有后台提取

您可以获取如下所示的现有后台提取:

navigator.serviceWorker.ready.then(async (swReg) => {
  const bgFetch = await swReg.backgroundFetch.get('my-fetch');
});

...方法是传递所需后台提取的 id。如果没有具有该 ID 的有效后台提取,get 会返回 undefined

后台提取从注册之时起被视为“有效”,直到成功、失败或被取消。

您可以使用 getIds 获取所有活跃后台提取的列表:

navigator.serviceWorker.ready.then(async (swReg) => {
  const ids = await swReg.backgroundFetch.getIds();
});

后台提取注册

BackgroundFetchRegistration(上述示例中的 bgFetch)具有以下特点:

属性
id string
后台提取的 ID。
uploadTotal number
要发送到服务器的字节数。
uploaded number
已成功发送的字节数。
downloadTotal number
注册后台提取时提供的值,或零。
downloaded number
成功接收的字节数。

此值可能会降低。例如,如果连接断开且下载无法恢复,在这种情况下,浏览器会从头开始重新开始提取该资源。

result

以下项之一:

  • "" - 后台提取处于活动状态,因此尚无任何结果。
  • "success" - 后台提取成功。
  • "failure" - 后台提取失败。此值仅在后台提取完全失败时显示,因为浏览器中无法重试/恢复。
failureReason

以下项之一:

  • "" - 后台提取尚未失败。
  • "aborted" - 后台提取已被用户取消,或调用了 abort()
  • "bad-status" - 其中一个响应处于不正常状态,例如 404。
  • "fetch-error" - 某项提取因其他原因而失败,例如 CORS、MIX、无效的部分响应,或常规网络故障导致无法重试的提取。
  • "quota-exceeded" - 在后台提取过程中达到了存储空间配额。
  • "download-total-exceeded" - 已超出提供的 `downloadTotal`。
recordsAvailable boolean
能否访问底层请求/响应?

一旦为 false,matchmatchAll 便无法再使用。

方法
abort() 返回 Promise<boolean>
取消后台提取。

如果提取成功取消,返回的 promise 将解析为 true。

matchAll(request, opts) 返回 Promise<Array<BackgroundFetchRecord>>
获取请求和响应。

此处的参数与缓存 API 相同。不使用参数的调用会返回所有记录的 promise。

详见下文说明。

match(request, opts) 返回 Promise<BackgroundFetchRecord>
同上,但使用第一个匹配项进行解析。
活动
progress uploadeddownloadedresultfailureReason 中的任何一项发生变化时触发。

跟踪进度

这可以通过 progress 事件来完成。请注意,downloadTotal 是您提供的任何值,如果您未提供值,则为 0

bgFetch.addEventListener('progress', () => {
  // If we didn't provide a total, we can't provide a %.
  if (!bgFetch.downloadTotal) return;

  const percent = Math.round(bgFetch.downloaded / bgFetch.downloadTotal * 100);
  console.log(`Download progress: ${percent}%`);
});

获取请求和响应

bgFetch.match('/ep-5.mp3').then(async (record) => {
  if (!record) {
    console.log('No record found');
    return;
  }

  console.log(`Here's the request`, record.request);
  const response = await record.responseReady;
  console.log(`And here's the response`, response);
});

record 是一个 BackgroundFetchRecord,如下所示:

属性
request Request
提供的请求。
responseReady Promise<Response>
提取的响应。

该响应位于 promise 后面,因为可能尚未收到该响应。如果提取失败,promise 将拒绝。

Service Worker 事件

活动
backgroundfetchsuccess 已成功提取所有内容。
backgroundfetchfailure 一项或多项抓取失败。
backgroundfetchabort 一项或多项提取失败。

这只有在您想要清理相关数据时才会真正有用。

backgroundfetchclick 用户点击了下载进度界面。

事件对象包含以下内容:

属性
registration BackgroundFetchRegistration
方法
updateUI({ title, icons }) 可让您更改最初设置的标题/图标。此操作是可选的,但可让您在必要时提供更多上下文。在 backgroundfetchsuccessbackgroundfetchfailure 事件期间,您只能执行 *一次* 操作。

响应成功/失败

我们已经了解了 progress 事件,但仅当用户打开了您的网站的网页时,该事件才有用。后台提取的主要优势在于,在用户离开页面甚至关闭浏览器后,内容仍可继续工作。

如果后台提取成功完成,您的 Service Worker 将收到 backgroundfetchsuccess 事件,而 event.registration 将是后台提取注册。

此事件之后,无法再访问提取的请求和响应,因此如果您想保留它们,请将其移至某个位置,例如 Cache API

与大多数 Service Worker 事件一样,请使用 event.waitUntil,以便 Service Worker 知道事件何时完成。

例如,在您的 Service Worker 中:

addEventListener('backgroundfetchsuccess', (event) => {
  const bgFetch = event.registration;

  event.waitUntil(async function() {
    // Create/open a cache.
    const cache = await caches.open('downloads');
    // Get all the records.
    const records = await bgFetch.matchAll();
    // Copy each request/response across.
    const promises = records.map(async (record) => {
      const response = await record.responseReady;
      await cache.put(record.request, response);
    });

    // Wait for the copying to complete.
    await Promise.all(promises);

    // Update the progress notification.
    event.updateUI({ title: 'Episode 5 ready to listen!' });
  }());
});

失败可能是单个 404 错误,这对您而言可能并不重要,因此仍有必要将一些响应复制到缓存中(如上所述)。

响应点击

显示下载进度和结果的界面可点击。借助 Service Worker 中的 backgroundfetchclick 事件,您可以做出响应。如上所述,event.registration 将是后台提取注册。

处理此事件的常见操作是打开一个窗口:

addEventListener('backgroundfetchclick', (event) => {
  const bgFetch = event.registration;

  if (bgFetch.result === 'success') {
    clients.openWindow('/latest-podcasts');
  } else {
    clients.openWindow('/download-progress');
  }
});

其他资源

更正:本文之前的版本错误地将后台提取称为“网络标准”。该 API 目前不在标准轨道中,规范可在 WICG 中找到(以社区群组草稿形式提供)。