يمكنك تخصيص عناصر التحكّم في النوافذ المركّبة في شريط عناوين تطبيق 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.

ما المقصود بتراكب عناصر التحكم في النوافذ؟

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

الوضع الحالي

كيفية استخدام ميزة "تراكب عناصر التحكم في النوافذ"

جارٍ إضافة 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) له.

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

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

والآن بعد أن أصبح هناك مساحة في شريط العناوين، يمكنك نقل عنصر هناك. بالنسبة لهذه المقالة، في إنشاء تطبيق ويب تقدّمي (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 عادي، وهو في الواقع.

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

بينما تشير لقطة الشاشة أعلاه إلى أنك قد انتهيت، إلا أنك لم تنته بعد. نافذة تطبيق الويب التقدّمي هي لم تعد قابلة للسحب (بخلاف المنطقة الصغيرة جدًا)، نظرًا لأن أزرار عناصر التحكم في النافذة لا يتم سحبها ، أما باقي شريط العناوين فتتألف من تطبيق "بحث Google" المصغّر. حلّ هذه المشكلة باستخدام خاصية CSS app-region بقيمة 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() على الموقع الإلكتروني 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);
}

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

لن يظهر عنصر التحكّم المركّب في النوافذ على مساحة شريط العناوين في بعض الحالات. خلال هذه الفترة بطبيعة الحال في المتصفحات التي لا تدعم ميزة "تراكب عناصر التحكم في النوافذ"، ولن يتوفّر أيضًا عند تشغيل تطبيق الويب التقدّمي (PWA) المعني في علامة تبويب. لاكتشاف هذا الموقف، يمكنك طلب البحث عن السمة 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".

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

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

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

عرض توضيحي

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

تعمل ميزة البحث في تراكب عناصر التحكّم بالنافذة بشكل كامل:

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

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

الانتحال

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

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

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

التنقّل

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

ملاحظات

يرغب فريق Chromium في معرفة رأيك في واجهة برمجة التطبيقات Window Controls Overlay API.

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

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

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

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

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

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

يمكنك إرسال تغريدة إلى @ChromiumDev باستخدام #WindowControlsOverlay علامة التصنيف وإعلامنا بمكان وكيفية استخدامك له.

روابط مفيدة

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

شكر وتقدير

تم تنفيذ ميزة "تراكب عناصر التحكم في النوافذ" وتحديدها من قِبل أماندا بيكر من فريق Microsoft Edge. تمت مراجعة هذه المقالة بواسطة جو ميدلي و كينيث رود كريستيانسن صورة رئيسية بواسطة Sigmund على Un وتتوفر