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
messageSkipWaiting
messageSkipWaiting()
Sends a {type: 'SKIP_WAITING'}
message to the service worker that's
currently in the waiting
state associated with the current registration.
If there is no current registration or no service worker is waiting
,
calling this will have no effect.
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
|
update
update()
Checks for updates of the registered service worker.
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 |
isExternal |
(boolean or undefined) True if this event is associated with an external service worker. |
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 |
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 |
isExternal |
(boolean or undefined) True if this event is associated with an external service worker. |
type |
string
|
target |
Workbox The |
message
WorkboxEvent
The message
event is dispatched any time a postMessage
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 or undefined) The original
|
isUpdate |
(boolean or undefined) True if a service worker was already
controlling when this |
isExternal |
(boolean or undefined) True if this event is associated with an external service worker. |
wasWaitingBeforeRegister |
(boolean or undefined) True if a service worker with
a matching |
type |
string
|
target |
Workbox The |