ServiceWorkerContainer: метод register()

Метод register() интерфейса ServiceWorkerContainer создаёт или обновляет ServiceWorkerRegistration для данного области действия. При успешном выполнении регистрация связывает предоставленный URL скрипта с областью действия, которая впоследствии используется для сопоставления документов с определённым рабочим процессом.

Для каждой уникальной области действия создаётся одна регистрация. Если register() вызывается для области действия, для которой уже существует регистрация, регистрация обновляется с учётом любых изменений в scriptURL или параметрах. Если изменений нет, возвращается существующая регистрация. Обратите внимание, что вызов register() с одной и той же областью действия и scriptURL не перезапускает процесс установки. Таким образом, вы можете вызывать этот метод безусловно с контролируемой страницы: вам не нужно предварительно проверять, есть ли активная регистрация или рабочий процесс.

Документ может потенциально находиться в области действия нескольких регистраций с разными рабочими процессами и параметрами. Браузер свяжет документ с соответствующей регистрацией, которая имеет наиболее узкую область действия. Это гарантирует, что для каждого документа запускается только один рабочий процесс.

scriptURL

URL скрипта рабочего процесса. Файл зарегистрированного рабочего процесса должен иметь допустимый MIME-тип JavaScript.

options Необязательно

Объект, содержащий параметры регистрации. В настоящее время доступны следующие параметры:

scope

Строка, представляющая URL, определяющий область действия регистрации рабочего процесса; то есть, какой диапазон URL рабочий процесс может контролировать.

Обычно он указывается как URL, относительный к базовому URL сайта (например, /some/path/), чтобы разрешённая область действия была одинаковой независимо от того, с какой страницы вызван код регистрации. По умолчанию scope для регистрации рабочего процесса — это каталог, в котором находится скрипт рабочего процесса (разрешая ./ относительно scriptURL).

Область действия должна использоваться для указания документов, которые находятся в одном каталоге или более глубоко вложены, чем скрипт рабочего процесса. Если вам нужна более широкая область действия, это можно разрешить с помощью HTTP-заголовка Service-Worker-Allowed. См. раздел Примеры для получения информации о расширении области действия рабочего процесса по умолчанию.

type

Строка, определяющая тип создаваемого рабочего процесса. Допустимые значения:

'classic'

Загруженный рабочий процесс находится в стандартном скрипте. Это значение по умолчанию.

'module'

Загруженный рабочий процесс находится в модуле ES, и инструкция import доступна в контекстах рабочего процесса. Сведения о совместимости модулей ES см. в таблице совместимости браузеров для интерфейса ServiceWorker.

updateViaCache

Строка, указывающая, как кеш HTTP используется для ресурсов скриптов рабочих процессов во время обновлений. Примечание: это относится только к скрипту рабочего процесса и его импортам, а не к другим ресурсам, полученным этими скриптами.

'all'

Кеш HTTP будет запрошен для основного скрипта и всех импортированных скриптов. Если в кеше HTTP нет свежей записи, скрипты загружаются из сети.

'imports'

Кеш HTTP будет запрошен для импортов, но основной скрипт всегда будет обновляться из сети. Если в кэше HTTP нет свежей записи для импортов, они загружаются из сети.

'none'

Кеш HTTP не будет использоваться для основного скрипта или его импортов. Все ресурсы скриптов рабочего процесса будут обновляться из сети.

A Promise, который разрешается с объектом ServiceWorkerRegistration.

TypeError

Произошла ошибка в scriptURL или scope URL. Это может произойти, если URL не может быть разрешён в допустимый URL или использует схему, которая не является http: или https. Это также может произойти, если scriptURL не является TrustedScriptURL, что является требованием политики Trusted Types сайта.

Исключение также возникает, если в пути scriptURL или scope URL содержится регистронезависимый ASCII "%2f" (*) или "%5c" (=)

SecurityError DOMException

scriptURL не является потенциально надёжным источником, например, localhost или https URL. scriptURL и область действия не находятся в одной области происхождения с регистрируемой страницей.

Примеры ниже следует читать вместе, чтобы понять, как область действия рабочего процесса применяется к странице.

В следующем примере используется значение по умолчанию для scope путём его опущения, что устанавливает его в том же расположении, что и URL скрипта.

Предположим, что код рабочего процесса находится по адресу example.com/sw.js, а код регистрации — по адресу example.com/index.html. Код рабочего процесса будет контролировать example.com/index.html, а также страницы, находящиеся под ним, такие как example.com/product/description.html.

if ("serviceWorker" in navigator) {
  // Register a service worker hosted at the root of the
  // site using the default scope.
  navigator.serviceWorker.register("/sw.js").then(
    (registration) => {
      console.log("Service worker registration succeeded:", registration);
    },
    (error) => {
      console.error(`Service worker registration failed: ${error}`);
    },
  );
} else {
  console.error("Service workers are not supported.");
}

Обратите внимание, что мы зарегистрировали рабочий процесс относительно корня сайта, а не текущей страницы. Это позволяет использовать один и тот же код регистрации с любой страницы.

Код ниже почти идентичен, за исключением того, что мы явно указали область действия с помощью { scope: "/" }. Мы указали область действия как относительную к сайту, чтобы один и тот же код регистрации можно было использовать в любой части сайта.

if ("serviceWorker" in navigator) {
  // declaring scope manually
  navigator.serviceWorker.register("./sw.js", { scope: "/" }).then(
    (registration) => {
      console.log("Service worker registration succeeded:", registration);
    },
    (error) => {
      console.error(`Service worker registration failed: ${error}`);
    },
  );
} else {
  console.error("Service workers are not supported.");
}

Эта область действия совпадает с областью действия по умолчанию, поэтому регистрация применяется к тем же страницам, что и в предыдущем примере. Обратите внимание, что если мы запустим этот код после предыдущего примера, браузеры должны распознать, что мы обновляем существующую регистрацию, а не создаём новую.

Ничто не мешает вам использовать URL, относительные к странице, за исключением того, что это усложняет перемещение страниц, и легко случайно создать ненужные регистрации, если вы это сделаете.

В этом примере код рабочего процесса находится по адресу example.com/product/sw.js, а код регистрации — по адресу example.com/product/description.html. Мы используем URL, относительные к текущему каталогу, для scriptURL и scope, где текущий каталог — это базовый URL страницы, которая вызывает register() (example.com/product/). Рабочий процесс применяется к ресурсам в example.com/product/.

if ("serviceWorker" in navigator) {
  // declaring scope manually
  navigator.serviceWorker.register("./sw.js", { scope: "./" }).then(
    (registration) => {
      console.log("Service worker registration succeeded:", registration);
    },
    (error) => {
      console.error(`Service worker registration failed: ${error}`);
    },
  );
} else {
  console.error("Service workers are not supported.");
}

Сервисный рабочий не может иметь область действия, шире, чем его собственное расположение, если сервер не укажет более широкую максимальную область действия в заголовке Service-Worker-Allowed скрипта сервисного рабочего. Используйте опцию scope , если вам нужна область действия уже, чем по умолчанию.

Следующий код, если включен в example.com/index.html, в корне сайта, будет применяться только к ресурсам под example.com/product.

if ("serviceWorker" in navigator) {
  // declaring scope manually
  navigator.serviceWorker.register("./sw.js", { scope: "/product/" }).then(
    (registration) => {
      console.log("Service worker registration succeeded:", registration);
    },
    (error) => {
      console.error(`Service worker registration failed: ${error}`);
    },
  );
} else {
  console.error("Service workers are not supported.");
}

Как указано выше, серверы могут изменить область действия по умолчанию, установив заголовок Service-Worker-Allowed в скрипте сервисного рабочего. Это позволяет установить опцию scope вне пути, определённого местоположением сервисного рабочего.

Следующий код, если включен в example.com/product/index.html, будет применяться ко всем ресурсам под example.com , если сервер установит заголовок Service-Worker-Allowed в значение / или https://example.com/ при обработке запросов sw.js. Если сервер не установит заголовок, регистрация сервисного рабочего завершится неудачей, так как запрашиваемая scope область слишком широка.

if ("serviceWorker" in navigator) {
  // Declaring a broadened scope
  navigator.serviceWorker.register("./sw.js", { scope: "/" }).then(
    (registration) => {
      // The registration succeeded because the Service-Worker-Allowed header
      // had set a broadened maximum scope for the service worker script
      console.log("Service worker registration succeeded:", registration);
    },
    (error) => {
      // This happens if the Service-Worker-Allowed header doesn't broaden the scope
      console.error(`Service worker registration failed: ${error}`);
    },
  );
} else {
  console.error("Service workers are not supported.");
}

• ServiceWorkerRegistration: метод unregister()
• API сервисных рабочих
• Использование сервисных рабочих
• Service-Worker-Allowed заголовок HTTP