ServiceWorkerContainer.register()

La méthode register() de l'interface ServiceWorkerContainer crée ou met à jour un ServiceWorkerRegistration pour la scriptURL donnée.

En cas de succès, un ServiceWorkerRegistration attache la scriptURL fournie à une portée, qui sera utilisé ensuite pour la correspondance de navigation. Vous pouvez appeler cette méthode en toutes circonstances depuis la page contrôlée. C'est-à-dire, vous n'avez pas besoin de vérifier si un enregistrement existe déjà.

Il y a une confusion fréquente autour de la signification et de l'utilisation de la portée. Puisque qu'un ServiceWorker ne peut pas avoir une portée plus large que son propre emplacement, utilisez uniquement l'option de la portée lorsque vous avez besoin d'une portée plus étroite que la valeur par défaut.

Syntaxe

serviceWorkerContainer.register(scriptURL, options)
  .then(function(serviceWorkerRegistration) { ... })

Paramètres

scriptURL
L' URL du script contenant le ServiceWorker. Le fichier qui a enregistré le ServiceWorker doit avoir un JavaScript MIME type valide.
options Facultatif
Un objet contenant les options d'enregistrement. Les options sont:
  • scope: Un USVString représentant une URL qui définit la portée d'enregistrement d'un ServiceWorker; c'est-à-dire quelle plage d'URL un ServiceWorker peut contrôler. Il s'agit généralement d'une URL relative. Elle est relative à l'URL de base de l'application. Par défaut, la valeur de la portée de l'enregistrement d'un ServiceWorker est limité au répertoire qui contient le script du ServiceWorker. Consultez la section Exemples pour plus d'informations sur son fonctionnement.
  • type: Un WorkerType, il prend les valeurs "classic" ou "module". Par défaut, la valeur est fixé à "classic".
  • updateViaCache: Un ServiceWorkerUpdateViaCache, il prend les valeurs "imports" ou "all" ou "none". Par défaut, la valeur est fixé à "imports".

Valeur de retour

Une Promise qui se résout avec un objet ServiceWorkerRegistration.

Exemples

Les exemples décrits ici doivent être pris ensemble pour obtenir une meilleure compréhension de comment la portée des ServiceWorker s'applique à une page.

L'exemple suivant utilise la valeur par défaut de la portée (en l'omettant). Le code du ServiceWorker dans ce cas, s'il est inclus dans example.com/index.html, contrôlera example.com/index.html, ainsi que les pages en dessous, comme 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)
    },
    /*catch*/ (error) => {
      console.log('Service worker registration failed:', error)
    }
  )
} else {
  console.log('Service workers are not supported.')
}

Le code suivant, s'il est inclus dans example.com/index.html, à la racine d'un site, s'appliquerait exactement aux mêmes pages que l'exemple ci-dessus. N'oubliez pas que la portée, lorsqu'elle est incluse, utilise l'emplacement de la page comme base.

Sinon, si ce code était inclus dans une page à example.com/product/description.html, avec le fichier Javascript résidant à example.com/product/sw.js, alors le service worker ne s'appliquerait qu'aux ressources sous 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)
    },
    /*catch*/ (error) => {
      console.log('Service worker registration failed:', error)
    }
  )
} else {
  console.log('Service workers are not supported.')
}

Il y a une confusion fréquente autour de la signification et de l'utilisation de la portée. Puisque qu'un ServiceWorker ne peut pas avoir une portée plus large que son propre emplacement, utilisez uniquement l'option de la portée lorsque vous avez besoin d'une portée plus étroite que la valeur par défaut.

Le code suivant, s'il est inclus dans example.com/index.html, à la racine d'un site, ne s'appliquerait qu'aux ressources sous 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)
    },
    /*catch*/ (error) => {
      console.log('Service worker registration failed:', error)
    }
  )
} else {
  console.log('Service workers are not supported.')
}

Toutefois, les serveurs peuvent supprimer cette restriction en définissant un en-tête Service-Worker-Allowed sur le script du ServiceWorker, et alors vous pouvez spécifier une portée maximale pour ce ServiceWorker au-dessus de l'emplacement du ServiceWorker.

Spécifications

Specification Status Comment
Service Workers
La définition de 'ServiceWorkerContainer: register' dans cette spécification.
Version de travail Définition initiale.

Compatibilité des navigateurs

Update compatibility data on GitHub
OrdinateurMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariWebview AndroidChrome pour AndroidFirefox pour AndroidOpera pour AndroidSafari sur iOSSamsung Internet
register
Expérimentale
Chrome Support complet 40Edge Support complet 17
Support complet 17
Support complet 16
Désactivée
Désactivée From version 16: this feature is behind the Enable service workers preference.
Firefox Support complet 44
Notes
Support complet 44
Notes
Notes Extended Support Releases (ESR) before Firefox 78 ESR do not support service workers and the Push API.
IE Aucun support NonOpera Support complet 27Safari Support complet 11.1WebView Android Support complet 40Chrome Android Support complet 40Firefox Android Support complet 44Opera Android Support complet 27Safari iOS Support complet 11.3Samsung Internet Android Support complet 4.0

Légende

Support complet  
Support complet
Aucun support  
Aucun support
Fonctionnalité expérimentale. Celle-ci peut être amenée à changer par la suite.
Fonctionnalité expérimentale. Celle-ci peut être amenée à changer par la suite.
Voir les notes d'implémentation.
Voir les notes d'implémentation.
Une action explicite de l'utilisateur est nécessaire pour activer cette fonctionnalité.
Une action explicite de l'utilisateur est nécessaire pour activer cette fonctionnalité.

Voir également