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

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

يجب أن يشتمل كل تطبيق ويب تقدّمي (PWA) على بيان واحد لكل تطبيق، يكون عادةً مستضافًا في المجلد الجذر ومرتبطًا بجميع صفحات HTML التي يمكن تثبيت تطبيق الويب التقدّمي (PWA) منها. وهذه الإضافة الرسمية هي .webmanifest، لذا يمكنك تسمية ملف البيان باسم app.webmanifest.

إضافة بيان تطبيق ويب إلى تطبيق الويب التقدّمي (PWA)

لإنشاء بيان تطبيق ويب، عليك أولاً إنشاء ملف نصي يحتوي على كائن JSON يحتوي على حقل name على الأقل مع قيمة سلسلة:

app.webmanifest:

{
   "name": "My First Application"
}

ولكن إنشاء الملف ليس كافيًا، بل يحتاج المتصفّح إلى معرفة أنّه متوفّر أيضًا.

إضافة روابط تؤدي إلى ملف البيان

لإعلام المتصفّح ببيان تطبيق الويب، عليك ربطه بتطبيق الويب التقدّمي (PWA) باستخدام عنصر HTML <link> وضبط السمة rel على manifest في جميع صفحات HTML الخاصة بتطبيق الويب التقدّمي (PWA). يشبه هذا كيفية ربط ورقة أنماط CSS بمستند.

index.html:

<html lang="en">
  <title>This is my first PWA</title>
  <link rel="manifest" href="/app.webmanifest">

تصحيح أخطاء البيان

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

بالنسبة إلى متصفِّحات Chromium

في أدوات مطوري البرامج

  1. في اللوحة اليمنى، ضمن التطبيق، اختَر بيان.
  2. تحقَّق من حقول البيان كما يحلّلها المتصفّح.

بالنسبة إلى Firefox

  1. افتح أداة الفحص.
  2. انتقِل إلى علامة التبويب "التطبيق".
  3. حدد خيار البيان في اللوحة اليمنى.
  4. تحقَّق من حقول البيان كما يحلّلها المتصفّح.

تصميم تجربة استخدام تطبيقات الويب التقدّمية (PWA)

بعد ربط تطبيق الويب التقدّمي (PWA) بملف البيان الخاص به، حان الوقت لملء باقي الحقول لتحديد تجربة المستخدمين.

الحقول الأساسية

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

name
الاسم الكامل لتطبيق الويب التقدّمي (PWA) وسيظهر هذا التطبيق إلى جانب الرمز على الشاشة الرئيسية لنظام التشغيل أو مشغّل التطبيقات أو شريط الإرساء أو القائمة.
short_name
اختياري، وهو اسم أقصر لتطبيق الويب التقدّمي (PWA)، يتم استخدامه عندما لا تتوفّر مساحة كافية لعرض القيمة الكاملة للحقل name. ويجب ألا يزيد طوله عن 12 حرفًا للحدّ من احتمال اقتطاعه.
icons
مصفوفة من عناصر الرموز مع src وtype وsizes وحقول purpose اختيارية، وتصف الصور التي يجب أن تمثّل تطبيق الويب التقدّمي (PWA)
start_url
عنوان URL الذي يجب أن يحمّله تطبيق الويب التقدّمي (PWA) عندما يبدأ المستخدم تشغيله من الرمز المثبَّت. يُنصح باستخدام مسار مطلق، لذلك إذا كانت الصفحة الرئيسية لتطبيق الويب التقدّمي (PWA) هي جذر موقعك الإلكتروني، يمكنك ضبط هذا الخيار على "/". لفتحه عند بدء تشغيل التطبيق. في حال عدم تقديم عنوان URL للبدء، يمكن للمتصفّح استخدام عنوان URL الذي تم تثبيت تطبيق الويب التقدّمي (PWA) منه كبداية. ويمكن أن يكون رابطًا لموضع معيّن، مثل تفاصيل منتج ما بدلاً من الشاشة الرئيسية.
display
أحد fullscreen أو standalone أو minimal-ui أو browser يصف كيف يجب أن يرسم نظام التشغيل نافذة تطبيق الويب التقدّمي (PWA). يمكنك الاطّلاع على مزيد من المعلومات عن أوضاع العرض المختلفة في فصل تصميم التطبيقات. في معظم حالات الاستخدام، يتم تنفيذ السمة standalone.
id
سلسلة تُحدِّد تطبيق الويب التقدّمي هذا (PWA) بشكلٍ فريد مقارنةً بالتطبيقات الأخرى التي قد تتم استضافتها على المصدر نفسه. وفي حال ترك السياسة بدون ضبط، سيتم استخدام start_url كقيمة احتياطية. يُرجى العلم أنّه من خلال تغيير start_url في المستقبل (مثلاً عند تغيير قيمة سلسلة طلب بحث)، قد تفقد قدرة المتصفّح على اكتشاف أنّ تطبيق الويب التقدّمي (PWA) مثبّت حاليًا.

الرموز

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

إذا أردت اختيار حجم رمز واحد فقط، يجب أن يكون 512 × 512 بكسل. ومع ذلك، يُنصح بتقديم المزيد من الأحجام، بما في ذلك صور بحجم 192 × 192، و384 × 384، و1024 × 1024 بكسل أيضًا.

"icons": [
   {
      "src": "icons/512.png",
      "type": "image/png",
      "sizes": "512x512"
   },
   {
      "src": "icons/1024.png",
      "type": "image/png",
      "sizes": "1024x1024"
   }
]

في حال عدم تقديم رمز أو إذا لم تكن الرموز بالأحجام التي يُنصح بها، لن تجتاز معايير التثبيت على بعض الأنظمة الأساسية. وعلى الأنظمة الأساسية الأخرى، سيتم إنشاء الرمز تلقائيًا، مثلاً من لقطة شاشة لتطبيق الويب التقدّمي (PWA) أو باستخدام رمز عام.

الرموز القابلة للإخفاء

تعمل بعض أنظمة التشغيل، مثل Android، على تعديل الرموز لتلائم الأحجام والأشكال المختلفة. على سبيل المثال، في نظام Android 12، يمكن للشركات المصنّعة أو الإعدادات المختلفة تغيير شكل الرموز من الدوائر إلى المربعات إلى المربعات ذات الزوايا المستديرة. لإتاحة هذه الأنواع من الرموز التكيُّفية، يمكنك توفير رمز قابل للإخفاء باستخدام الحقل purpose.

لإجراء ذلك، قدِّم ملف صورة مربّعة يحتوي على رمزه الرئيسي ضِمن "المنطقة الآمنة"، وهو دائرة في وسط الرمز بنصف قطر 40 في المئة من عرض الرمز. (انظر الصورة أدناه). ستحجب الأجهزة التي تتيح الرموز القابلة للإخفاء الرمز حسب الحاجة.

المنطقة الآمنة الموضوع عليها علامة على شكل دائرة نصف قطرها 40 في المئة داخل الرمز المربع

في ما يلي مثال لرمز قابل للإخفاء معروض في عدد من الأشكال الشائعة الاستخدام:

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

يشير ذلك المصطلح إلى أيقونة غير مناسبة لرمز قابل للإخفاء.

يمكن جعل هذه الصورة قابلة للاستخدام مع إضافة المزيد من المساحة المتروكة.

الرمز ذو المساحة المتروكة مناسب للأقنعة.

يجب أن تكون الرموز القابلة للإخفاء بحجم 512 × 512 على الأقل. باستخدام التطبيق الذي تم إنشاؤه، يمكنك إضافته إلى مجموعتك على "icons" لتحسين تجربة الأجهزة المتوافقة:

"icons": [
   {
      "src": "/icons/512.png",
      "type": "image/png",
      "sizes": "512x512"
   },
   {
      "src": "/icons/1024.png",
      "type": "image/png",
      "sizes": "1024x1024"
   },
   {
      "src": "/icons/512-maskable.png",
      "type": "image/png",
      "sizes": "512x512",
      "purpose": "maskable"
   },
]

في معظم الحالات، إذا لم يكن الرمز القابل للإخفاء يظهر بشكل جيد، يمكنك تحسينه من خلال إضافة المزيد من المساحة المتروكة. Maskable.app هي أداة مجانية على الإنترنت لاختبار وإنشاء نسخة قابلة للإخفاء من رمزك.

أمّا مجموعة الحقول التالية التي يجب تضمينها، فهي الحقول التي ستحسّن تجربة المستخدم، على الرغم من أنّها ليست مطلوبة للتثبيت.

theme_color
اللون التلقائي للتطبيق، ويؤثر أحيانًا في كيفية عرض نظام التشغيل للموقع الإلكتروني (مثل لون النافذة وشريط العنوان على الكمبيوتر المكتبي أو لون شريط الحالة على الأجهزة الجوّالة). يمكن أن يلغي عنصر HTML theme-color <meta> هذا اللون.
background_color
لون العنصر النائب لعرضه في خلفية التطبيق قبل تحميل ورقة الأنماط الخاصة به. ويتجاهل متصفّح Safari على نظامي التشغيل iOS وiPadOS ومعظم المتصفحات المتوافقة مع أجهزة الكمبيوتر المكتبي هذا الحقل حاليًا.
scope
تغيّر هذه السياسة نطاق التنقّل في تطبيق الويب التقدّمي (PWA)، ما يسمح لك بتحديد ما يتم عرضه وما لا يتم عرضه في نافذة التطبيق المثبَّت. على سبيل المثال، في حال الربط بصفحة خارج النطاق، سيتم عرضها في متصفح داخل التطبيق بدلاً من نافذة تطبيق الويب التقدّمي (PWA). ومع ذلك، لن يؤدي ذلك إلى تغيير نطاق مشغّل الخدمات.

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

تطبيق الويب التقدّمي (PWA) نفسه المثبَّت على الكمبيوتر المكتبي بلون مظهر مختلف

عند تحديد الألوان في البيان، مثلاً ضمن theme_color وbackground_color، يجب استخدام ألوان CSS المحدّدة، مثل salmon أو orange، أو ألوان RGB مثل #FF5500، أو دوال الألوان بدون شفافية مثل rgb() أو hsl(). يُرجى الاطّلاع على فصل تصميم التطبيق للحصول على مزيد من المعلومات.

التجربة الآن

شاشات البداية

في بعض الأجهزة، يتم عرض صورة ثابتة أثناء تحميل تطبيق الويب التقدّمي (PWA) لتقديم ملاحظات فورية للمستخدم.

يستخدم Android القيم theme_color وbackground_color وicon لإنشاء شاشة البداية.

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

تطبيق ويب تقدّمي (PWA) على شاشة بداية Android يستخدم قيمًا مختلفة عن البيان

من ناحية أخرى، لا يستخدم Safari على نظامَي التشغيل iOS وiPadOS بيان تطبيق الويب لإنشاء شاشات البداية. بدلاً من ذلك، يتم استخدام صورة مرتبطة من عنصر <link> خاص مشابه لطريقة تعاملها مع الرموز. ويمكنك الاطّلاع على فصل التحسينات للحصول على المزيد من التفاصيل.

الحقول الموسّعة

تقدِّم المجموعة التالية من الحقول معلومات إضافية عن تطبيق الويب التقدّمي (PWA). وجميعها اختيارية.

lang
علامة لغة تحدد اللغة الأساسية لقيم البيان، مثل en للغة الإنجليزية، أو pt-BR للبرتغالية البرازيلية، أو in للهندية.
dir
الاتجاه المطلوب لعرض حقول البيان التي تتيح الاتجاهات (مثل name وshort_name وdescription). القيم الصالحة هي auto وltr (من اليسار إلى اليمين) وrtl (من اليمين إلى اليسار).
orientation
الاتجاه المطلوب للتطبيق عند تثبيته. يمكن أن تضبط اللعبة هذا الإعداد لطلب الاتجاه الأفقي فقط. يتم قبول قيم متعددة، ولكن إذا تم تضمينها، تكون عادةً portrait أو landscape بشكل صريح.

الحقول الترويجية

تتيح لك المجموعة الرابعة من الحقول تقديم معلومات ترويجية حول تطبيق الويب التقدّمي (PWA)، على سبيل المثال، في مسارات التثبيت والبيانات ونتائج البحث.

description
شرح لمهام تطبيق الويب التقدّمي (PWA)
screenshots
مصفوفة لعناصر لقطات الشاشة باستخدام src وtype وsizes (على غرار العنصر icons) بهدف عرض تطبيق الويب التقدّمي (PWA) ولا تُفرض أي قيود على الحجم.
categories
يجب استخدام مصفوفة فئات تطبيق الويب التقدّمي (PWA) كتلميحات للبيانات، وذلك بشكل اختياري من قائمة الفئات المعروفة. وتكون هذه القيم عادةً بأحرف لاتينية صغيرة.
iarc_rating_id
يجب أن يكون لديك رمز اعتماد الاتحاد الدولي لتقييم المحتوى حسب الفئات العمرية (PWA)، إذا كان لديك تطبيق. والغرض منها هو تحديد الفئات العمرية التي يناسبها تطبيق PWA الخاص بك.

يمكنك الاطّلاع على هذه الحقول الترويجية قيد التنفيذ اليوم. على سبيل المثال، إذا كان تطبيق الويب التقدّمي (PWA) قابلاً للتثبيت وقدّمت قيمًا للحقلَين "description" و"screenshots" على الأقل، ستتحول تجربة مربع حوار التثبيت من عملية "إضافة إلى الشاشة الرئيسية" بسيطة. شريط المعلومات، إلى مربّع حوار تثبيت أكثر تفصيلاً يشبه مربّع متجر التطبيقات

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

يمكنك الاطّلاع على هذه الحقول الترويجية بشكل عملي:

حقول الإمكانات

أخيرًا، يتوفّر عدد من الحقول المرتبطة بإمكانيات مختلفة يمكن لتطبيق الويب التقدّمي (PWA) استخدامها في المتصفّحات المتوافقة، مثل الحقول shortcuts وshare_target وdisplay_overrides كما نتناولها في فصل الإمكانات. وتتوفّر أيضًا حقول، مثل related_apps وprefer_related_apps (راجِع فصل الرصد لمزيد من المعلومات)، لربط تطبيق الويب التقدّمي (PWA) بالتطبيقات المثبّتة، وغالبًا ما يكون ذلك من متجر التطبيقات.

قد تظهر العديد من الحقول الجديدة في المستقبل بينما تضيف المتصفّحات المزيد من الإمكانات إلى تطبيقات الويب التقدّمية.

الموارد