PWA'nızın başlık çubuğunun pencere kontrolleri yer paylaşımını özelleştirin

PWA'nızın daha fazla uygulama gibi görünmesi için pencere denetimlerinin yanındaki başlık çubuğu alanını kullanın.

Amanda Baker

Thomas Steiner

PWA'nızı daha uygulama gibi hissettirme başlıklı makalemi hatırlıyorsanız daha uygulama benzeri bir deneyim oluşturmak için uygulamanızın başlık çubuğunu özelleştirme stratejisinden bahsettiğimi hatırlayabilirsiniz. Aşağıda, macOS Podcasts uygulamasında bu durumun nasıl görünebileceğine dair bir örnek verilmiştir.

Şimdi, Podcasts'in tarayıcıda çalışmayan, platforma özgü bir macOS uygulaması olduğunu ve bu nedenle tarayıcı kurallarına uymak zorunda kalmadan istediğini yapabileceğini söyleyerek itiraz etmek isteyebilirsiniz. Doğru, ancak bu makalenin konusu olan Pencere Kontrolleri Yerleşimi özelliği sayesinde yakında PWA'nız için benzer kullanıcı arayüzleri oluşturabileceksiniz.

Pencere denetimi yer paylaşımı bileşenleri

Pencere Denetimi Yer Paylaşımı dört alt özellikten oluşur:

1. Web uygulaması manifest'indeki "display_override" alanı için "window-controls-overlay" değeri.
2. titlebar-area-x, titlebar-area-y, titlebar-area-width ve titlebar-area-height CSS ortam değişkenleri.
3. Web içeriğinde sürüklenebilir bölgeleri tanımlamak için daha önce özel olan -webkit-app-region CSS mülkünün app-region mülkü olarak standartlaştırılması.
4. window.navigator sınıfının windowControlsOverlay üyesi aracılığıyla pencere denetimleri bölgesini sorgulamak ve bu bölgede çalışmak için kullanılan bir mekanizma.

Pencere denetimi yer paylaşımı nedir?

Başlık çubuğu alanı, pencere kontrollerinin (yani küçültme, büyütme, kapatma vb. düğmelerin) sol veya sağındaki alanı ifade eder ve genellikle uygulamanın başlığını içerir. Pencere denetimi yer paylaşımı, mevcut tam genişlikli başlık çubuğunu pencere denetimlerini içeren küçük bir yer paylaşımıyla değiştirerek progresif web uygulamalarının (PWAs) daha uygulama benzeri bir deneyim sunmasını sağlar. Bu sayede geliştiriciler, daha önce tarayıcı tarafından kontrol edilen başlık çubuğu alanına özel içerik yerleştirebilir.

Mevcut durum

Pencere denetimi yer paylaşımını kullanma

window-controls-overlay, web uygulaması manifest dosyasına ekleniyor

Bir progresif web uygulaması, web uygulaması manifest dosyasında birincil "display_override" üyesi olarak "window-controls-overlay" ekleyerek pencere kontrolleri yer paylaşımını etkinleştirebilir:

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

Pencere kontrolleri yer paylaşımı yalnızca aşağıdaki koşulların tümü karşılandığında görünür:

1. Uygulama tarayıcıda açılmaz, ayrı bir PWA penceresinde açılır.
2. Manifest "display_override": ["window-controls-overlay"] içeriyor. (Daha sonra diğer değerlere izin verilir.)
3. PWA, masaüstü işletim sisteminde çalışıyor.
4. Mevcut kaynak, PWA'nın yüklendiği kaynakla eşleşir.

Bunun sonucunda, işletim sistemine bağlı olarak sol veya sağ tarafta normal pencere kontrollerinin bulunduğu boş bir başlık çubuğu alanı oluşur.

İçeriği başlık çubuğuna taşıma

Başlık çubuğunda yer açtığınıza göre bir öğeyi buraya taşıyabilirsiniz. Bu makale için Wikimedia Öne Çıkan İçerik PWA'sı oluşturdum. Bu uygulama için faydalı bir özellik, makale başlıklarındaki kelimeleri aramak olabilir. Arama özelliğinin HTML'si şu şekilde görünür:

<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>

Bu div simgesini başlık çubuğuna taşımak için CSS'ye ihtiyaç vardır:

.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);
}

Bu kodun etkisini aşağıdaki ekran görüntüsünde görebilirsiniz. Başlık çubuğu tamamen duyarlı olmalıdır. PWA penceresini yeniden boyutlandırdığınızda başlık çubuğu, normal HTML içeriğinden oluşuyormuş gibi tepki verir.

Başlık çubuğunun hangi bölümlerinin sürüklenebileceğini belirleme

Yukarıdaki ekran görüntüsü işlemi tamamladığınızı gösteriyor olsa da henüz tamamlamış değilsiniz. Pencere denetimi düğmeleri artık sürükleme alanı olmadığından ve başlık çubuğunun geri kalanı arama widget'ından oluştuğundan, PWA penceresi artık çok küçük bir alan dışında sürüklenemez. drag değerine sahip app-region CSS mülkünü kullanarak bu sorunu düzeltin. Bu durumda, input öğesinden başka her şeyi sürüklenebilir hale getirebilirsiniz.

/* 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;
}

Bu CSS uygulandığında kullanıcı, div, img veya label'yi sürükleyerek uygulama penceresini her zamanki gibi sürükleyebilir. Arama sorgusunun girilebilmesi için yalnızca input öğesi etkileşimlidir.

Özellik algılama

Pencere denetimi yer paylaşımı desteği, windowControlsOverlay aşağıdakilerin varlığını test ederek algılanabilir:

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

windowControlsOverlay ile pencere denetimleri bölgesini sorgulamak

Kodda şu an için bir sorun var: Bazı platformlarda pencere kontrolleri sağda, bazılarında solda. Daha da kötüsü, "üç nokta" Chrome menüsü de platforma göre konumunu değiştirecek. Bu, çizgisel degrade arka plan resminin <meta name="theme-color" content="maroon"> tarafından belirlenen başlık çubuğunun maroon arka plan rengiyle uyumlu olması için #131313→maroon veya maroon→#131313→maroon şeklinde dinamik olarak uyarlanması gerektiği anlamına gelir. Bu işlem, navigator.windowControlsOverlay mülkünde getTitlebarAreaRect() API'yi sorgulamanızla yapılabilir.

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');
}

Değiştirilen kodda, arka plan resmi doğrudan .search sınıfı CSS kurallarında yer almak yerine (eskiden olduğu gibi) artık yukarıdaki kodun dinamik olarak ayarladığı iki sınıf kullanılmaktadır.

/* 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);
}

Pencere denetimi yer paylaşımının görünür olup olmadığını belirleme

Pencere denetimleri yer paylaşımı, her durumda başlık çubuğu alanında görünmez. Pencere Denetimleri Yerleşimi özelliğini desteklemeyen tarayıcılarda bu özellik doğal olarak bulunmaz. Söz konusu PWA bir sekmede çalışırken de bu özellik gösterilmez. Bu durumu tespit etmek için windowControlsOverlay mülkünün visible mülkünü sorgulayabilirsiniz:

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

Alternatif olarak, JavaScript ve/veya CSS'de display-mode medya sorgusunu da kullanabilirsiniz:

// 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. */ 
}

Geometri değişiklikleri hakkında bildirim alma

Pencere denetimleri yer paylaşımı alanını getTitlebarAreaRect() ile sorgulamak, pencere denetimlerinin bulunduğu yere göre doğru arka plan resmini ayarlama gibi tek seferlik işlemler için yeterli olabilir ancak diğer durumlarda daha ayrıntılı kontrol gerekir. Örneğin, pencere denetimi yer paylaşımını mevcut alana göre uyarlamak ve yeterli alan olduğunda pencere denetimi yer paylaşımına bir şaka eklemek olası bir kullanım alanı olabilir.

navigator.windowControlsOverlay.ongeometrychange kaynağına abone olarak veya geometrychange etkinliği için bir etkinlik dinleyicisi ayarlayarak geometri değişiklikleri hakkında bildirim alabilirsiniz. Bu etkinlik yalnızca pencere kontrolleri yer paylaşımı görünür olduğunda, yani navigator.windowControlsOverlay.visible true olduğunda tetiklenir.

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'e bir işlev atamak yerine, aşağıdaki gibi windowControlsOverlay'e bir etkinlik dinleyicisi de ekleyebilirsiniz. İkisi arasındaki fark hakkında bilgi edinmek için MDN'yi ziyaret edebilirsiniz.

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

Sekmede ve desteklemeyen tarayıcılarda çalıştırırken uyumluluk

Dikkate alınması gereken iki olası durum vardır:

• Bir uygulamanın, Window Controls Overlay'ı destekleyen bir tarayıcıda çalıştığı ancak uygulamanın tarayıcı sekmesinde kullanıldığı durum.
• Bir uygulamanın, Pencere Denetimleri Yer Paylaşımı'nı desteklemeyen bir tarayıcıda çalıştığı durum.

Her iki durumda da, pencere kontrolleri yer paylaşımı için oluşturulan HTML varsayılan olarak normal HTML içeriği gibi satır içi olarak gösterilir ve env() değişkenlerinin yedek değerleri konumlandırma için etkinleştirilir. Desteklenen tarayıcılarda, pencere kontrolleri yer paylaşımı için belirlenen HTML'yi göstermemeye de karar verebilirsiniz. Bunun için yer paylaşımının visible mülkünü kontrol edin. false değerini döndürüyorsa HTML içeriğini gizleyin.

Desteklemedikleri tarayıcılar "display_override" web uygulaması manifest mülkünü hiç dikkate almaz veya "window-controls-overlay" değerini tanımaz. Bu nedenle, yedek zincire göre olası bir sonraki değeri (ör. "standalone") kullanır.

Kullanıcı arayüzüyle ilgili dikkat edilmesi gereken noktalar

Cazip olsa da Pencere Denetimleri Yer paylaşımı alanında klasik bir açılır menü oluşturmanız önerilmez. Bu, kullanıcıların ekranın üst kısmında menü çubukları (hem sistem tarafından sağlanan hem de özel olanlar) beklediği bir platform olan macOS'teki tasarım yönergelerini ihlal eder.

Uygulamanız tam ekran deneyimi sunuyorsa Pencere Denetimleri yer paylaşımınızın tam ekran görünümünün bir parçası olmasının mantıklı olup olmadığını dikkatlice değerlendirin. onfullscreenchange etkinliği tetiklendiğinde düzeninizi yeniden düzenlemek isteyebilirsiniz.

Demo

Farklı destekleyen ve desteklemeyen tarayıcılarda, ayrıca yüklü ve yüklü olmayan durumda oynayabileceğiniz bir demo oluşturdum. Gerçek Pencere Denetimleri Yerleşimi deneyimi için uygulamayı yüklemeniz gerekir. Aşağıda, neyle karşılaşacağınıza dair iki ekran görüntüsü görebilirsiniz. Uygulamanın kaynak kodu Glitch'te mevcuttur.

Pencere denetimleri yer paylaşımındaki arama özelliği tam olarak çalışır:

Güvenlikle ilgili olarak göz önünde bulundurulması gerekenler

Chromium ekibi, Window Controls Overlay API'yi tasarlarken ve uygularken kullanıcı denetimi, şeffaflık ve ergonomi gibi Güçlü Web Platformu Özelliklerine Erişimi Kontrol Etme başlıklı makalede tanımlanan temel ilkeleri kullandı.

Adres sahteciliği

Sitelere başlık çubuğu üzerinde kısmi kontrol verilmesi, geliştiricilerin daha önce güvenilir ve tarayıcı kontrollü bir bölgedeki içeriği taklit etmesine olanak tanır. Şu anda Chromium tarayıcılarında bağımsız mod, ilk başlatıldığında solda web sayfasının başlığını, sağda ise sayfanın kaynağını gösteren bir başlık çubuğu içerir (ardından "ayarlar ve daha fazlası" düğmesi ve pencere kontrolleri gelir). Orijinal metin birkaç saniye sonra kaybolur. Tarayıcı sağdan sola (RTL) bir dile ayarlanmışsa bu düzen, kaynak metin solda olacak şekilde ters çevrilir. Bu işlem, kaynak ile yer paylaşımının sağ kenarı arasında yeterli dolgu yoksa kaynağı taklit etmek için pencere denetimleri yer paylaşımını açar. Örneğin, "evil.ltd" kaynağı, güvenilir bir site olan "google.com" ile eklenebilir. Bu da kullanıcıların kaynağın güvenilir olduğuna inanmasına neden olur. Kullanıcıların uygulamanın kaynağını bilmesini ve beklentilerini karşıladığından emin olmasını sağlamak için bu kaynak metninin korunması planlanmaktadır. RTL yapılandırılmış tarayıcılarda, kötü amaçlı bir web sitesinin güvenli olmayan kaynağı güvenilir bir kaynağa eklemesini önlemek için kaynak metninin sağında yeterli dolgu olmalıdır.

Dijital parmak izi

Pencere denetimi yer paylaşımını ve sürüklenebilir bölgeleri etkinleştirmek, özellik algılama dışında önemli gizlilik sorunları oluşturmaz. Ancak pencere kontrol düğmelerinin işletim sistemleri arasında farklı boyut ve konumlara sahip olması nedeniyle navigator.windowControlsOverlay.getTitlebarAreaRect() yöntemi, konumu ve boyutları tarayıcının çalıştığı işletim sistemi hakkında bilgi veren bir DOMRect döndürür. Şu anda geliştiriciler kullanıcı aracısı dizesinden işletim sistemini keşfedebiliyor olsa da parmak izi alma endişeleri nedeniyle UA dizesinin dondurulması ve işletim sistemi sürümlerinin birleştirilmesi hakkında tartışmalar var. Tarayıcı topluluğu, pencere kontrollerinin yer paylaşımı boyutunun platformlar arasında ne sıklıkta değiştiğini anlamak için sürekli olarak çalışmalar yürütmektedir. Şu anda bu boyutların işletim sistemi sürümleri arasında oldukça kararlı olduğu ve bu nedenle küçük işletim sistemi sürümlerini gözlemlemek için yararlı olmayacağı varsayılmaktadır. Bu, parmak izi oluşturma sorununa yol açabilecek bir durum olsa da yalnızca özel başlık çubuğu özelliğini kullanan yüklü PWA'lar için geçerlidir ve genel tarayıcı kullanımı için geçerli değildir. Ayrıca, navigator.windowControlsOverlay API, PWA'lara yerleştirilmiş iframe'ler tarafından kullanılamayacak.

Gezinme

Bir PWA'da farklı bir kaynağa gitmek, yukarıdaki ölçütleri karşılıyor ve pencere denetimleri yer paylaşımıyla başlatılıyor olsa bile uygulamanın normal bağımsız başlık çubuğuna geri dönmesine neden olur. Bu, farklı bir kaynağa giderken görünen siyah çubuğu barındırmak içindir. Orijinal kaynağa geri döndükten sonra pencere kontrolleri yer paylaşımı tekrar kullanılır.

Geri bildirim

Chromium ekibi, Pencere Denetimleri Yerleşimi API'si ile ilgili deneyimlerinizi öğrenmek istiyor.

API tasarımı hakkında bilgi verin

API ile ilgili olarak beklediğiniz gibi çalışmayan bir şey var mı? Yoksa fikrinizi uygulamak için ihtiyaç duyduğunuz yöntemler veya özellikler eksik mi? Güvenlik modeliyle ilgili sorunuz veya yorumunuz mu var? İlgili GitHub deposunda spesifikasyon sorunu oluşturun veya mevcut bir soruna düşüncelerinizi ekleyin.

Uygulamayla ilgili sorunları bildirme

Chromium'un uygulamasında bir hata mı buldunuz? Yoksa uygulama, spesifikasyondan farklı mı? new.crbug.com adresinden hata kaydı oluşturun. Mümkün olduğunca fazla ayrıntı ekleyin, hatayı yeniden oluşturmayla ilgili basit talimatlar verin ve Bileşenler kutusuna UI>Browser>WebAppInstalls yazın. Glitch, hızlı ve kolay yeniden oluşturma işlemlerini paylaşmak için idealdir.

API'yi destekleme

Window Controls Overlay API'yi kullanmayı planlıyor musunuz? Herkese açık desteğiniz, Chromium ekibinin özelliklere öncelik vermesine yardımcı olur ve diğer tarayıcı tedarikçi firmalarına bu özellikleri desteklemenin ne kadar önemli olduğunu gösterir.

@ChromiumDev hesabına #WindowControlsOverlay hashtag'ini ekleyerek bir Tweet gönderin ve bu özelliği nerede ve nasıl kullandığınızı bize bildirin.

Faydalı bağlantılar

• Açıklayıcı
• Özellik taslağı
• Chromium hatası
• Chrome Platform Durumu girişi
• TAG incelemesi
• Microsoft Edge ile ilgili dokümanlar

Teşekkür ederiz

Pencere denetimi yer paylaşımı, Microsoft Edge ekibinden Amanda Baker tarafından uygulandı ve tanımlandı. Bu makale Joe Medley ve Kenneth Rohde Christiansen tarafından incelenmiştir. Unsplash'taki Sigmund tarafından oluşturulan hero resim.