workbox-window. Workbox
A class to aid in handling service worker registration, updates, and reacting to service worker lifecycle events.
Constructor
Workbox
new Workbox(scriptURL, registerOptions)
Creates a new Workbox instance with a script URL and service worker options. The script URL and options are the same as those used when calling navigator.serviceWorker.register(scriptURL, options)
. See: https://developer.mozilla.org/en-US/docs/Web/API/ServiceWorkerContainer/register
Parameter |
|
---|---|
scriptURL |
string The service worker script associated with this instance. |
registerOptions |
Optional Object The service worker options associated with this instance. |
Properties
active
Resolves to the service worker registered by this instance as soon as it is active. If a service worker was already controlling at registration time then it will resolve to that if the script URLs (and optionally script versions) match, otherwise it will wait until an update is found and activates.
- Returns
-
Promise containing ServiceWorker
controlling
Resolves to the service worker registered by this instance as soon as it is controlling the page. If a service worker was already controlling at registration time then it will resolve to that if the script URLs (and optionally script versions)
match, otherwise it will wait until an update is found and starts controlling the page. Note: the first time a service worker is installed it will active but not start controlling the page unless clients.claim()
is called
in the service worker.
- Returns
-
Promise containing ServiceWorker
Methods
getSW
getSW() returns Promise containing ServiceWorker
Resolves with a reference to a service worker that matches the script URL of this instance, as soon as it's available.
If, at registration time, there's already an active or waiting service worker with a matching script URL, it will be used (with the waiting service worker taking precedence over the active service worker if both match, since the waiting service worker would have been registered more recently). If there's no matching active or waiting service worker at registration time then the promise will not resolve until an update is found and starts installing, at which point the installing service worker is used.
- Returns
-
Promise containing ServiceWorker
messageSW
messageSW(data) returns Promise containing Object
Sends the passed data object to the service worker registered by this instance (via getSW()
) and resolves with a response (if any).
A response can be set in a message handler in the service worker by calling event.ports[0].postMessage(...)
, which will resolve the promise returned by messageSW()
. If no response is set, the promise will never
resolve.
Parameter |
|
---|---|
data |
Object An object to send to the service worker |
- Returns
-
Promise containing Object
register
register(options)
Registers a service worker for this instances script URL and service worker options. By default this method delays registration until after the window has loaded.
Parameter |
|||||
---|---|---|---|---|---|
options |
Optional Object Values in
|
Events
activated
WorkboxEvent
The activated
event is dispatched if the state of a
Workbox
instance's
registered service worker changes to activated
.
Properties
Parameter |
|
---|---|
sw |
ServiceWorker The service worker instance. |
originalEvent |
Event The original |
isUpdate |
(boolean or undefined) True if a service worker was already controlling when this |
type |
string
|
target |
Workbox The |
controlling
WorkboxEvent
The controlling
event is dispatched if a
controllerchange
fires on the service worker container and the scriptURL
of the new controller matches the scriptURL
of the Workbox
instance's
registered service worker.
Properties
Parameter |
|
---|---|
sw |
ServiceWorker The service worker instance. |
originalEvent |
Event The original |
isUpdate |
(boolean or undefined) True if a service worker was already controlling when this service worker was registered. |
type |
string
|
target |
Workbox The |
externalactivated
WorkboxEvent
The externalactivated
event is dispatched if the state of an
external service worker changes to activated
.
Properties
Parameter |
|
---|---|
sw |
ServiceWorker The service worker instance. |
originalEvent |
Event The original |
type |
string
|
target |
Workbox The |
externalinstalled
WorkboxEvent
The externalinstalled
event is dispatched if the state of an
external service worker changes to installed
.
Properties
Parameter |
|
---|---|
sw |
ServiceWorker The service worker instance. |
originalEvent |
Event The original |
type |
string
|
target |
Workbox The |
externalwaiting
WorkboxEvent
The externalwaiting
event is dispatched if the state of an
external service worker changes to waiting
.
Properties
Parameter |
|
---|---|
sw |
ServiceWorker The service worker instance. |
originalEvent |
(Event or undefined) The original |
type |
string
|
target |
Workbox The |
installed
WorkboxEvent
The installed
event is dispatched if the state of a
Workbox
instance's
registered service worker changes to installed
.
Then can happen either the very first time a service worker is installed, or after an update to the current service worker is found. In the case of an update being found, the event's isUpdate
property will be true
.
Properties
Parameter |
|
---|---|
sw |
ServiceWorker The service worker instance. |
originalEvent |
Event The original |
isUpdate |
(boolean or undefined) True if a service worker was already controlling when this |
type |
string
|
target |
Workbox The |
message
WorkboxEvent
The message
event is dispatched any time a postMessage
(or a
BroadcastChannel
message with the workbox
channel name) is received.
Properties
Parameter |
|
---|---|
data |
any type The |
originalEvent |
Event The original |
type |
string
|
target |
Workbox The |
redundant
WorkboxEvent
The redundant
event is dispatched if the state of a
Workbox
instance's
registered service worker changes to redundant
.
Properties
Parameter |
|
---|---|
sw |
ServiceWorker The service worker instance. |
originalEvent |
Event The original |
isUpdate |
(boolean or undefined) True if a service worker was already controlling when this |
type |
string
|
target |
Workbox The |
waiting
WorkboxEvent
The waiting
event is dispatched if the state of a
Workbox
instance's
registered service worker changes to installed
and then doesn't immediately change to activating
. It may
also be dispatched if a service worker with the same
scriptURL
was already waiting when the register()
method was called.
Properties
Parameter |
|
---|---|
sw |
ServiceWorker The service worker instance. |
originalEvent |
Event The native |
isUpdate |
(boolean or undefined) True if a service worker was already controlling when this |
wasWaitingBeforeRegister |
(boolean or undefined) True if a service worker with a matching |
type |
string
|
target |
Workbox The |