워크박스 코어

Workbox는 모듈식으로 빌드되었으므로 개발자가 단일 파일로 모든 항목을 다운로드하지 않고도 사용하려는 부분을 선택할 수 있습니다.

하지만 모듈 간에는 겹치는 부분이 있습니다. 예를 들어 각 모듈은 콘솔과 상호작용해야 하고, 의미 있는 오류를 발생시키며, 네트워크 또는 캐시를 활용해야 합니다. 각 모듈이 동일한 로직을 구현하는 것을 방지하기 위해 workbox-core에는 각 모듈이 사용하는 이 공통 코드가 포함되어 있습니다.

이 모듈은 개발자에게 일부 기능을 제공하지만, 로그 수준과 캐싱 외에도 workbox-core는 최종 개발자가 아닌 각 모듈에 내부 로직을 제공합니다.

기본 캐시 이름 보기 및 변경

Workbox는 cacheNames를 통해 캐시를 정의합니다.

import {cacheNames} from 'workbox-core';

console.log(cacheNames.precache);
console.log(cacheNames.runtime);
console.log(cacheNames.googleAnalytics);

이러한 캐시 이름은 프리픽스, 이름, 접미사 형식으로 구성되며 캐시 사용에 따라 이름이 변경됩니다.

<prefix>-<cache-id>-<suffix>

setCacheNameDetails()에 전달된 값의 전체 또는 일부를 변경하여 이러한 기본 이름을 변경할 수 있습니다.

import {cacheNames, setCacheNameDetails} from 'workbox-core';

setCacheNameDetails({
  prefix: 'my-app',
  suffix: 'v1',
  precache: 'install-time',
  runtime: 'run-time',
  googleAnalytics: 'ga',
});

// Will print 'my-app-install-time-v1'
console.log(cacheNames.precache);

// Will print 'my-app-run-time-v1'
console.log(cacheNames.runtime);

// Will print 'my-app-ga-v1'
console.log(cacheNames.googleAnalytics);

접두사 및 접미사의 주요 사용 사례는 여러 프로젝트에 Workbox를 사용하고 프로젝트마다 동일한 로컬 호스트 포트를 사용하는 경우 각 모듈에 커스텀 접두사를 설정하면 캐시가 서로 충돌하는 것을 방지하는 것입니다.

고객의 클레임

일부 개발자는 새 서비스 워커를 게시하고 활성화되자마자 이미 열려 있는 웹페이지를 제어할 수 있기를 원하며, 이러한 상황은 기본적으로 발생하지 않습니다.

이 동작을 원할 경우 workbox-core에서 도우미 메서드를 제공합니다.

import {clientsClaim} from 'workbox-core';

// This clientsClaim() should be at the top level
// of your service worker, not inside of, e.g.,
// an event handler.
clientsClaim();

workbox-core의 clientsClaim() 메서드는 activate 이벤트 리스너를 서비스 워커에 자동으로 추가하고 그 내부에서 self.clients.claim()를 호출합니다. 현재 서비스 워커가 활성화되기 전에 self.clients.claim()를 호출하면 런타임 예외가 발생하고 workbox-core의 래퍼를 사용하면 적절한 시점에 호출할 수 있습니다.

skipWaiting 래퍼가 지원 중단됨

Workbox v6 이전에는 개발자가 workbox-core의 skipWaiting() 메서드도 사용하도록 권장되었습니다. 그러나 이 메서드는 개발자가 self.skipWaiting()를 명시적으로 호출할 경우 얻을 수 있는 것 이상의 가치가 거의 없었습니다.

기존 workbox-core 래퍼도 self.skipWaiting()가 호출되는 install 이벤트 핸들러를 등록했으므로 설치가 이미 완료된 후 래퍼가 message와 같은 다른 이벤트 핸들러 내부에서 호출되면 예상대로 작동하지 않습니다.

이러한 이유로 workbox-core의 skipWaiting()는 지원 중단되며 개발자는 self.skipWaiting()를 직접 호출하도록 전환해야 합니다. self.clients.claim()와 달리 self.skipWaiting()는 '잘못된' 시간에 호출되어도 예외가 발생하지 않으므로 이벤트 핸들러에서 래핑할 필요가 없습니다.

유형

CacheDidUpdateCallback()

workbox-core.CacheDidUpdateCallback(
  param: CacheDidUpdateCallbackParam,
)

매개변수

반환 값

  • Promise<void>

CacheDidUpdateCallbackParam

속성

  • cacheName

    문자열

  • event

    ExtendableEvent

  • newResponse

    응답

  • oldResponse

    응답 선택사항

  • 요청

    요청

  • state

    MapLikeObject 선택사항

CachedResponseWillBeUsedCallback()

workbox-core.CachedResponseWillBeUsedCallback(
  param: CachedResponseWillBeUsedCallbackParam,
)

매개변수

반환 값

  • Promise<void | Response>

CachedResponseWillBeUsedCallbackParam

속성

  • cacheName

    문자열

  • cachedResponse

    응답 선택사항

  • event

    ExtendableEvent

  • matchOptions

    CacheQueryOptions 선택사항

  • 요청

    요청

  • state

    MapLikeObject 선택사항

CacheKeyWillBeUsedCallback()

workbox-core.CacheKeyWillBeUsedCallback(
  param: CacheKeyWillBeUsedCallbackParam,
)

매개변수

반환 값

  • Promise<string | Request>

CacheKeyWillBeUsedCallbackParam

속성

  • event

    ExtendableEvent

  • 모드

    문자열

  • params

    모든 선택사항

  • 요청

    요청

  • state

    MapLikeObject 선택사항

CacheWillUpdateCallback()

workbox-core.CacheWillUpdateCallback(
  param: CacheWillUpdateCallbackParam,
)

매개변수

반환 값

  • Promise<void | Response>

CacheWillUpdateCallbackParam

속성

  • event

    ExtendableEvent

  • 요청

    요청

  • 응답

    응답

  • state

    MapLikeObject 선택사항

FetchDidFailCallback()

workbox-core.FetchDidFailCallback(
  param: FetchDidFailCallbackParam,
)

매개변수

반환 값

  • Promise<void>

FetchDidFailCallbackParam

속성

  • error

    오류

  • event

    ExtendableEvent

  • originalRequest

    요청

  • 요청

    요청

  • state

    MapLikeObject 선택사항

FetchDidSucceedCallback()

workbox-core.FetchDidSucceedCallback(
  param: FetchDidSucceedCallbackParam,
)

매개변수

반환 값

  • 프로미스<응답>

FetchDidSucceedCallbackParam

속성

  • event

    ExtendableEvent

  • 요청

    요청

  • 응답

    응답

  • state

    MapLikeObject 선택사항

HandlerCallbackOptions

enum

RouteHandlerCallbackOptions

ManualHandlerCallbackOptions

HandlerDidCompleteCallback()

workbox-core.HandlerDidCompleteCallback(
  param: HandlerDidCompleteCallbackParam,
)

매개변수

반환 값

  • Promise<void>

HandlerDidCompleteCallbackParam

속성

  • error

    오류 선택사항

  • event

    ExtendableEvent

  • 요청

    요청

  • 응답

    응답 선택사항

  • state

    MapLikeObject 선택사항

HandlerDidErrorCallback()

workbox-core.HandlerDidErrorCallback(
  param: HandlerDidErrorCallbackParam,
)

매개변수

반환 값

  • 프로미스<응답>

HandlerDidErrorCallbackParam

속성

  • error

    오류

  • event

    ExtendableEvent

  • 요청

    요청

  • state

    MapLikeObject 선택사항

HandlerDidRespondCallback()

workbox-core.HandlerDidRespondCallback(
  param: HandlerDidRespondCallbackParam,
)

매개변수

반환 값

  • Promise<void>

HandlerDidRespondCallbackParam

속성

  • event

    ExtendableEvent

  • 요청

    요청

  • 응답

    응답 선택사항

  • state

    MapLikeObject 선택사항

HandlerWillRespondCallback()

workbox-core.HandlerWillRespondCallback(
  param: HandlerWillRespondCallbackParam,
)

매개변수

반환 값

  • 프로미스<응답>

HandlerWillRespondCallbackParam

속성

  • event

    ExtendableEvent

  • 요청

    요청

  • 응답

    응답

  • state

    MapLikeObject 선택사항

HandlerWillStartCallback()

workbox-core.HandlerWillStartCallback(
  param: HandlerWillStartCallbackParam,
)

매개변수

반환 값

  • Promise<void>

HandlerWillStartCallbackParam

속성

  • event

    ExtendableEvent

  • 요청

    요청

  • state

    MapLikeObject 선택사항

ManualHandlerCallback()

workbox-core.ManualHandlerCallback(
  options: ManualHandlerCallbackOptions,
)

Router가 RouteMatchCallback를 통해 URL/요청을 Route에 일치시킬 때마다 '핸들러' 콜백이 호출됩니다. 이 핸들러 콜백은 Response로 확인되는 Promise를 반환해야 합니다.

RouteMatchCallback에서 비어 있지 않은 배열이나 객체를 반환하면 이 핸들러의 options.params 인수로 전달됩니다.

매개변수

반환 값

  • 프로미스<응답>

ManualHandlerCallbackOptions

ManualHandlerCallback 함수에 전달되는 옵션입니다.

속성

  • event

    ExtendableEvent

  • 요청

    string | 요청

MapLikeObject

PluginState

지금은 일반 MapLikeObject을 사용하지만 향후 이를 확장하거나 제한할 수 있습니다.

유형

MapLikeObject

RequestWillFetchCallback()

workbox-core.RequestWillFetchCallback(
  param: RequestWillFetchCallbackParam,
)

매개변수

반환 값

  • 프로미스<요청>

RequestWillFetchCallbackParam

속성

  • event

    ExtendableEvent

  • 요청

    요청

  • state

    MapLikeObject 선택사항

RouteHandler

RouteHandlerCallback 또는 RouteHandlerObject입니다. 경로 핸들러를 허용하는 workbox-routing의 대부분의 API는 둘 중 하나를 사용합니다.

enum

RouteHandlerCallback

RouteHandlerObject

RouteHandlerCallback()

workbox-core.RouteHandlerCallback(
  options: RouteHandlerCallbackOptions,
)

Router가 RouteMatchCallback를 통해 URL/요청을 Route에 일치시킬 때마다 '핸들러' 콜백이 호출됩니다. 이 핸들러 콜백은 Response로 확인되는 Promise를 반환해야 합니다.

RouteMatchCallback에서 비어 있지 않은 배열이나 객체를 반환하면 이 핸들러의 options.params 인수로 전달됩니다.

매개변수

반환 값

  • 프로미스<응답>

RouteHandlerCallbackOptions

RouteHandlerCallback 함수에 전달되는 옵션입니다.

속성

  • event

    ExtendableEvent

  • params

    string[] | MapLikeObject 선택사항

  • 요청

    요청

  • url

    URL

RouteHandlerObject

RouteHandlerCallback 유형의 handle 메서드가 있는 객체

Route 객체는 RouteHandlerCallback 함수 또는 이 RouteHandler 객체를 사용하여 만들 수 있습니다. RouteHandler의 이점은 workbox-strategies 패키지와 마찬가지로 확장될 수 있다는 것입니다.

속성

RouteMatchCallback()

workbox-core.RouteMatchCallback(
  options: RouteMatchCallbackOptions,
)

'match' 콜백은 Route를 특정 URL 및 요청에 적용해야 하는지 결정하는 데 사용됩니다. 클라이언트의 가져오기 이벤트에 대한 응답으로 일치가 발생하면 event 객체도 제공됩니다. 그러나 일치 콜백은 가져오기 이벤트 외부에서 호출될 수 있으므로 일치 로직은 event 객체를 항상 사용할 수 있다고 가정해서는 안 됩니다. 일치 콜백이 진실 값을 반환하면 일치하는 경로의 RouteHandlerCallback가 즉시 호출됩니다. 반환된 값이 비어 있지 않은 배열 또는 객체인 경우 해당 값은 핸들러의 options.params 인수에 설정됩니다.

매개변수

반환 값

  • 모두

RouteMatchCallbackOptions

RouteMatchCallback 함수에 전달되는 옵션입니다.

속성

  • event

    ExtendableEvent

  • 요청

    요청

  • sameOrigin

    boolean

  • url

    URL

WorkboxPlugin

가져오기 및 캐시 작업을 위한 선택적 수명 주기 콜백 속성이 있는 객체입니다.

속성

WorkboxPluginCallbackParam

속성

속성

cacheNames

Workbox에서 사용하는 현재 캐시 이름과 접두사/접미사를 가져옵니다.

cacheNames.precache는 사전 캐시된 애셋에 사용되고 cacheNames.googleAnalytics는 workbox-google-analytics에서 analytics.js를 저장하는 데 사용되며 cacheNames.runtime는 그 외 모든 항목에 사용됩니다.

cacheNames.prefix를 사용하여 현재 접두사 값만 검색할 수 있습니다. cacheNames.suffix를 사용하여 현재 서픽스 값만 검색할 수 있습니다.

유형

객체

속성

  • googleAnalytics

    문자열

  • 사전 캐시

    문자열

  • 프리픽스

    문자열

  • 런타임

    문자열

  • suffix

    문자열

메서드

clientsClaim()

workbox-core.clientsClaim()

서비스 워커가 활성화되면 현재 사용 가능한 클라이언트의 클레임 일반적으로 skipWaiting()와 함께 사용됩니다.

copyResponse()

workbox-core.copyResponse(
  response: Response,
  modifier?: function,
)

개발자가 응답을 복사하고 headers, status, statusText 값 (생성자의 [ResponseInit]https://developer.mozilla.org/en-US/docs/Web/API/Response/Response#Syntax 객체를 통해 설정 가능한 값)을 수정할 수 있습니다. 이러한 값을 수정하려면 함수를 두 번째 인수로 전달합니다. 이 함수는 응답 속성 {headers, status, statusText}가 있는 단일 객체를 사용하여 호출됩니다. 이 함수의 반환 값은 새 Response의 ResponseInit로 사용됩니다. 값을 변경하려면 전달된 매개변수를 수정하여 반환하거나 완전히 새로운 객체를 반환합니다.

이 메서드는 CORS 사용 여부에 관계없이 의도적으로 동일 출처 응답으로 제한됩니다.

매개변수

  • 응답

    응답

  • 수정자

    함수 선택사항

    modifier 매개변수는 다음과 같습니다. 

    (responseInit: ResponseInit) => ResponseInit

    • responseInit

      ResponseInit

    • returns

      ResponseInit

반환 값

  • 프로미스<응답>

registerQuotaErrorCallback()

workbox-core.registerQuotaErrorCallback(
  callback: Function,
)

할당량 오류가 있는 경우 실행될 할당량 오류 콜백 집합에 함수를 추가합니다.

매개변수

  • callback

    함수

setCacheNameDetails()

workbox-core.setCacheNameDetails(
  details: PartialCacheNameDetails,
)

Workbox 패키지에서 사용하는 기본 캐시 이름을 수정합니다. 캐시 이름은 <prefix>-<Cache Name>-<suffix>로 생성됩니다.

매개변수

  • 세부정보

    PartialCacheNameDetails

skipWaiting()

workbox-core.skipWaiting()

이 메서드는 지원 중단되었으며 Workbox v7에서 삭제될 예정입니다.

self.skipWaiting() 호출은 동일하며, 대신 사용해야 합니다.