إضافة بيان تطبيق ويب

François Beaufort

Pete LePage

Thomas Steiner

Alexey Rodionov

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

• اسم التطبيق
• الأيقونات التي يجب أن يستخدمها التطبيق
• عنوان URL الذي يجب فتحه عند تشغيل التطبيق

إنشاء ملف البيان

ويمكن أن يحتوي ملف البيان على أي اسم، ولكن يُسمى عادةً manifest.json ويتم عرضه من الجذر (دليل المستوى الأعلى لموقعك الإلكتروني). تقترح المواصفات أن تكون الإضافة .webmanifest، ولكن قد تحتاج إلى استخدام ملفات JSON لتسهيل قراءة البيانات.

يبدو البيان النموذجي على النحو التالي:

{
  "short_name": "Weather",
  "name": "Weather: Do I need an umbrella?",
  "icons": [
    {
      "src": "/images/icons-vector.svg",
      "type": "image/svg+xml",
      "sizes": "512x512"
    },
    {
      "src": "/images/icons-192.png",
      "type": "image/png",
      "sizes": "192x192"
    },
    {
      "src": "/images/icons-512.png",
      "type": "image/png",
      "sizes": "512x512"
    }
  ],
  "id": "/?source=pwa",
  "start_url": "/?source=pwa",
  "background_color": "#3367D6",
  "display": "standalone",
  "scope": "/",
  "theme_color": "#3367D6",
  "shortcuts": [
    {
      "name": "How's the weather today?",
      "short_name": "Today",
      "description": "View weather information for today",
      "url": "/today?source=pwa",
      "icons": [{ "src": "/images/today.png", "sizes": "192x192" }]
    },
    {
      "name": "How's the weather tomorrow?",
      "short_name": "Tomorrow",
      "description": "View weather information for tomorrow",
      "url": "/tomorrow?source=pwa",
      "icons": [{ "src": "/images/tomorrow.png", "sizes": "192x192" }]
    }
  ],
  "description": "Weather forecast information",
  "screenshots": [
    {
      "src": "/images/screenshot1.png",
      "type": "image/png",
      "sizes": "540x720",
      "form_factor": "narrow"
    },
    {
      "src": "/images/screenshot2.jpg",
      "type": "image/jpg",
      "sizes": "720x540",
      "form_factor": "wide"
    }
  ]
}

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

short_name وname

يجب تقديم سمة واحدة على الأقل من short_name أو name في البيان. في حال تقديم الاثنين معًا، يتم استخدام name عند تثبيت التطبيق، واستخدام short_name على الشاشة الرئيسية للمستخدم أو مشغّل التطبيقات أو في الأماكن الأخرى التي تكون فيها المساحة محدودة.

icons

عندما يثبّت المستخدِم تطبيق الويب التقدّمي (PWA)، يمكنك تحديد مجموعة من الرموز لاستخدامها في المتصفّح على الشاشة الرئيسية ومشغّل التطبيقات ومبدّل المهام وشاشة البداية وفي أماكن أخرى.

السمة icons هي مصفوفة من عناصر الصور. ويجب أن يتضمّن كل عنصر السمة src والسمة sizes وسمة type للصورة. لاستخدام الرموز التكيُّفية التي يُشار إليها أحيانًا باسم الرموز التكيُّفية على Android، أضِف "purpose": "any maskable" إلى السمة icon.

بالنسبة إلى Chromium، يجب تقديم رمز بحجم 192x192 بكسل ورمز 512x512 بكسل على الأقل. إذا تم توفير هذين الحجمين فقط للأيقونات، فسيقوم Chrome تلقائيًا بقياس الأيقونات لتلائم الجهاز. إذا كنت تفضّل تغيير حجم الرموز الخاصة بك، وضبطها للحصول على درجة مثالية للبكسل، يمكنك توفير رموز بزيادات تبلغ 48 بكسل مستقل الكثافة.

id

تتيح لك السمة id تحديد المعرّف المستخدَم لتطبيقك بشكل صريح. تؤدي إضافة السمة id إلى البيان إلى إزالة التبعية على start_url أو مكان البيان، كما تتيح إمكانية تعديلها في المستقبل. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة تحديد تطبيقات الويب التقدّمية (PWA) بشكل فريد باستخدام خاصية معرّف بيان تطبيق الويب.

start_url

يجب إدراج السمة start_url. فهو يخبر المتصفح بالمكان الذي يجب أن يبدأ فيه تطبيقك عند تشغيله، ويمنع التطبيق من البدء في أي صفحة كان المستخدم فيها عند إضافة تطبيقك إلى الشاشة الرئيسية.

يجب أن يوجّه start_url المستخدم إلى تطبيقك مباشرةً، وليس إلى الصفحة المقصودة للمنتج. فكر فيما سيرغب المستخدم في القيام به على الفور بعد فتح تطبيقك، ووضعه هناك.

background_color

يتم استخدام السمة background_color على شاشة البداية عند تشغيل التطبيق على الأجهزة الجوّالة للمرة الأولى.

display

يمكنك تخصيص واجهة مستخدم المتصفح التي تظهر عند تشغيل تطبيقك. على سبيل المثال، يمكنك إخفاء عناصر شريط العناوين وواجهة مستخدم المتصفّح. يمكن حتى إنشاء الألعاب في وضع ملء الشاشة. تستخدم السمة display إحدى القيم التالية:

الموقع	السلوك
fullscreen	يتم فتح تطبيق الويب بدون أي واجهة مستخدم في المتصفّح ويشغل كل مساحة العرض المتاحة.
standalone	يتم فتح تطبيق الويب ليظهر وكأنه تطبيق مستقل. ويعمل التطبيق في نافذته الخاصة بشكل منفصل عن المتصفّح، كما يخفي عناصر واجهة المستخدم العادية الخاصة بالمتصفّح، مثل شريط العناوين.
minimal-ui	يشبه هذا الوضع وضع standalone، ولكنّه يوفّر للمستخدم الحد الأدنى من مجموعة عناصر واجهة المستخدم للتحكم في التنقل، مثل زر الرجوع وإعادة التحميل.
browser	تجربة متصفّح عادية.

display_override

لاختيار طريقة عرض تطبيق الويب، يجب ضبط وضع "display" في ملف البيان على النحو الموضّح سابقًا. لا يلزم أن تتوافق المتصفحات مع جميع أوضاع العرض، لكنها مطلوبة لإتاحة السلسلة الاحتياطية المحدّدة حسب المواصفات ("fullscreen" ← "standalone" ← "minimal-ui" ← "browser"). وإذا لم تكن متوافقة مع وضع معيّن، تعود إلى وضع العرض التالي في السلسلة. في حالات نادرة، يمكن أن تسبب هذه العناصر الاحتياطية مشاكل. على سبيل المثال، لا يمكن للمطوّر طلب استخدام "minimal-ui" بدون فرض إعادة استخدام وضع عرض "browser" عندما لا يكون "minimal-ui" متاحًا. كما أن السلوك الحالي يجعل من المستحيل تقديم أوضاع عرض جديدة بطريقة متوافقة مع الأنظمة القديمة، لأنه ليس لها مكان في السلسلة الاحتياطية.

يمكنك ضبط التسلسل الاحتياطي باستخدام السمة display_override التي يأخذها المتصفّح في الاعتبار قبل السمة display. وتكون قيمتها سلسلة من السلاسل التي يتمّ أخذها في الاعتبار بالترتيب المذكور، ويتمّ تطبيق أول وضع عرض متوافق. وفي حال عدم توافق أي من هذه البيانات، يعود المتصفح إلى تقييم الحقل display. وإذا لم يتوفّر حقل display، يتجاهل المتصفّح display_override.

في ما يلي مثال على كيفية استخدام السمة display_override. تقع تفاصيل "window-control-overlay" خارج نطاق هذه الصفحة.

{
  "display_override": ["window-control-overlay", "minimal-ui"],
  "display": "standalone",
}

عند تحميل هذا التطبيق، يحاول المتصفح استخدام "window-control-overlay" أولاً. وإذا لم يكن الخيار متاحًا، يتم الرجوع إلى السمة "minimal-ui"، ثم إلى "standalone" من السمة display. وإذا لم يكن أي منها متاحًا، يعود المتصفح إلى السلسلة الاحتياطية القياسية.

scope

ويشكّل scope لتطبيقك مجموعة عناوين URL التي يعتبرها المتصفّح جزءًا من تطبيقك. ويتحكّم scope في بنية عنوان URL التي تتضمن جميع نقاط الدخول والخروج إلى التطبيق، ويستخدمها المتصفّح لتحديد وقت خروج المستخدم من التطبيق.

في ما يلي بعض الملاحظات الأخرى عن scope:

• في حال عدم تضمين scope في ملف البيان، سيتم ضبط القيمة التلقائية scope ضمن عنوان URL للبدء، ولكن مع إزالة اسم الملف وطلب البحث والجزء.
• يمكن أن تكون السمة scope مسارًا نسبيًا (../) أو أي مسار بمستوى أعلى (/) يسمح بزيادة تغطية عمليات التنقّل في تطبيق الويب.
• يجب أن يكون start_url في النطاق.
• يرتبط start_url بالمسار المحدّد في السمة scope.
• وستكون القيمة start_url التي تبدأ بـ / دائمًا جذر المصدر.

theme_color

يحدّد theme_color لون شريط الأدوات، ويمكن أن يظهر في معاينة التطبيق في مبدِّلات المهام. يجب أن يتطابق عنصر "theme_color" مع لون مظهر meta المحدَّد في عنوان المستند.

theme_color في الاستعلامات عن الوسائط

يمكنك تعديل theme_color في الاستعلام عن الوسائط باستخدام السمة media لعنصر لون المظهر meta. على سبيل المثال، يمكنك تحديد لون للوضع الفاتح ولون آخر للوضع الداكن بهذه الطريقة. ومع ذلك، لا يمكنك تحديد هذه التفضيلات في البيان. لمزيد من المعلومات، يُرجى الاطّلاع على مشكلة w3c/manifest#975 GitHub.

<meta name="theme-color" media="(prefers-color-scheme: light)" content="white">
<meta name="theme-color" media="(prefers-color-scheme: dark)"  content="black">

shortcuts

السمة shortcuts هي مصفوفة من كائنات اختصارات التطبيقات التي توفّر إمكانية الوصول السريع إلى المهام الرئيسية داخل تطبيقك. ويكون كل عضو عبارة عن قاموس يحتوي على name وurl على الأقل.

description

تصف السمة description الغرض من تطبيقك.

في Chrome، يبلغ الحد الأقصى لطول الوصف 300 حرف في جميع الأنظمة الأساسية. أما إذا كان الوصف أطول من ذلك، فسيقتطعه المتصفح بحرف حذف. في Android، يجب أن يستخدم الوصف أيضًا سبعة أسطر من النص كحد أقصى.

screenshots

السمة screenshots هي مصفوفة من عناصر الصور التي تمثل تطبيقك في سيناريوهات الاستخدام الشائعة. ويجب أن يتضمّن كل عنصر السمة src والسمة sizes وtype للصورة. وتُعدّ السمة form_factor اختيارية. يمكنك ضبط القيمة على "wide" للقطات الشاشة السارية على الشاشات الكبيرة فقط أو على "narrow" للقطات الشاشة الضيقة فقط.

في Chrome، يجب أن تستوفي الصورة المعايير التالية:

• يجب ألا يقل العرض والارتفاع عن 320 بكسل و3840 بكسل كحد أقصى.
• لا يمكن أن يكون الحدّ الأقصى للبُعد أكبر من 2.3 ضِعف طول الحدّ الأدنى.
• يجب أن تكون جميع لقطات الشاشة التي تتطابق مع شكل الجهاز المناسب بنسبة العرض إلى الارتفاع ذاتها.
  • بدايةً من الإصدار 109 من Chrome، لا تُعرض سوى لقطات الشاشة التي تم ضبط form_factor فيها على "wide" على الكمبيوتر المكتبي.
• بدايةً من الإصدار 109 من Chrome، يتم تجاهل لقطات الشاشة التي تم ضبط form_factor فيها على "wide" على نظام التشغيل Android. وسيتم عرض لقطات الشاشة التي لا تتضمّن form_factor بهدف التوافق مع الأنظمة القديمة.

يعرض Chrome على سطح المكتب لقطة شاشة واحدة على الأقل وثماني لقطات شاشة تستوفي هذه المعايير. ويتم تجاهل الإعلانات المتبقية.

يعرض Chrome على نظام التشغيل Android لقطة شاشة واحدة على الأقل وخمس لقطات شاشة على الأكثر تستوفي هذه المعايير. ويتم تجاهل الإعلانات المتبقية.

إضافة بيان تطبيق الويب إلى صفحاتك

بعد إنشاء البيان، أضِف علامة <link> إلى جميع صفحات تطبيق الويب التقدّمي. على سبيل المثال:

<link rel="manifest" href="/manifest.json">

اختبار البيان

للتحقّق من إعداد البيان بشكل صحيح، استخدِم لوحة البيان في لوحة التطبيق في "أدوات مطوري البرامج في Chrome".

توفِّر هذا اللوحة نسخة يمكن لشخص عادي قراءتها من العديد من خصائص البيان، وتتيح لك التحقّق من أنّه يتم تحميل جميع الصور بشكل صحيح.

شاشات البداية على الأجهزة الجوّالة

عند تشغيل تطبيقك لأول مرة على الجوّال، قد يستغرق المتصفح بعض الوقت ليبدأ عرض المحتوى في البداية. وبدلاً من عرض شاشة بيضاء قد تجعل المستخدم يعتقد أن التطبيق لا يعمل، يعرض المتصفح شاشة بداية حتى أول طلاء.

ينشئ Chrome شاشة البداية تلقائيًا من name وbackground_color وicons المحدّدة في بيانك. للانتقال بسلاسة من شاشة البداية إلى التطبيق، يجب أن تعرض background_color نفس لون صفحة التحميل.

ويختار Chrome الرمز الذي يتطابق إلى حدّ كبير مع درجة دقة الجهاز في شاشات البداية. يكفي توفير رمزين بحجم 192 بكسل و512 بكسل في معظم الحالات، ولكن يمكنك توفير رموز إضافية للحصول على تطابق أفضل.

محتوى إضافي للقراءة

للاطّلاع على معلومات عن الخصائص الأخرى التي يمكنك إضافتها إلى بيان تطبيق الويب، يمكنك مراجعة مستند بيان تطبيق الويب MDN.