Конфигурация работника службы¶

28.02.2022

В этой теме описываются свойства файла конфигурации работника службы.

Предварительные условия¶

Базовое понимание следующего:

• Service worker overview
• Service Worker in Production

Конфигурационный файл ngsw-config.json определяет, какие файлы и URL данных должен кэшировать сервисный работник Angular и как он должен обновлять кэшированные файлы и данные. Angular CLI обрабатывает конфигурационный файл во время ng build.

Вручную, обработайте его с помощью инструмента ngsw-config (где <имя проекта> — имя собираемого проекта):

1

./node_modules/.bin/ngsw-config ./dist/<project-name> ./ngsw-config.json [/base/href]

Конфигурационный файл использует формат JSON. Все пути к файлам должны начинаться с /, что соответствует директории развертывания — обычно dist/<имя проекта> в проектах CLI.

Если не указано иное, шаблоны используют ограниченный формат glob, который внутри будет преобразован в regex:

Примеры шаблонов:

Свойства конфигурации работника службы¶

В следующих разделах описывается каждое свойство конфигурационного файла.

appData¶

Этот раздел позволяет вам передать любые данные, которые описывают данную конкретную версию приложения. Служба SwUpdate включает эти данные в уведомления об обновлении.

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

index¶

Определяет файл, который служит в качестве индексной страницы для удовлетворения навигационных запросов. Обычно это /index.html.

assetGroups¶

Ассеты — это ресурсы, которые являются частью версии приложения и обновляются вместе с ним. Они могут включать ресурсы, загруженные из исходного текста страницы, а также сторонние ресурсы, загруженные из CDN и других внешних URL.

Поскольку не все такие внешние URL могут быть известны на момент сборки, можно сопоставить шаблоны URL.

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

{
  "assetGroups": [
    {
      …
    },
    {
      …
    }
  ]
}

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

Группы активов следуют интерфейсу Typescript, показанному здесь:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

interface AssetGroup {
    name: string;
    installMode?: 'prefetch' | 'lazy';
    updateMode?: 'prefetch' | 'lazy';
    resources: {
        files?: string[];
        urls?: string[];
    };
    cacheQueryOptions?: {
        ignoreSearch?: boolean;
    };
}

Каждая AssetGroup определяется следующими свойствами группы активов.

имя.¶

Имя name является обязательным. Оно идентифицирует данную конкретную группу активов между версиями конфигурации.

installMode.¶

Свойство installMode определяет способ первоначального кэширования этих ресурсов. Значение installMode может быть одним из двух:

По умолчанию используется prefetch.

updateMode¶

Для ресурсов, уже находящихся в кэше, параметр updateMode определяет поведение кэша при обнаружении новой версии приложения. Любые ресурсы в группе, которые изменились с предыдущей версии, обновляются в соответствии с updateMode.

По умолчанию принимает значение, на которое установлен installMode.

resources¶

В этом разделе описываются ресурсы для кэширования, разбитые на следующие группы:

cacheQueryOptions¶

Эти опции используются для изменения поведения при подборе запросов. Они передаются в функцию браузера Cache#match.

Подробности смотрите в MDN.

В настоящее время поддерживаются только следующие опции:

dataGroups¶

В отличие от ресурсов активов, запросы данных не версионируются вместе с приложением. Они кэшируются в соответствии с настроенными вручную политиками, которые более полезны для таких ситуаций, как API-запросы и другие зависимости данных.

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

{
  "dataGroups": [
    {
      …
    },
    {
      …
    }
  ]
}

Группы данных следуют этому интерфейсу Typescript:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

export interface DataGroup {
    name: string;
    urls: string[];
    version?: number;
    cacheConfig: {
        maxSize: number;
        maxAge: string;
        timeout?: string;
        strategy?: 'freshness' | 'performance';
    };
    cacheQueryOptions?: {
        ignoreSearch?: boolean;
    };
}

Каждая Группа данных определяется следующими свойствами группы данных.

name¶

Подобно assetGroups, каждая группа данных имеет name, которое уникально идентифицирует ее.

urls¶

Список шаблонов URL. URL, соответствующие этим шаблонам, кэшируются в соответствии с политикой этой группы данных.

Кэшируются только не мутирующие запросы (GET и HEAD).

• Отрицательные шаблоны glob не поддерживаются
• ? используется буквально, то есть соответствует только символу ?.

version¶

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

version предоставляет механизм для указания того, что кэшируемые ресурсы были обновлены обратно несовместимым способом, и что старые записи кэша —от предыдущих версий— должны быть отброшены.

Поле version является целочисленным и по умолчанию равно 1.

cacheConfig¶

Следующие свойства определяют политику кэширования соответствующих запросов.

maxSize¶

Обязательно

Максимальное количество записей, или ответов, в кэше. Неограниченные кэши могут расти неограниченно и в конечном итоге превысить квоты хранения, что приведет к необходимости выселения.

maxAge¶

Необходимо

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

Например, строка 3d12h кэширует содержимое на срок до трех с половиной дней.

timeout¶

Эта строка duration задает таймаут сети. Таймаут сети — это время, в течение которого работник службы Angular ожидает ответа сети, прежде чем использовать кэшированный ответ, если он настроен. timeout — это строка длительности, использующая следующие суффиксы единиц измерения:

Например, строка 5s30u означает 5 секунд и 30 миллисекунд сетевого тайм-аута.

strategy¶

Angular service worker может использовать одну из двух стратегий кэширования для ресурсов данных.

cacheOpaqueResponses¶

Должен ли работник службы Angular кэшировать непрозрачные ответы или нет.

Если не указано, значение по умолчанию зависит от настроенной стратегии группы данных:

cacheQueryOptions¶

Подробности см. в assetGroups

navigationUrls¶

Этот необязательный раздел позволяет указать пользовательский список URL, которые будут перенаправлены в индексный файл.

Обработка навигационных запросов¶

ServiceWorker перенаправляет навигационные запросы, которые не соответствуют какой-либо группе asset или data, в указанный индексный файл. Запрос считается навигационным, если:

• Его метод — GET.

• Его режим — navigation.

• Он принимает ответ text/html, что определяется значением заголовка Accept.

• Его URL соответствует следующим критериям:

  • URL не должен содержать расширение файла (то есть, .) в последнем сегменте пути.

  • URL не должен содержать __

Соответствие URL-адресов навигационных запросов¶

Хотя эти критерии по умолчанию подходят в большинстве случаев, иногда желательно настроить другие правила. Например, вы можете захотеть игнорировать определенные маршруты, например, те, которые не являются частью приложения Angular, и передавать их серверу.

Это поле содержит массив URL-адресов и glob-like шаблонов URL, которые будут сопоставляться во время выполнения. Он может содержать как отрицательные шаблоны (то есть шаблоны, начинающиеся с !), так и неотрицательные шаблоны и URL.

Навигационными считаются только те запросы, URL которых соответствуют любому из неотрицательных URL/шаблонов и ни одному из отрицательных. Запрос URL игнорируется при сопоставлении.

Если поле опущено, оно используется по умолчанию:

1
2
3
4
5
6

[
    '/**', // Include all URLs.
    '!/**/*.*', // Exclude URLs to files.
    '!/**/*__*', // Exclude URLs containing `__` in the last segment.
    '!/**/*__*/**', // Exclude URLs containing `__` in any other segment.
];

navigationRequestStrategy¶

Это необязательное свойство позволяет вам настроить, как работник службы обрабатывает навигационные запросы:

1
2
3

{
    "navigationRequestStrategy": "freshness"
}

Комментарии