روکش کنترل های پنجره نوار عنوان PWA خود را سفارشی کنید

از ناحیه نوار عنوان در کنار کنترل های پنجره استفاده کنید تا PWA خود را بیشتر شبیه یک برنامه کنید.

Amanda Baker

Thomas Steiner

اگر مقاله من را به خاطر بیاورید که PWA خود را بیشتر شبیه یک برنامه کنید ، ممکن است به یاد بیاورید که چگونه به شخصی سازی نوار عنوان برنامه خود به عنوان استراتژی برای ایجاد تجربه ای شبیه به برنامه اشاره کردم. در اینجا مثالی از نحوه نمایش برنامه پادکست macOS ارائه شده است.

نوار عنوان سفارشی باعث می شود که PWA شما بیشتر شبیه یک برنامه مخصوص پلتفرم باشد.

اکنون ممکن است وسوسه شوید که با گفتن اینکه پادکست یک برنامه macOS مخصوص پلتفرم است که در مرورگر اجرا نمی شود و بنابراین می تواند آنچه را که می خواهد بدون نیاز به اجرای قوانین مرورگر انجام دهد، مخالفت کنید. درست است، اما خبر خوب این است که ویژگی Window Controls Overlay، که موضوع همین مقاله است، به زودی به شما امکان می دهد رابط های کاربری مشابهی برای PWA خود ایجاد کنید.

کنترل های پنجره اجزای پوشش

Windows Controls Overlay از چهار ویژگی فرعی تشکیل شده است:

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 .

Windows Controls Overlay چیست

ناحیه نوار عنوان به فضای سمت چپ یا راست کنترل‌های پنجره (یعنی دکمه‌های کوچک کردن، حداکثر کردن، بستن و غیره) اشاره دارد و اغلب شامل عنوان برنامه است. Window Controls Overlay به برنامه های کاربردی وب مترقی (PWA) اجازه می دهد تا با تعویض نوار عنوان تمام عرض موجود با یک پوشش کوچک حاوی کنترل های پنجره، احساسی شبیه به برنامه ایجاد کنند. این به توسعه دهندگان اجازه می دهد تا محتوای سفارشی را در قسمتی که قبلاً قسمت نوار عنوان تحت کنترل مرورگر بود قرار دهند.

وضعیت فعلی

مرحله	وضعیت
1. توضیح دهنده ایجاد کنید	کامل
2. پیش نویس اولیه مشخصات را ایجاد کنید	کامل
3. جمع آوری بازخورد و تکرار در طراحی	در حال انجام است
4. آزمایش مبدا	کامل
5. راه اندازی کنید	کامل (در Chromium 104)

نحوه استفاده از Windows 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 برای آن نصب شده است مطابقت دارد.

نتیجه این یک ناحیه خالی نوار عنوان با کنترل های پنجره معمولی در سمت چپ یا راست است، بسته به سیستم عامل.

نوار عنوان خالی برای محتوای سفارشی آماده است.

انتقال محتوا به نوار عنوان

اکنون که فضایی در نوار عنوان وجود دارد، می توانید چیزی را به آنجا منتقل کنید. برای این مقاله، من یک PWA محتوای ویژه ویکی‌مدیا ساختم. یک ویژگی مفید برای این برنامه ممکن است جستجوی کلمات در عنوان مقاله باشد. 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 دیگر قابل کشیدن نیست (به غیر از یک منطقه بسیار کوچک)، زیرا دکمه های کنترل پنجره مناطق کشیدن نیستند و بقیه نوار عنوان از ویجت جستجو تشکیل شده است. با استفاده از ویژگی 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;
}

توجه: در حال حاضر، app-region استاندارد نشده است، بنابراین برنامه این است که تا زمانی که app-region استاندارد شود، از پیشوند -webkit-app-region استفاده شود. در حال حاضر، فقط -webkit-app-region در مرورگر پشتیبانی می شود.

با قرار دادن این CSS، کاربر می‌تواند پنجره برنامه را طبق معمول با کشیدن div ، img یا label بکشد. فقط عنصر input تعاملی است بنابراین عبارت جستجو را می توان وارد کرد.

تشخیص ویژگی

پشتیبانی از Windows Controls Overlay را می توان با آزمایش وجود windowControlsOverlay تشخیص داد:

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

پرس و جو از منطقه کنترل های پنجره با windowControlsOverlay

کد تا کنون یک مشکل دارد: در برخی از سیستم عامل ها کنترل های پنجره در سمت راست و در برخی دیگر در سمت چپ قرار دارند. بدتر از همه، منوی "سه نقطه" کروم نیز بر اساس پلتفرم، موقعیت خود را تغییر می دهد. این بدان معناست که تصویر پس‌زمینه گرادیان خطی باید به‌صورت پویا برای اجرا از #131313 → maroon مایل maroon ← #131313 → maroon تطبیق داده شود، به طوری که با رنگ پس‌زمینه maroon نوار عنوان که توسط <meta name="theme-color" content="maroon"> تعیین می‌شود، ترکیب شود. <meta name="theme-color" content="maroon"> . این را می توان با جستجو در API 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);
}

تعیین اینکه آیا پوشش کنترل‌های پنجره قابل مشاهده است یا خیر

پوشش کنترل های پنجره در هر شرایطی در ناحیه نوار عنوان قابل مشاهده نخواهد بود. در حالی که طبیعتاً در مرورگرهایی که از ویژگی Window Controls Overlay پشتیبانی نمی‌کنند وجود نخواهد داشت، زمانی که PWA مورد نظر در یک برگه اجرا می‌شود نیز وجود نخواهد داشت. برای تشخیص این وضعیت، می توانید ویژگی visible windowControlsOverlay را پرس و جو کنید:

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

توجه: نمایان بودن همپوشانی کنترل‌های پنجره را نباید با دید به مفهوم CSS هر محتوای HTML که در کنار همپوشانی کنترل‌های پنجره قرار می‌دهید، اشتباه گرفت. حتی اگر display: none در div قرار داده شده در همپوشانی کنترل‌های پنجره، ویژگی visible پوشش کنترل‌های پنجره همچنان true گزارش می‌شود.

از طرف دیگر، می توانید از پرس و جو رسانه display-mode در جاوا اسکریپت و/یا 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 باشد.

توجه: از آنجایی که این رویداد به طور مکرر فعال می شود (مقایسه با نحوه شلیک یک شنونده اسکرول)، من همیشه توصیه می کنم از یک تابع debounce استفاده کنید تا رویداد خیلی زیاد اجرا نشود.

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),
);

سازگاری هنگام اجرا در یک برگه و در مرورگرهای غیر پشتیبانی

دو مورد ممکن برای بررسی وجود دارد:

• موردی که یک برنامه در مرورگری اجرا می‌شود که از Windows Controls Overlay پشتیبانی می‌کند ، اما در آن برنامه در برگه مرورگر استفاده می‌شود.
• موردی که یک برنامه در مرورگری اجرا می‌شود که از پوشش کنترل‌های پنجره پشتیبانی نمی‌کند .

در هر دو مورد، به‌طور پیش‌فرض HTML ساخته‌شده برای همپوشانی کنترل‌های پنجره، مانند محتوای معمولی HTML درون خطی نمایش داده می‌شود و مقادیر بازگشتی متغیرهای env() برای موقعیت‌یابی وارد می‌شوند. در مرورگرهای پشتیبانی کننده، همچنین می توانید تصمیم بگیرید که HTML تعیین شده برای همپوشانی کنترل های پنجره را با بررسی ویژگی visible روکش نمایش داده نشود و اگر false گزارش شود، محتوای HTML را پنهان کنید.

کنترل های در نظر گرفته شده برای نوار عنوان را می توان به راحتی در بدنه در مرورگرهای قدیمی نشان داد.

به عنوان یادآوری، مرورگرهای غیر پشتیبانی یا اصلاً ویژگی مانیفست برنامه وب "display_override" را در نظر نمی گیرند یا "window-controls-overlay" را نمی شناسند و بنابراین از مقدار ممکن بعدی مطابق با زنجیره بازگشتی استفاده می کنند، برای مثال، "standalone" .

کنترل های در نظر گرفته شده برای نوار عنوان را می توان به راحتی در بدنه در مرورگرهای قدیمی نشان داد.

ملاحظات UI

در حالی که ممکن است وسوسه انگیز باشد، ایجاد یک منوی کشویی کلاسیک در ناحیه Window Controls Overlay توصیه نمی شود. انجام این کار، دستورالعمل‌های طراحی در macOS را نقض می‌کند، پلتفرمی که در آن کاربران انتظار دارند نوارهای منو (هم منوهای ارائه‌شده توسط سیستم و هم موارد سفارشی) در بالای صفحه نمایش داشته باشند.

توجه: داشتن یک API منوی برنامه مناسب، مشابه Menu موجود در برنامه‌های Electron.js، به‌عنوان crbug/1295253 ردیابی می‌شود.

اگر برنامه شما یک تجربه تمام صفحه ارائه می دهد، به دقت بررسی کنید که آیا منطقی است که پوشش کنترل های پنجره شما بخشی از نمای تمام صفحه باشد. به طور بالقوه ممکن است بخواهید زمانی که رویداد onfullscreenchange فعال می شود، چیدمان خود را دوباره تنظیم کنید.

نسخه ی نمایشی

من یک نسخه آزمایشی ایجاد کرده ام که می توانید با آن در مرورگرهای مختلف پشتیبانی کننده و غیر پشتیبانی کننده و در حالت نصب شده و غیر نصب شده بازی کنید. برای تجربه واقعی Windows Controls Overlay، باید برنامه را نصب کنید. در زیر می توانید دو اسکرین شات از آنچه را که باید انتظار داشته باشید را مشاهده کنید. کد منبع برنامه در Glitch موجود است.

برنامه آزمایشی برای آزمایش در دسترس است.

ویژگی جستجو در پوشش کنترل های پنجره کاملاً کاربردی است:

یک ویژگی جستجو با استفاده از همپوشانی کنترل‌های پنجره.

ملاحظات امنیتی

تیم Chromium با استفاده از اصول اصلی تعریف شده در کنترل دسترسی به ویژگی‌های قدرتمند پلتفرم وب ، از جمله کنترل کاربر، شفافیت و ارگونومی، Windows Controls Overlay API را طراحی و اجرا کرد.

جعل

دادن کنترل جزئی نوار عنوان به سایت‌ها، فضایی را برای توسعه‌دهندگان ایجاد می‌کند تا محتوا را در منطقه‌ای که قبلاً منطقه‌ای قابل اعتماد و تحت کنترل مرورگر بود، جعل کنند. در حال حاضر، در مرورگرهای Chromium، حالت مستقل شامل یک نوار عنوان است که در راه‌اندازی اولیه، عنوان صفحه وب را در سمت چپ، و مبدا صفحه را در سمت راست نمایش می‌دهد (به دنبال آن دکمه «تنظیمات و موارد دیگر» و کنترل‌های پنجره را دنبال می‌کند. . پس از چند ثانیه، متن اصلی ناپدید می شود. اگر مرورگر روی زبان راست به چپ (RTL) تنظیم شده باشد، این طرح به گونه‌ای برگردانده می‌شود که متن اصلی در سمت چپ باشد. در صورت عدم وجود بالشتک کافی بین مبدا و لبه سمت راست روکش، همپوشانی کنترل‌های پنجره باز می‌شود تا مبدا را جعل کند. به عنوان مثال، منبع "evil.ltd" را می توان به یک سایت قابل اعتماد "google.com" اضافه کرد، که باعث می شود کاربران باور کنند که منبع قابل اعتماد است. برنامه این است که این متن اصلی حفظ شود تا کاربران بدانند منشاء برنامه چیست و بتوانند اطمینان حاصل کنند که با انتظارات آنها مطابقت دارد. برای مرورگرهای پیکربندی شده RTL، باید به اندازه کافی بالشتک در سمت راست متن اصلی وجود داشته باشد تا از اضافه کردن منبع ناامن به منبع قابل اعتماد توسط یک وب سایت مخرب جلوگیری شود.

انگشت نگاری

فعال کردن همپوشانی کنترل‌های پنجره و مناطق قابل کشیدن، به جز تشخیص ویژگی، نگرانی‌های قابل‌توجهی را برای حفظ حریم خصوصی ایجاد نمی‌کند. با این حال، با توجه به اندازه ها و موقعیت های مختلف دکمه های کنترل پنجره در سیستم عامل، navigator. windowControlsOverlay. getTitlebarAreaRect() متد navigator. windowControlsOverlay. getTitlebarAreaRect() DOMRect را برمی گرداند که موقعیت و ابعاد آن اطلاعاتی را در مورد سیستم عاملی که مرورگر بر روی آن اجرا می شود نشان می دهد. در حال حاضر، توسعه‌دهندگان می‌توانند سیستم عامل را از رشته عامل کاربر کشف کنند، اما به دلیل نگرانی‌های مربوط به اثر انگشت، بحث در مورد مسدود کردن رشته UA و یکپارچه‌سازی نسخه‌های سیستم عامل وجود دارد. تلاش‌های مداومی در جامعه مرورگر وجود دارد تا بفهمیم که اندازه کنترل‌های پنجره چند بار روی پلتفرم‌ها تغییر می‌کند، زیرا فرض فعلی این است که این کنترل‌ها در نسخه‌های سیستم‌عامل نسبتاً پایدار هستند و بنابراین برای مشاهده نسخه‌های سیستم‌عامل کوچک مفید نیستند. اگرچه این یک مشکل بالقوه اثر انگشت است، اما فقط برای PWA های نصب شده که از ویژگی نوار عنوان سفارشی استفاده می کنند اعمال می شود و برای استفاده عمومی مرورگر اعمال نمی شود. علاوه بر این، navigator. windowControlsOverlay API برای iframe های تعبیه شده در یک PWA در دسترس نخواهد بود.

ناوبری

پیمایش به مبدأ متفاوت در یک PWA باعث می‌شود که به نوار عنوان مستقل عادی برگردد، حتی اگر معیارهای بالا را برآورده کند و با پوشش کنترل‌های پنجره راه‌اندازی شود. این برای قرار دادن نوار سیاهی است که در مسیریابی به مبدأ متفاوت ظاهر می شود. پس از بازگشت به مبدا اصلی، همپوشانی کنترل های پنجره دوباره استفاده خواهد شد.

هنگامی که کاربر به مبدأ دیگری هدایت می شود، یک نوار سیاه نشان داده می شود.

بازخورد

تیم Chromium می‌خواهد درباره تجربیات شما با Windows Controls Overlay API بشنود.

در مورد طراحی API به ما بگویید

آیا چیزی در مورد API وجود دارد که آنطور که انتظار داشتید کار نمی کند؟ یا آیا روش ها یا ویژگی هایی وجود دارد که برای اجرای ایده خود به آنها نیاز دارید؟ سوال یا نظری در مورد مدل امنیتی دارید؟ یک مشکل مشخصات را در مخزن GitHub مربوطه ثبت کنید یا افکار خود را به یک مشکل موجود اضافه کنید.

گزارش مشکل در اجرا

آیا با اجرای Chromium اشکالی پیدا کردید؟ یا اجرا با مشخصات متفاوت است؟ یک اشکال را در new.crbug.com ثبت کنید. اطمینان حاصل کنید که تا جایی که می توانید جزئیات، دستورالعمل های ساده برای بازتولید را وارد کنید و UI>Browser>WebAppInstalls در کادر Components وارد کنید. Glitch برای به اشتراک گذاری سریع و آسان تکرارها عالی عمل می کند.

پشتیبانی از API را نشان دهید

آیا قصد دارید از Windows Controls Overlay API استفاده کنید؟ پشتیبانی عمومی شما به تیم Chromium کمک می‌کند تا ویژگی‌ها را اولویت‌بندی کند و به سایر فروشندگان مرورگر نشان می‌دهد که چقدر حمایت از آنها ضروری است.

با هشتگ #WindowControlsOverlay یک توییت به ChromiumDev@ ارسال کنید و به ما اطلاع دهید کجا و چگونه از آن استفاده می‌کنید.

لینک های مفید

• توضیح دهنده
• پیش نویس مشخصات
• اشکال کروم
• ورودی وضعیت پلتفرم Chrome
• بررسی تگ
• اسناد مربوط به Microsoft Edge

قدردانی ها

Window Controls Overlay توسط آماندا بیکر از تیم Microsoft Edge پیاده سازی و مشخص شد. این مقاله توسط Joe Medley و Kenneth Rohde Christiansen بررسی شده است. تصویر قهرمان توسط زیگموند در Unsplash .