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

ملف بيان تطبيق الويب

18 دقيقة الدرس 2 من 30

فهم ملف بيان تطبيق الويب

ملف بيان تطبيق الويب (Web App Manifest) هو ملف JSON يخبر المتصفح كيف يجب أن يتصرف تطبيق PWA الخاص بك عند تثبيته على جهاز المستخدم. إنه يتحكم في مظهر التطبيق وسلوكه ويوفر البيانات الوصفية التي تجعل تطبيق الويب الخاص بك يبدو وكأنه تطبيق أصلي.

إنشاء manifest.json

قم بإنشاء ملف باسم manifest.json في جذر مشروعك وربطه في HTML الخاص بك:

<!DOCTYPE html>
<html lang="ar" dir="rtl">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>تطبيق PWA الخاص بي</title>
    <link rel="manifest" href="/manifest.json">
</head>
<body>
    <h1>تطبيق ويب تقدمي</h1>
</body>
</html>

الخصائص الأساسية للبيان

إليك مثالاً كاملاً لملف manifest.json يحتوي على جميع الخصائص الأساسية:

{
  "name": "تطبيق الويب التقدمي الخاص بي",
  "short_name": "تطبيقي",
  "description": "تطبيق ويب تقدمي قوي",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#2196F3",
  "orientation": "portrait-primary",
  "icons": [
    {
      "src": "/icons/icon-72x72.png",
      "sizes": "72x72",
      "type": "image/png",
      "purpose": "maskable any"
    },
    {
      "src": "/icons/icon-96x96.png",
      "sizes": "96x96",
      "type": "image/png",
      "purpose": "maskable any"
    },
    {
      "src": "/icons/icon-128x128.png",
      "sizes": "128x128",
      "type": "image/png",
      "purpose": "maskable any"
    },
    {
      "src": "/icons/icon-144x144.png",
      "sizes": "144x144",
      "type": "image/png",
      "purpose": "maskable any"
    },
    {
      "src": "/icons/icon-152x152.png",
      "sizes": "152x152",
      "type": "image/png",
      "purpose": "maskable any"
    },
    {
      "src": "/icons/icon-192x192.png",
      "sizes": "192x192",
      "type": "image/png",
      "purpose": "maskable any"
    },
    {
      "src": "/icons/icon-384x384.png",
      "sizes": "384x384",
      "type": "image/png",
      "purpose": "maskable any"
    },
    {
      "src": "/icons/icon-512x512.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "maskable any"
    }
  ]
}

تفصيل الخصائص

name مقابل short_name:

name: اسم التطبيق الكامل المعروض أثناء التثبيت وفي مشغلات التطبيقات (يُنصح بـ 45 حرفًا كحد أقصى).

short_name: الاسم المختصر المعروض على الشاشة الرئيسية أسفل الأيقونة (يُنصح بـ 12 حرفًا كحد أقصى).

1. أوضاع العرض

تتحكم خاصية display في كيفية ظهور تطبيقك:

/* standalone - الأكثر شيوعًا لتطبيقات PWA */
"display": "standalone"
// يبدو كتطبيق أصلي، بدون واجهة متصفح

/* fullscreen - تجربة غامرة */
"display": "fullscreen"
// ملء الشاشة، إخفاء جميع واجهات المتصفح وشريط الحالة

/* minimal-ui - بعض عناصر التحكم في المتصفح */
"display": "minimal-ui"
// واجهة متصفح بسيطة (رجوع/تقدم/إعادة تحميل)

/* browser - تجربة المتصفح الافتراضية */
"display": "browser"
// يفتح في علامة تبويب متصفح عادية

أفضل ممارسة: استخدم "standalone" لمعظم تطبيقات PWA. يوفر أفضل توازن بين الشعور الأصلي وألفة المستخدم.

2. الألوان

تعزز الألوان تجربة التطبيق والعلامة التجارية:

{
  "theme_color": "#2196F3",
  // يؤثر على شريط أدوات المتصفح وشريط الحالة
  // يظهر في مبدل المهام على Android
  
  "background_color": "#ffffff"
  // خلفية شاشة البداية أثناء تحميل التطبيق
  // يجب أن يتطابق مع خلفية تطبيقك الفعلية
}

3. عنوان URL للبداية

يتحكم في مكان فتح التطبيق عند تشغيله:

{
  "start_url": "/"
  // الصفحة الرئيسية
  
  "start_url": "/dashboard"
  // صفحة محددة
  
  "start_url": "/?source=pwa"
  // مع معامل التتبع
}

4. الاتجاه

قفل اتجاه الشاشة لتجربة مستخدم أفضل:

{
  "orientation": "portrait-primary"
  // portrait-primary, portrait-secondary
  // landscape-primary, landscape-secondary
  // portrait, landscape, any (افتراضي)
}

متطلبات الأيقونات

الأيقونات ضرورية لمظهر التطبيق المثبت. تحتاج إلى أحجام متعددة:

أحجام الأيقونات الحرجة:

• 192x192: مطلوب - الشاشة الرئيسية لـ Chrome/Android
• 512x512: مطلوب - شاشات البداية ومتاجر التطبيقات
• 72x72 إلى 384x384: موصى به لأجهزة مختلفة

استخدم تنسيق PNG مع خلفيات شفافة. يدعم حقل purpose:
• "any" - أيقونة قياسية
• "maskable" - أيقونة قابلة للتكيف لـ Android (منطقة آمنة في المركز)
• "maskable any" - كلا الغرضين

خصائص البيان المتقدمة

{
  "scope": "/",
  // يحدد نطاق التنقل لـ PWA
  
  "categories": ["productivity", "utilities"],
  // فئات التطبيق لمتاجر التطبيقات
  
  "screenshots": [
    {
      "src": "/screenshots/desktop.png",
      "sizes": "1280x720",
      "type": "image/png",
      "form_factor": "wide"
    },
    {
      "src": "/screenshots/mobile.png",
      "sizes": "750x1334",
      "type": "image/png",
      "form_factor": "narrow"
    }
  ],
  // تُستخدم في متاجر التطبيقات ومطالبات التثبيت
  
  "shortcuts": [
    {
      "name": "رسالة جديدة",
      "short_name": "جديد",
      "description": "ابدأ رسالة جديدة",
      "url": "/messages/new",
      "icons": [{ "src": "/icons/new.png", "sizes": "192x192" }]
    },
    {
      "name": "صندوق الوارد",
      "short_name": "الوارد",
      "description": "عرض صندوق الوارد",
      "url": "/messages/inbox",
      "icons": [{ "src": "/icons/inbox.png", "sizes": "192x192" }]
    }
  ],
  // اختصارات التطبيق (قائمة النقر بزر الماوس الأيمن على سطح المكتب)
  
  "lang": "ar-SA",
  // اللغة الأساسية
  
  "dir": "rtl",
  // اتجاه النص: ltr, rtl, auto
  
  "prefer_related_applications": false,
  // تفضيل التطبيق الأصلي على PWA
  
  "related_applications": [
    {
      "platform": "play",
      "url": "https://play.google.com/store/apps/details?id=com.example.app",
      "id": "com.example.app"
    }
  ]
}

التحقق من صحة البيان الخاص بك

قائمة الاختبار:

1. أدوات مطور Chrome:
• افتح DevTools > Application > Manifest
• تحقق من عرض جميع الخصائص بشكل صحيح
• تحقق من تحميل الأيقونات بجميع الأحجام

2. تدقيق Lighthouse:
• قم بتشغيل تدقيق Lighthouse PWA
• يجب أن يجتاز فحوصات "قابل للتثبيت"

3. توافق المتصفح:
• اختبر البيان في Chrome و Edge و Safari
• تحقق من ظهور مطالبات التثبيت

4. جودة الأيقونة:
• استخدم صور مصدر عالية الدقة
• تأكد من أن الأيقونات القابلة للقناع لها منطقة آمنة
• اختبر على الأجهزة الفعلية

أخطاء البيان الشائعة

تجنب هذه الأخطاء:

❌ أحجام الأيقونات المطلوبة مفقودة (192x192، 512x512)
❌ نوع MIME غير صحيح في علامة <link> (استخدم application/manifest+json)
❌ بناء JSON غير صالح (فواصل زائدة، مفاتيح بدون علامات اقتباس)
❌ أيقونات بنسبة عرض إلى ارتفاع خاطئة أو دقة منخفضة
❌ start_url لا يتطابق مع بنية التطبيق الفعلية
❌ theme_color لا يتطابق مع تصميم التطبيق
❌ نسيان تقديم البيان باستخدام HTTPS

مثال عملي: إعداد كامل

<!-- index.html -->
<!DOCTYPE html>
<html lang="ar" dir="rtl">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>تطبيق إدارة المهام PWA</title>
    
    <!-- البيان -->
    <link rel="manifest" href="/manifest.json">
    
    <!-- لون السمة لواجهة المتصفح -->
    <meta name="theme-color" content="#2196F3">
    
    <!-- علامات meta الخاصة بـ Apple -->
    <meta name="apple-mobile-web-app-capable" content="yes">
    <meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">
    <meta name="apple-mobile-web-app-title" content="إدارة المهام">
    <link rel="apple-touch-icon" href="/icons/icon-192x192.png">
</head>
<body>
    <h1>إدارة المهام</h1>
    <button id="installBtn" style="display: none;">تثبيت التطبيق</button>
    
    <script>
        // معالجة مطالبة التثبيت
        let deferredPrompt;
        const installBtn = document.getElementById('installBtn');
        
        window.addEventListener('beforeinstallprompt', (e) => {
            e.preventDefault();
            deferredPrompt = e;
            installBtn.style.display = 'block';
        });
        
        installBtn.addEventListener('click', async () => {
            if (!deferredPrompt) return;
            
            deferredPrompt.prompt();
            const { outcome } = await deferredPrompt.userChoice;
            console.log(`استجابة المستخدم: ${outcome}`);
            
            deferredPrompt = null;
            installBtn.style.display = 'none';
        });
    </script>
</body>
</html>

الخطوات التالية: في الدرس التالي، سنتعمق في Service Workers - المحرك الذي يشغل الوظائف دون اتصال ويجعل PWA الخاص بك قويًا حقًا.