فایل پیکربندی Service Worker

این صفحه ویژگی‌های فایل پیکربندی service worker را شرح می‌دهد.

تغییر پیکربندی

فایل پیکربندی JSON به نام ngsw-config.json مشخص می‌کند service worker مربوط به Angular کدام فایل‌ها و URLهای داده را cache کند و فایل‌ها و داده‌های cacheشده را چگونه به‌روزرسانی کند. Angular CLI این فایل پیکربندی را هنگام اجرای ng build پردازش می‌کند.

همه مسیرهای فایل باید با / آغاز شوند که متناظر با دایرکتوری deployment است — در پروژه‌های CLI معمولاً dist/<project-name>.

مگر آنکه خلاف آن ذکر شود، الگوها از قالب glob محدود\* زیر استفاده می‌کنند که در داخل به regex تبدیل می‌شود:

چند الگوی نمونه:

ویژگی‌های پیکربندی service worker

بخش‌های زیر هریک از ویژگی‌های فایل پیکربندی را شرح می‌دهند.

appData

این بخش اجازه می‌دهد هر داده‌ای را که این نسخه مشخص برنامه را توصیف می‌کند منتقل کنید. service به نام SwUpdate این داده‌ها را در اعلان‌های به‌روزرسانی قرار می‌دهد. بسیاری از برنامه‌ها از این بخش برای ارائه اطلاعات بیشتر در popupهای UI استفاده می‌کنند تا کاربران را از به‌روزرسانی موجود آگاه سازند.

index

فایلی را مشخص می‌کند که برای پاسخ‌گویی به درخواست‌های پیمایش به‌عنوان صفحه index ارائه می‌شود. این فایل معمولاً /index.html است.

assetGroups

Assetها منابعی هستند که جزئی از نسخه برنامه‌اند و همراه برنامه به‌روزرسانی می‌شوند. آن‌ها می‌توانند منابع بارگذاری‌شده از origin صفحه و نیز منابع شخص ثالث بارگذاری‌شده از CDNها و سایر URLهای خارجی را شامل شوند. از آنجا که ممکن است همه URLهای خارجی هنگام build مشخص نباشند، می‌توان آن‌ها را با الگوی URL تطبیق داد.

این فیلد آرایه‌ای از گروه‌های asset را در بر دارد؛ هریک مجموعه‌ای از منابع asset و سیاست cache شدن آن‌ها را تعریف می‌کنند.

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

نخستین گروه asset منطبق با منبع درخواستی، درخواست را مدیریت می‌کند.

توصیه می‌شود گروه‌های asset اختصاصی‌تر را بالاتر قرار دهید. برای نمونه، گروهی که با /foo.js مطابقت دارد باید پیش از گروه منطبق با *.js قرار بگیرد.

هر گروه asset هم مجموعه‌ای از منابع و هم سیاست حاکم بر آن‌ها را مشخص می‌کند. این سیاست زمان دریافت منابع و رفتار هنگام تشخیص تغییرات را تعیین می‌کند.

گروه‌های asset از interface زیر در TypeScript پیروی می‌کنند:

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

هر AssetGroup با ویژگی‌های زیر تعریف می‌شود.

name

وجود name الزامی است. این ویژگی گروه مشخصی از assetها را بین نسخه‌های پیکربندی شناسایی می‌کند.

installMode

ویژگی installMode نحوه cache اولیه این منابع را تعیین می‌کند. installMode می‌تواند یکی از دو مقدار زیر باشد:

مقدار پیش‌فرض prefetch است.

updateMode

برای منابع موجود در cache،‏ updateMode رفتار cache را هنگام یافتن نسخه جدید برنامه تعیین می‌کند. هر منبع گروه که نسبت به نسخه قبلی تغییر کرده باشد مطابق updateMode به‌روزرسانی می‌شود.

مقدار پیش‌فرض همان مقداری است که برای installMode تنظیم شده است.

resources

این بخش منابع قابل cache را در گروه‌های زیر شرح می‌دهد:

cacheQueryOptions

این گزینه‌ها برای تغییر رفتار تطبیق درخواست‌ها به‌کار می‌روند. آن‌ها به تابع Cache#match مرورگر منتقل می‌شوند. برای جزئیات MDN را ببینید. در حال حاضر فقط گزینه زیر پشتیبانی می‌شود:

dataGroups

برخلاف منابع asset، درخواست‌های داده همراه برنامه versionبندی نمی‌شوند. آن‌ها براساس سیاست‌های پیکربندی‌شده دستی cache می‌شوند که برای شرایطی مانند درخواست‌های API و سایر dependencyهای داده مناسب‌ترند.

این فیلد آرایه‌ای از گروه‌های داده را در بر دارد؛ هریک مجموعه‌ای از منابع داده و سیاست cache شدن آن‌ها را تعریف می‌کند.

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

نخستین گروه داده منطبق با منبع درخواستی، درخواست را مدیریت می‌کند.

توصیه می‌شود گروه‌های داده اختصاصی‌تر را بالاتر قرار دهید. برای نمونه، گروه منطبق با /api/foo.json باید پیش از گروه منطبق با /api/*.json قرار بگیرد.

گروه‌های داده از interface زیر در TypeScript پیروی می‌کنند:

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

هر DataGroup با ویژگی‌های زیر تعریف می‌شود.

name

مشابه assetGroups، هر گروه داده یک name دارد که آن را به‌صورت یکتا شناسایی می‌کند.

urls

فهرستی از الگوهای URL. URLهای منطبق با این الگوها براساس سیاست این گروه داده cache می‌شوند. فقط درخواست‌های بدون تغییر داده \(GET و HEAD\) cache می‌شوند.

• الگوهای glob منفی پشتیبانی نمی‌شوند
• ? به‌صورت literal تطبیق داده می‌شود؛ یعنی فقط با نویسه ? مطابقت دارد

version

گاهی قالب APIها به شکلی تغییر می‌کند که backward-compatible نیست. ممکن است نسخه جدید برنامه با قالب قدیمی API و در نتیجه با منابع cacheشده موجود از آن API سازگار نباشد.

version سازوکاری فراهم می‌کند تا نشان دهید منابع cacheشده به‌شکلی ناسازگار با نسخه‌های قبلی به‌روزرسانی شده‌اند و entryهای قدیمی cache — مربوط به نسخه‌های پیشین — باید کنار گذاشته شوند.

version فیلدی integer با مقدار پیش‌فرض 1 است.

cacheConfig

ویژگی‌های زیر سیاست cache شدن درخواست‌های منطبق را تعریف می‌کنند.

##### maxSize

حداکثر تعداد entryها یا responseها در cache.

##### maxAge

پارامتر maxAge مشخص می‌کند responseها چه مدتی می‌توانند در cache بمانند تا نامعتبر تلقی و حذف شوند. maxAge رشته‌ای برای مدت‌زمان است که از پسوندهای زیر استفاده می‌کند:

برای نمونه، رشته 3d12h محتوا را تا سه روز و نیم cache می‌کند.

##### timeout

این رشته مدت‌زمان، timeout شبکه را مشخص می‌کند. timeout شبکه مدتی است که service worker مربوط به Angular پیش از استفاده از response موجود در cache، در صورت پیکربندی برای این کار، منتظر پاسخ شبکه می‌ماند. timeout رشته‌ای برای مدت‌زمان با پسوندهای زیر است:

برای نمونه، رشته 5s30u به معنای timeout شبکه برابر پنج ثانیه و 30 میلی‌ثانیه است.

##### refreshAhead

این رشته مدت‌زمان مشخص می‌کند service worker مربوط به Angular چه مدتی پیش از انقضای منبع cacheشده، به‌صورت پیش‌دستانه برای refresh آن از شبکه تلاش کند. refreshAhead پیکربندی اختیاری‌ای است که تعیین می‌کند service worker چه مدتی پیش از انقضای response موجود در cache، درخواست refresh منبع از شبکه را آغاز کند.

برای نمونه، رشته 1h30m به معنای یک ساعت و 30 دقیقه پیش از زمان انقضا است.

##### strategy

service worker مربوط به Angular می‌تواند یکی از دو راهبرد cache را برای منابع داده به‌کار ببرد.

برای استفاده از آن، strategy را روی freshness و timeout را در cacheConfig روی 0u تنظیم کنید.

این کار در عمل مراحل زیر را انجام می‌دهد:

1. ابتدا دریافت از شبکه را امتحان می‌کند.
2. اگر درخواست شبکه بلافاصله، یعنی پس از timeout برابر 0 ms، کامل نشود، سن cache را نادیده می‌گیرد و از مقدار cacheشده استفاده می‌کند.
3. پس از کامل شدن درخواست شبکه، cache را برای درخواست‌های آینده به‌روزرسانی می‌کند.
4. اگر منبع در cache وجود نداشته باشد، در هر حال برای درخواست شبکه منتظر می‌ماند.

##### cacheOpaqueResponses

مشخص می‌کند service worker مربوط به Angular باید responseهای opaque را cache کند یا خیر.

اگر مشخص نشده باشد، مقدار پیش‌فرض به راهبرد پیکربندی‌شده گروه داده بستگی دارد:

cacheQueryOptions

برای جزئیات به assetGroups مراجعه کنید.

navigationUrls

این بخش اختیاری اجازه می‌دهد فهرستی سفارشی از URLهایی مشخص کنید که به فایل index هدایت می‌شوند.

مدیریت درخواست‌های پیمایش

ServiceWorker درخواست‌های پیمایشی را که با هیچ گروه asset یا data مطابقت ندارند، به فایل index مشخص‌شده هدایت می‌کند. یک درخواست در صورت داشتن شرایط زیر، درخواست پیمایش محسوب می‌شود:

• method آن GET باشد
• mode آن navigation باشد
• مطابق مقدار header به نام Accept،‏ response از نوع text/html را بپذیرد
• URL آن با معیارهای زیر مطابقت داشته باشد:
• آخرین بخش مسیر URL نباید پسوند فایل \(یعنی .\) داشته باشد
• URL نباید __ داشته باشد

تطبیق URL درخواست‌های پیمایش

هرچند این معیارهای پیش‌فرض در بیشتر موارد مناسب‌اند، گاهی پیکربندی قوانین متفاوت مطلوب است. برای نمونه، ممکن است بخواهید routeهای مشخصی را که جزئی از برنامه Angular نیستند نادیده بگیرید و به server منتقل کنید.

این فیلد آرایه‌ای از URLها و الگوهای URL شبیه glob را در بر دارد که هنگام اجرا تطبیق داده می‌شوند. این آرایه می‌تواند هم الگوهای منفی \(الگوهایی که با ! آغاز می‌شوند\) و هم الگوها و URLهای غیرمنفی داشته باشد.

فقط درخواست‌هایی که URL آن‌ها با یکی از URLها/الگوهای غیرمنفی و با هیچ‌یک از موارد منفی مطابقت داشته باشد، درخواست پیمایش محسوب می‌شوند. query مربوط به URL هنگام تطبیق نادیده گرفته می‌شود.

اگر این فیلد حذف شود، مقدار پیش‌فرض آن چنین است:

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

navigationRequestStrategy

این ویژگی اختیاری امکان پیکربندی نحوه مدیریت درخواست‌های پیمایش توسط service worker را فراهم می‌کند:

{
  "navigationRequestStrategy": "freshness"
}

applicationMaxAge

این ویژگی اختیاری امکان پیکربندی مدت cache شدن همه درخواست‌ها توسط service worker را فراهم می‌کند. در محدوده maxAge فایل‌ها از cache ارائه می‌شوند. پس از آن، همه درخواست‌ها، از جمله درخواست‌های asset و داده، فقط از شبکه ارائه خواهند شد.