تطبيقات الويب التقدمية

مكتبة Workbox

20 دقيقة الدرس 11 من 30

مقدمة إلى Workbox

Workbox هي مجموعة من المكتبات التي طورتها Google لتبسيط أنماط التوجيه والتخزين المؤقت الشائعة في Service Workers. توفر كود Service Worker جاهز للإنتاج يتعامل مع تعقيدات استراتيجيات التخزين المؤقت، والتخزين المؤقت المسبق، والوظائف دون اتصال.

لماذا نستخدم Workbox؟

إدارة Service Workers يدوياً قد تكون معقدة وعرضة للأخطاء. توفر Workbox:

استراتيجيات تخزين مؤقت جاهزة للحالات الشائعة
تخزين مؤقت تلقائي للأصول أثناء وقت البناء
نظام توجيه مرن للتعامل مع أنواع مختلفة من الطلبات
بنية إضافات لتوسيع الوظائف
إصدارات تطوير وإنتاج مع دعم التصحيح
التكامل مع أدوات البناء الشائعة (webpack، Gulp، npm scripts)

ملاحظة: Workbox لا يستبدل Service Workers—بل يجعل كتابتها أسهل. لا يزال لديك تحكم كامل في سلوك Service Worker الخاص بك.

تثبيت Workbox

هناك عدة طرق لاستخدام Workbox حسب إعداد مشروعك:

1. استخدام CDN (البدء السريع)

<!-- في ملف Service Worker الخاص بك -->
importScripts('https://storage.googleapis.com/workbox-cdn/releases/7.0.0/workbox-sw.js');

if (workbox) {
  console.log('تم تحميل Workbox بنجاح');

  // كود Workbox الخاص بك هنا
} else {
  console.log('فشل تحميل Workbox');
}

2. استخدام npm (موصى به للإنتاج)

npm install workbox-webpack-plugin --save-dev
# أو
npm install workbox-cli --save-dev
# أو
npm install workbox-build --save-dev

3. استخدام workbox-cli

# التثبيت بشكل عام
npm install workbox-cli --global

# إنشاء Service Worker
workbox wizard

# بناء Service Worker
workbox generateSW workbox-config.js

إعداد Workbox الأساسي

إليك Service Worker بسيط يستخدم Workbox من CDN:

// sw.js
importScripts('https://storage.googleapis.com/workbox-cdn/releases/7.0.0/workbox-sw.js');

// تفعيل وضع التصحيح أثناء التطوير
workbox.setConfig({ debug: true });

// التخزين المؤقت المسبق للملفات
workbox.precaching.precacheAndRoute([
  { url: '/', revision: 'v1' },
  { url: '/styles/main.css', revision: 'v1' },
  { url: '/scripts/app.js', revision: 'v1' }
]);

// تخزين الصور مؤقتاً باستراتيجية Cache First
workbox.routing.registerRoute(
  ({ request }) => request.destination === 'image',
  new workbox.strategies.CacheFirst({
    cacheName: 'images-cache',
    plugins: [
      new workbox.expiration.ExpirationPlugin({
        maxEntries: 50,
        maxAgeSeconds: 30 * 24 * 60 * 60 // 30 يوم
      })
    ]
  })
);

// تخزين CSS و JS مؤقتاً باستراتيجية Stale While Revalidate
workbox.routing.registerRoute(
  ({ request }) =>
    request.destination === 'style' ||
    request.destination === 'script',
  new workbox.strategies.StaleWhileRevalidate({
    cacheName: 'assets-cache'
  })
);

// تخزين خطوط Google مؤقتاً
workbox.routing.registerRoute(
  ({ url }) => url.origin === 'https://fonts.googleapis.com',
  new workbox.strategies.StaleWhileRevalidate({
    cacheName: 'google-fonts-stylesheets'
  })
);

workbox.routing.registerRoute(
  ({ url }) => url.origin === 'https://fonts.gstatic.com',
  new workbox.strategies.CacheFirst({
    cacheName: 'google-fonts-webfonts',
    plugins: [
      new workbox.expiration.ExpirationPlugin({
        maxEntries: 30,
        maxAgeSeconds: 60 * 60 * 24 * 365 // سنة واحدة
      })
    ]
  })
);

التخزين المؤقت المسبق في Workbox

التخزين المؤقت المسبق يقوم بتنزيل وتخزين الأصول مؤقتاً أثناء مرحلة تثبيت Service Worker، مما يضمن توفرها دون اتصال فوراً.

// التخزين المؤقت المسبق اليدوي مع hashes المراجعة
workbox.precaching.precacheAndRoute([
  { url: '/index.html', revision: 'abc123' },
  { url: '/styles.css', revision: 'def456' },
  { url: '/app.js', revision: 'ghi789' }
]);

// hash المراجعة يساعد Workbox على معرفة متى تغيرت الملفات
// ويحتاج إلى تحديثها في الذاكرة المؤقتة

نصيحة: في الإنتاج، استخدم أدوات البناء لإنشاء manifest التخزين المؤقت المسبق تلقائياً مع hashes المراجعة الصحيحة. المراجعات اليدوية عرضة للأخطاء وصعبة الصيانة.

توجيه Workbox

توجيه Workbox يتيح لك تحديد كيفية التعامل مع أنواع مختلفة من الطلبات:

// المطابقة حسب وجهة الطلب
workbox.routing.registerRoute(
  ({ request }) => request.destination === 'image',
  new workbox.strategies.CacheFirst()
);

// المطابقة حسب نمط URL (RegExp)
workbox.routing.registerRoute(
  /\.(?:png|jpg|jpeg|svg|gif)$/,
  new workbox.strategies.CacheFirst()
);

// المطابقة حسب دالة مخصصة
workbox.routing.registerRoute(
  ({ url, request }) => {
    return url.pathname.startsWith('/api/') &&
           request.method === 'GET';
  },
  new workbox.strategies.NetworkFirst()
);

// المطابقة حسب مصدر محدد
workbox.routing.registerRoute(
  ({ url }) => url.origin === 'https://api.example.com',
  new workbox.strategies.NetworkFirst({
    cacheName: 'api-cache',
    networkTimeoutSeconds: 3
  })
);

استراتيجيات التخزين المؤقت في Workbox

توفر Workbox خمس استراتيجيات تخزين مؤقت مدمجة:

1. Cache First (التخزين المؤقت أولاً مع العودة إلى الشبكة)

workbox.routing.registerRoute(
  ({ request }) => request.destination === 'image',
  new workbox.strategies.CacheFirst({
    cacheName: 'images',
    plugins: [
      new workbox.expiration.ExpirationPlugin({
        maxEntries: 60,
        maxAgeSeconds: 30 * 24 * 60 * 60
      })
    ]
  })
);

الأفضل لـ: الأصول التي لا تتغير كثيراً (الصور، الخطوط، مكتبات CSS)

2. Network First (الشبكة أولاً مع العودة إلى التخزين المؤقت)

workbox.routing.registerRoute(
  ({ url }) => url.pathname.startsWith('/api/'),
  new workbox.strategies.NetworkFirst({
    cacheName: 'api-cache',
    networkTimeoutSeconds: 5,
    plugins: [
      new workbox.expiration.ExpirationPlugin({
        maxEntries: 50
      })
    ]
  })
);

الأفضل لـ: طلبات API، المحتوى الديناميكي الذي يجب أن يكون طازجاً

3. Stale While Revalidate

workbox.routing.registerRoute(
  ({ request }) => request.destination === 'script',
  new workbox.strategies.StaleWhileRevalidate({
    cacheName: 'js-cache'
  })
);

الأفضل لـ: الأصول حيث لا بأس من عرض نسخة قديمة قليلاً (JS، CSS)

4. Network Only

workbox.routing.registerRoute(
  ({ url }) => url.pathname.startsWith('/admin/'),
  new workbox.strategies.NetworkOnly()
);

الأفضل لـ: الطلبات التي يجب أن تكون طازجة دائماً (لوحات الإدارة، البيانات الفورية)

5. Cache Only

workbox.routing.registerRoute(
  ({ url }) => url.pathname === '/offline.html',
  new workbox.strategies.CacheOnly()
);

الأفضل لـ: الأصول المخزنة مسبقاً التي لا يجب أن تصل إلى الشبكة أبداً

استخدام Workbox مع webpack

للمشاريع التي تستخدم webpack، يتكامل workbox-webpack-plugin بسلاسة:

// webpack.config.js
const WorkboxPlugin = require('workbox-webpack-plugin');

module.exports = {
  // ... إعداد webpack الأخرى
  plugins: [
    new WorkboxPlugin.GenerateSW({
      clientsClaim: true,
      skipWaiting: true,
      runtimeCaching: [
        {
          urlPattern: /\.(?:png|jpg|jpeg|svg)$/,
          handler: 'CacheFirst',
          options: {
            cacheName: 'images',
            expiration: {
              maxEntries: 60,
              maxAgeSeconds: 30 * 24 * 60 * 60
            }
          }
        }
      ]
    })
  ]
};

استخدام workbox-build في سكريبتات Node

لعمليات البناء المخصصة، توفر workbox-build وصولاً برمجياً:

// build-sw.js
const workboxBuild = require('workbox-build');

workboxBuild.generateSW({
  globDirectory: 'dist/',
  globPatterns: [
    '**/*.{html,js,css,png,jpg,json}'
  ],
  swDest: 'dist/sw.js',
  runtimeCaching: [
    {
      urlPattern: /^https:\/\/fonts\.googleapis\.com/,
      handler: 'StaleWhileRevalidate',
      options: {
        cacheName: 'google-fonts-stylesheets'
      }
    }
  ]
}).then(({ count, size }) => {
  console.log(`تم إنشاء Service Worker مع ${count} ملفات (${size} بايت)`);
});

# تشغيل سكريبت البناء
node build-sw.js

خيارات تكوين Workbox

workbox.setConfig({
  debug: true, // تفعيل سجل التصحيح
  modulePathPrefix: '/custom/path/' // مسار مخصص لوحدات Workbox
});

// تعيين بادئة اسم الذاكرة المؤقتة
workbox.core.setCacheNameDetails({
  prefix: 'my-app',
  suffix: 'v1',
  precache: 'precache',
  runtime: 'runtime'
});

// تخطي الانتظار والمطالبة بالعملاء
workbox.core.skipWaiting();
workbox.core.clientsClaim();

تمرين:

أنشئ Service Worker جديد باستخدام Workbox من CDN
قم بالتخزين المؤقت المسبق لملفات HTML و CSS و JS الرئيسية
أضف استراتيجية CacheFirst للصور مع انتهاء صلاحية 30 يوماً
أضف استراتيجية NetworkFirst لطلبات API مع مهلة 5 ثوانٍ
اختبر التخزين المؤقت الخاص بك بالانتقال إلى وضع عدم الاتصال وإعادة تحميل الصفحة
تحقق من Cache Storage في DevTools للتأكد من الأصول المخزنة مؤقتاً

تصحيح أخطاء Workbox

// تفعيل وضع التصحيح
workbox.setConfig({ debug: true });

// التحقق من المسارات المسجلة
console.log('المسارات المسجلة:', workbox.routing.routes);

// مراقبة عمليات الذاكرة المؤقتة
self.addEventListener('message', (event) => {
  if (event.data && event.data.type === 'CACHE_URLS') {
    caches.keys().then(cacheNames => {
      console.log('جميع الذاكرات المؤقتة:', cacheNames);
    });
  }
});

تحذير: اختبر دائماً تكوين Workbox الخاص بك بدقة. استراتيجيات التخزين المؤقت غير الصحيحة يمكن أن تؤدي إلى تقديم محتوى قديم إلى الأبد. استخدم الإصدارات واستراتيجيات إبطال الذاكرة المؤقتة بشكل مناسب.