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

François Beaufort

Pete LePage

Thomas Steiner

Alexey Rodionov

دعم المتصفح

• 39
• 79
• x
• 17

المصدر

بيان تطبيق الويب هو ملف 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. تستخدم على الشاشة الرئيسية للمستخدم أو مشغّل التطبيقات أو الأماكن الأخرى التي تتوفر فيها مساحة محدودة.

ملاحظة: عادةً ما يكون هناك عنوان لكل نافذة تطبيق في أنظمة التشغيل. هذا النمط العنوان في عدة أسطح لتبديل النوافذ مثل alt+tab ووضع النظرة العامة وقائمة نافذة الرف. بالنسبة إلى تطبيقات الويب التقدّمية (PWA) التي تعمل في الوضع المستقل: يضيف Chromium السمة short_name (أو، إذا لم يكن ذلك متاحًا، name) إلى بداية <title> في مستند HTML لمنع الهجمات المتخفية حيث التطبيقات المستقلة التي قد تحاول الخلط بينها وبين نظام التشغيل مثلاً ومربعات الحوار. للمساعدة في الحفاظ على أمان تطبيقك، يُرجى عدم تكرار اسم التطبيق في <title> للوضع المستقل.

icons

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

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

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

ملاحظة: تتوافق المتصفحات المستندة إلى Chromium أيضًا مع رموز SVG التي يمكن تغيير حجمها عشوائيًا بدون أن تبدو متقطعة وتدعم ميزات متقدمة مثل الاستجابة إلى prefers-color-scheme. ومع ذلك، تظل هذه الرموز بحالتها التي كانت عليها وقت التثبيت، بدلاً من يتم تحديثها مباشرةً. لاستخدام رموز SVG بأمان، عليك دائمًا تحديد الرمز النقطي للمتصفّحات التي لا تتيح استخدام رموز SVG.

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، سيتم فتح الرابط وعرضه في نافذة تطبيق الويب التقدّمي الحالية. إذا أردت الرابط الذي سيتم فتحه في علامة تبويب المتصفِّح، وإضافة target="_blank" إلى العلامة <a>. مشغَّلة في أجهزة Android، يتم فتح الروابط التي تتضمن target="_blank" في علامة تبويب Chrome المخصَّصة.

ملاحظات أخرى حول scope:

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

theme_color

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

مثال على نافذة تطبيق ويب تقدّمي (PWA) مع سمة theme_color مخصّصة

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

دعم المتصفح

• 93
• 93
• 106
• 15

المصدر

يمكنك تعديل 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 ضعف طول الحدّ الأدنى. البعد.
• يجب أن تتطابق جميع لقطات الشاشة التي تتطابق مع شكل الجهاز المناسب نسبة العرض إلى الارتفاع:
  • من Chrome 109، سيتم فقط ضبط لقطات الشاشة التي تتضمّن form_factor على "wide" تظهر على أجهزة الكمبيوتر المكتبي
• بدءًا من الإصدار 109 من Chrome، يتم تغيير قيم لقطات الشاشة التي تم ضبط form_factor فيها على "wide" تم تجاهلها على Android. سيستمر عرض لقطات الشاشة التي لا تحتوي على السمة form_factor لـ التوافق مع الأنظمة القديمة.

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

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

واجهة مستخدم تثبيت أكثر ثراءً على أجهزة الكمبيوتر المكتبي والأجهزة الجوّالة

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

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

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

يتم تقديم طلب البيان بدون بيانات الاعتماد، حتى لو كانت على النطاق نفسه. إذا كان البيان يتطلب بيانات الاعتماد، يجب تضمين crossorigin="use-credentials" في علامة البيان.

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

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

يمكنك اختبار البيان في "أدوات مطوري البرامج".

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

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

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

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

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

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

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