إنّ بيان تطبيق الويب هو ملف 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
المحدَّد في عنوان المستند.
![مثال على نافذة تطبيق ويب تقدّمي (PWA) مع سمة متصفّح_لون مخصّص](https://web.dev/static/articles/add-manifest/image/an-example-a-pwa-window-06989d8a3c54d.png?authuser=6&hl=ar)
theme_color
مخصّصة.
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، لا تُعرض سوى لقطات الشاشة التي تم ضبط
- بدايةً من الإصدار 109 من Chrome، يتم تجاهل لقطات الشاشة التي تم ضبط
form_factor
فيها على"wide"
على نظام التشغيل Android. وسيتم عرض لقطات الشاشة التي لا تتضمّنform_factor
بهدف التوافق مع الأنظمة القديمة.
يعرض Chrome على سطح المكتب لقطة شاشة واحدة على الأقل وثماني لقطات شاشة تستوفي هذه المعايير. ويتم تجاهل الإعلانات المتبقية.
يعرض Chrome على نظام التشغيل Android لقطة شاشة واحدة على الأقل وخمس لقطات شاشة على الأكثر تستوفي هذه المعايير. ويتم تجاهل الإعلانات المتبقية.
![لقطات شاشة لواجهة مستخدم أكثر تفصيلاً على الكمبيوتر المكتبي والأجهزة الجوّالة](https://web.dev/static/articles/add-manifest/image/screenshots-richer-insta-4ad995b153d76.jpeg?authuser=6&hl=ar)
إضافة بيان تطبيق الويب إلى صفحاتك
بعد إنشاء البيان، أضِف علامة <link>
إلى جميع صفحات تطبيق الويب التقدّمي. على سبيل المثال:
<link rel="manifest" href="/manifest.json">
اختبار البيان
للتحقّق من إعداد البيان بشكل صحيح، استخدِم لوحة البيان في لوحة التطبيق في "أدوات مطوري البرامج في Chrome".
![لوحة التطبيقات في Chrome Devtools بعد اختيار علامة تبويب البيان](https://web.dev/static/articles/add-manifest/image/the-application-panel-ch-36462ceb8c218.png?authuser=6&hl=ar)
توفِّر هذا اللوحة نسخة يمكن لشخص عادي قراءتها من العديد من خصائص البيان، وتتيح لك التحقّق من أنّه يتم تحميل جميع الصور بشكل صحيح.
شاشات البداية على الأجهزة الجوّالة
عند تشغيل تطبيقك لأول مرة على الجوّال، قد يستغرق المتصفح بعض الوقت ليبدأ عرض المحتوى في البداية. وبدلاً من عرض شاشة بيضاء قد تجعل المستخدم يعتقد أن التطبيق لا يعمل، يعرض المتصفح شاشة بداية حتى أول طلاء.
ينشئ Chrome شاشة البداية تلقائيًا من name
وbackground_color
وicons
المحدّدة في بيانك. للانتقال بسلاسة من شاشة البداية إلى التطبيق، يجب أن تعرض background_color
نفس لون صفحة التحميل.
ويختار Chrome الرمز الذي يتطابق إلى حدّ كبير مع درجة دقة الجهاز في شاشات البداية. يكفي توفير رمزين بحجم 192 بكسل و512 بكسل في معظم الحالات، ولكن يمكنك توفير رموز إضافية للحصول على تطابق أفضل.
محتوى إضافي للقراءة
للاطّلاع على معلومات عن الخصائص الأخرى التي يمكنك إضافتها إلى بيان تطبيق الويب، يمكنك مراجعة مستند بيان تطبيق الويب MDN.