يمكنك تخصيص عناصر التحكّم في النوافذ المركّبة في شريط عناوين تطبيق PWA.

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

Amanda Baker

Thomas Steiner

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

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

عناصر تراكب عناصر التحكّم في النوافذ

يتألف "تراكب عناصر التحكم في النوافذ" من أربع ميزات فرعية:

1. قيمة "window-controls-overlay" للحقل "display_override" في بيان تطبيق الويب.
2. متغيرات بيئة CSS titlebar-area-x وtitlebar-area-y وtitlebar-area-width وtitlebar-area-height.
3. يشير هذا المصطلح إلى توحيد خاصية CSS -webkit-app-region التي كانت مملوكة سابقًا لتكون السمة app-region، وذلك لتحديد المناطق القابلة للسحب في محتوى الويب.
4. آلية للبحث عن منطقة عناصر التحكم في النوافذ والتعامل معها عن طريق العنصر windowControlsOverlay في window.navigator.

ما المقصود بـ Window Controls Overlay

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

الوضع الحالي

كيفية استخدام واجهة برمجة التطبيقات Window Controls Overlay

جارٍ إضافة window-controls-overlay إلى بيان تطبيق الويب

يمكن لتطبيق الويب التقدّمي تفعيل عرض عناصر التحكّم في النوافذ المركّبة من خلال إضافة "window-controls-overlay" كعضو "display_override" الأساسي في بيان تطبيق الويب:

{
  "display_override": ["window-controls-overlay"]
}

لن يظهر تراكب عناصر التحكّم في النوافذ إلا عند استيفاء كل الشروط التالية:

1. لا يتم فتح التطبيق في المتصفح، ولكن في نافذة تطبيق ويب منفصلة (PWA).
2. يتضمّن البيان "display_override": ["window-controls-overlay"]. (يُسمح بقيم أخرى بعد ذلك).
3. يعمل تطبيق الويب التقدّمي (PWA) على نظام تشغيل متوافق مع أجهزة الكمبيوتر المكتبي.
4. يتطابق المصدر الحالي مع المصدر الذي تم تثبيت تطبيق الويب التقدّمي (PWA) له.

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

نقل المحتوى إلى شريط العناوين

الآن بعد أن كانت هناك مساحة في شريط العناوين، يمكنك نقل شيء ما هناك. في هذه المقالة، أنشأت تطبيق ويب تقدّمي للمحتوى المميّز في Wikimedia. قد تكون إحدى الميزات المفيدة لهذا التطبيق هي البحث عن الكلمات في عناوين المقالات. يظهر رمز HTML لميزة البحث على النحو التالي:

<div class="search">
  <img src="logo.svg" alt="Wikimedia logo." width="32" height="32" />
  <label>
    <input type="search" />
    Search for words in articles
  </label>
</div>

لنقل div إلى الأعلى إلى شريط العناوين، يجب استخدام بعض CSS:

.search {
  /* Make sure the `div` stays there, even when scrolling. */
  position: fixed;
  /**
   * Gradient, because why not. Endless opportunities.
   * The gradient ends in `#36c`, which happens to be the app's
   * `<meta name="theme-color" content="#36c">`.
   */
  background-image: linear-gradient(90deg, #36c, #131313, 33%, #36c);
  /* Use the environment variable for the left anchoring with a fallback. */
  left: env(titlebar-area-x, 0);
  /* Use the environment variable for the top anchoring with a fallback. */
  top: env(titlebar-area-y, 0);
  /* Use the environment variable for setting the width with a fallback. */
  width: env(titlebar-area-width, 100%);
  /* Use the environment variable for setting the height with a fallback. */
  height: env(titlebar-area-height, 33px);
}

يمكنك الاطّلاع على تأثير هذا الرمز في لقطة الشاشة أدناه. شريط العنوان مستجيب بالكامل. عند تغيير حجم نافذة PWA، يتفاعل شريط العناوين كما لو كان مؤلفًا من محتوى HTML عادي، وهو في الواقع محتوى غير متوفّر.

تحديد الأجزاء القابلة للسحب من شريط العناوين

بينما تشير لقطة الشاشة أعلاه إلى أنك انتهيت، إلا أنك لم تنته بعد. لم تعُد نافذة PWA قابلة للسحب (بصرف النظر عن مساحة صغيرة جدًا)، لأنّ أزرار عناصر التحكم في النافذة لا تتيح سحب المساحات، ويتكوّن الجزء المتبقي من شريط العناوين من تطبيق "بحث Google" المصغّر. يمكنك حلّ هذه المشكلة باستخدام سمة app-region في CSS مع قيمة drag. في الحالة الملموسة، لا بأس في جعل كل ما عدا العنصر input قابل للسحب.

/* The entire search `div` is draggable… */
.search {
  -webkit-app-region: drag;
  app-region: drag;
}

/* …except for the `input`. */
input {
  -webkit-app-region: no-drag;
  app-region: no-drag;
}

بعد استخدام خدمة مقارنة الأسعار (CSS) هذه، يمكن للمستخدم سحب نافذة التطبيق كالمعتاد من خلال سحب div أو img أو label. ويكون العنصر input فقط تفاعليًا، وبالتالي يمكن إدخال طلب البحث.

رصد الميزات

يمكن رصد ميزة "تراكب عناصر التحكم في النوافذ" عن طريق اختبار توفُّر windowControlsOverlay:

if ('windowControlsOverlay' in navigator) {
  // Window Controls Overlay is supported.
}

طلب البحث عن منطقة عناصر التحكم في النوافذ باستخدام windowControlsOverlay

توجد مشكلة واحدة في الكود حتى الآن: في بعض المنصات، تكون عناصر التحكم في النوافذ على اليمين، وعلى البعض الآخر على اليسار. وما يزيد الأمر سوءًا، سيتغير موضع قائمة Chrome "النقاط الثلاث" أيضًا، بناءً على النظام الأساسي. ويعني هذا أنّه يجب تعديل صورة الخلفية ذات التدرج الخطي بشكل ديناميكي للعرض من #131313←maroon أو maroon←#131313←maroon بحيث تتداخل مع لون خلفية maroon الخاص بشريط العنوان والذي يتم تحديده من خلال <meta name="theme-color" content="maroon">. ويمكن تحقيق ذلك من خلال إرسال طلب بحث إلى getTitlebarAreaRect() API في السمة navigator.windowControlsOverlay.

if ('windowControlsOverlay' in navigator) {
  const { x } = navigator.windowControlsOverlay.getTitlebarAreaRect();
  // Window controls are on the right (like on Windows).
  // Chrome menu is left of the window controls.
  // [ windowControlsOverlay___________________ […] [_] [■] [X] ]
  if (x === 0) {
    div.classList.add('search-controls-right');
  }
  // Window controls are on the left (like on macOS).
  // Chrome menu is right of the window controls overlay.
  // [ [X] [_] [■] ___________________windowControlsOverlay [⋮] ]
  else {
    div.classList.add('search-controls-left');
  }
} else {
  // When running in a non-supporting browser tab.
  div.classList.add('search-controls-right');
}

بدلاً من إضافة صورة الخلفية إلى قواعد CSS لفئة .search مباشرةً (كما في السابق)، يستخدم الرمز المعدّل الآن فئتَين يضبطهما الرمز البرمجي أعلاه بشكل ديناميكي.

/* For macOS: */
.search-controls-left {
  background-image: linear-gradient(90deg, #36c, 45%, #131313, 90%, #36c);
}

/* For Windows: */
.search-controls-right {
  background-image: linear-gradient(90deg, #36c, #131313, 33%, #36c);
}

تحديد ما إذا كان تراكب عناصر التحكم في النوافذ مرئيًا

لن يظهر تراكب عناصر التحكم في النوافذ في منطقة شريط العناوين في جميع الحالات. يُرجى العِلم أنّ هذه الميزة لن تكون متوفّرة بطبيعة الحال على المتصفحات التي لا تتيح استخدام ميزة "تراكب عناصر التحكم في النوافذ"، إلا أنّها لن تكون متاحة أيضًا عندما يتم تشغيل تطبيق الويب التقدّمي المعنيّ في علامة تبويب. لرصد هذا الموقف، يمكنك إجراء طلب بحث في السمة visible في windowControlsOverlay:

if (navigator.windowControlsOverlay.visible) {
  // The window controls overlay is visible in the title bar area.
}

بدلاً من ذلك، يمكنك أيضًا استخدام الاستعلام عن الوسائط display-mode بلغة JavaScript و/أو CSS:

// Create the query list.
const mediaQueryList = window.matchMedia('(display-mode: window-controls-overlay)');

// Define a callback function for the event listener.
function handleDisplayModeChange(mql) {
  // React on display mode changes.
}

// Run the display mode change handler once.
handleDisplayChange(mediaQueryList);

// Add the callback function as a listener to the query list.
mediaQueryList.addEventListener('change', handleDisplayModeChange);

@media (display-mode: window-controls-overlay) { 
  /* React on display mode changes. */ 
}

يتم إعلامك بالتغييرات الهندسية

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

يمكنك إشعارك بالتغييرات في الأشكال الهندسية من خلال الاشتراك في navigator.windowControlsOverlay.ongeometrychange أو من خلال إعداد أداة معالجة الحدث لحدث geometrychange. لن يتم تنشيط هذا الحدث إلا عندما يكون تراكب عناصر التحكم في النوافذ مرئيًا، أي عندما تكون قيمة navigator.windowControlsOverlay.visible هي true.

const debounce = (func, wait) => {
  let timeout;
  return function executedFunction(...args) {
    const later = () => {
      clearTimeout(timeout);
      func(...args);
    };
    clearTimeout(timeout);
    timeout = setTimeout(later, wait);
  };
};

if ('windowControlsOverlay' in navigator) {
  navigator.windowControlsOverlay.ongeometrychange = debounce((e) => {
    span.hidden = e.titlebarAreaRect.width < 800;
  }, 250);
}

بدلاً من تخصيص دالة إلى ongeometrychange، يمكنك أيضًا إضافة أداة معالجة الحدث إلى windowControlsOverlay كما هو موضّح أدناه. يمكنك القراءة عن الفرق بين الاثنين على MDN.

navigator.windowControlsOverlay.addEventListener(
  'geometrychange',
  debounce((e) => {
    span.hidden = e.titlebarAreaRect.width < 800;
  }, 250),
);

التوافق عند التشغيل في علامة تبويب وعلى متصفحات غير متوافقة

هناك حالتان محتملتان يجب أخذهما في الاعتبار:

• يشير ذلك المصطلح إلى الحالة التي يتم فيها تشغيل تطبيق في متصفّح يتوافق مع Window Controls Overlay، ولكن عند استخدام التطبيق في علامة تبويب متصفّح.
• يشير ذلك المصطلح إلى الحالة التي يتم فيها تشغيل تطبيق في متصفّح لا يتيح استخدام Window Controls Overlay.

في كلتا الحالتين، سيعرض HTML الذي تم إنشاؤه لتراكب عناصر التحكم في النوافذ مضمّنًا مثل محتوى HTML العادي، وستبدأ القيم الاحتياطية لمتغيرات env() في تحديد الموضع. في المتصفحات المتوافقة، يمكنك أيضًا اختيار عدم عرض رمز HTML المخصص لتراكب عناصر التحكم في النوافذ من خلال التحقّق من سمة visible للتراكب، وإذا كانت تعرض false، يتم إخفاء محتوى HTML هذا.

للتذكير، لن تراعي المتصفِّحات غير المتوافقة سمة بيان تطبيق الويب "display_override" على الإطلاق، أو لن تتعرّف على "window-controls-overlay"، وبالتالي ستستخدم القيمة التالية المحتمَلة وفقًا للسلسلة الاحتياطية، على سبيل المثال، "standalone".

اعتبارات واجهة المستخدم

على الرغم من أن ذلك قد يكون مغريًا، إلا أنه لا يوصى بإنشاء قائمة منسدلة كلاسيكية في منطقة " Window Controls Overlay" (تراكب عناصر التحكم في النوافذ). ويُعدّ ذلك مخالفًا لإرشادات التصميم على نظام التشغيل macOS، وهي منصة يتوقع المستخدمون أن تظهر عليها أشرطة القوائم (التي يوفّرها النظام وتلك المخصّصة) في أعلى الشاشة.

إذا كان تطبيقك يقدم تجربة ملء الشاشة، فكر جيدًا في ما إذا كان من المنطقي أن يكون جزء عناصر التحكم في النافذة جزءًا من عرض ملء الشاشة. من المحتمل أن تريد إعادة ترتيب تصميمك عند بدء حدث onfullscreenchange.

الخصائص الديموغرافية

لقد أنشأت عرضًا توضيحيًا يمكنك العمل عليه في متصفّحات مختلفة متوافقة وغير متوافقة وفي الحالة المُثبَّتة وغير المثبَّتة. عليك تثبيت التطبيق في تجربة Window Controls Overlay الفعلية. ويمكنك رؤية لقطتَي شاشة لما يمكن توقّعه في ما يلي. رمز المصدر للتطبيق متوفّر على Glitch.

ميزة البحث في تراكب عناصر التحكم في النوافذ تعمل بكامل طاقتها:

الاعتبارات الأمنية

لقد صمّم فريق Chromium واجهة برمجة التطبيقات Window Controls Overlay API ونفّذها باستخدام المبادئ الأساسية المحدّدة في التحكّم في الوصول إلى الميزات الفعّالة لمنصة الويب، بما في ذلك التحكّم في المستخدِم والشفافية وهندسة العمل.

الانتحال

فمنح المواقع الإلكترونية إمكانية التحكّم الجزئي في شريط العناوين يتيح للمطوّرين انتحال المحتوى بطريقة كانت في السابق منطقة موثوق بها يتحكّم فيها المتصفّح. حاليًا، في متصفحات Chromium، يشتمل الوضع المستقل على شريط عناوين يعرض عند التشغيل الأولي عنوان صفحة الويب على اليسار، وأصل الصفحة على اليمين (يليه زر "الإعدادات والمزيد" وعناصر التحكم في النوافذ). بعد بضع ثوانٍ، يختفي نص المصدر. وفي حال ضبط المتصفِّح على لغة اتجاهها من اليمين إلى اليسار (RTL)، سيتم قلب هذا التنسيق ليكون نص المصدر إلى اليسار. يؤدي ذلك إلى فتح تراكب عناصر التحكم في النافذة لانتحال صفة المصدر في حال عدم وجود مساحة متروكة كافية بين المصدر والحافة اليمنى للتراكب. على سبيل المثال، يمكن إلحاق الأصل "evil.ltd" بموقع إلكتروني موثوق به "google.com"، ما يدفع المستخدمين إلى الاعتقاد بأنّ المصدر موثوق. وتتمثل الخطة في الاحتفاظ بنص المصدر هذا حتى يعرف المستخدمون منشأ التطبيق ويضمن أنّه يطابق توقعاتهم. بالنسبة إلى المتصفِّحات التي تم ضبطها من خلال ميزة RTL، يجب توفير مساحة متروكة كافية على يسار نص المصدر لمنع المواقع الإلكترونية الضارّة من إلحاق مصدر غير آمن ذي مصدر موثوق به.

البصمات الرقمية

لا يشكّل تفعيل عناصر التحكم في النوافذ المركّبة والمناطق القابلة للسحب مخاوف كبيرة بشأن الخصوصية بخلاف رصد الميزات. ومع ذلك، بسبب اختلاف الأحجام وأماكن أزرار التحكم في النوافذ على أنظمة التشغيل، تعرض الطريقة navigator.windowControlsOverlay.getTitlebarAreaRect() العنصر DOMRect الذي تكشف مواضعه وأبعاده معلومات عن نظام التشغيل الذي يتم تشغيل المتصفح عليه. في الوقت الحالي، يمكن للمطوّرين اكتشاف نظام التشغيل من سلسلة وكيل المستخدم، ولكن بسبب مشاكل في البصمات الرقمية، نناقش مسألة تجميد سلسلة UA وتوحيد إصدارات نظام التشغيل. هناك جهد مستمر داخل منتدى المتصفّح لفهم معدّل تغيُّر حجم عناصر التحكّم في النوافذ على مختلف الأنظمة الأساسية، وذلك لأنّ الافتراض الحالي هو أنّ هذه العناصر مستقرة نوعًا ما على مستوى جميع إصدارات نظام التشغيل، وبالتالي لن تكون مفيدة لرصد الإصدارات الثانوية من نظام التشغيل. على الرغم من أنّ هذه المشكلة قد تكون مرتبطة ببصمة الإصبع، لا تنطبق إلا على تطبيقات الويب التقدّمية (PWA) المثبّتة التي تستخدم ميزة شريط العناوين المخصّص ولا تنطبق على الاستخدام العام للمتصفّح. بالإضافة إلى ذلك، لن تكون واجهة برمجة التطبيقات navigator.windowControlsOverlay متاحة لإطارات iframe المضمَّنة داخل تطبيق الويب التقدّمي (PWA).

التنقّل

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

إضافة ملاحظات

يريد فريق Chromium معرفة معلومات عن تجاربك في استخدام واجهة برمجة التطبيقات Window Controls Overlay API.

أخبرنا عن تصميم واجهة برمجة التطبيقات

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

الإبلاغ عن مشكلة في التنفيذ

هل عثرت على خطأ في تنفيذ Chromium؟ أم أنّ التنفيذ مختلف عن المواصفات؟ عليك الإبلاغ عن خطأ على new.crbug.com. واحرص على تضمين أكبر قدر ممكن من التفاصيل، وتعليمات بسيطة لإعادة الإنتاج، وإدخال UI>Browser>WebAppInstalls في مربّع المكونات. تعمل ميزة Glitch بشكل رائع لمشاركة عمليات إعادة الإنشاء بسرعة وسهولة.

إظهار الدعم لواجهة برمجة التطبيقات

هل تخطّط لاستخدام واجهة برمجة التطبيقات Window Controls Overlay API؟ يساعد الدعم المتاح للجميع فريق Chromium في تحديد أولويات الميزات ويعرض لمورّدي المتصفِّح الآخرين مدى أهمية دعمهم لها.

أرسِل تغريدة إلى @ChromiumDev مع تضمين الهاشتاغ #WindowControlsOverlay وأطلِعنا على مكان استخدامك لها وطريقة استخدامك لها.

روابط مفيدة

• الشرح
• مسودة المواصفات
• خطأ في Chromium
• إدخال حالة النظام الأساسي Chrome
• مراجعة TAG
• المستندات ذات الصلة في Microsoft Edge

شكر وتقدير

تم تنفيذ واجهة برمجة التطبيقات Window Controls Overlay وتحديدها عن طريق Amanda Baker من فريق Microsoft Edge. راجع هذه المقالة جو ميدلي وكينيث رودي كريستيانسن. صورة رئيسية من إعداد سيغموند على UnLaunch