Dostosuj nakładkę elementów sterujących oknami na pasku tytułu PWA

Użyj obszaru paska tytułu obok elementów sterujących oknem, aby Twoja PWA była bardziej podobna do aplikacji.

Amanda Baker

Thomas Steiner

Jeśli pamiętasz mój artykuł Uczynienie aplikacji internetowej bardziej zbliżoną do aplikacji, być może przypomnisz sobie, że dostosowywanie paska tytułu aplikacji jest strategią na stworzenie środowiska bardziej zbliżonego do aplikacji. Oto przykład tego, jak to może wyglądać w przypadku aplikacji Podcasty na macOS.

Niestandardowy pasek tytułu sprawia, że aplikacja PWA wygląda bardziej jak aplikacja na daną platformę.

Możesz teraz zaprotestować, twierdząc, że Podcasty to aplikacja na macOS, która nie działa w przeglądarce, a więc może robić, co chce, bez konieczności przestrzegania zasad przeglądarki. To prawda, ale mamy dobrą wiadomość: funkcja nakładki z elementami sterującymi okna, która jest tematem tego artykułu, pozwoli Ci wkrótce tworzyć podobne interfejsy użytkownika dla aplikacji PWA.

Komponenty nakładki z elementami sterującymi okna

Nakładka z elementami sterującymi okna składa się z 4 podfunkcji:

1. Wartość "window-controls-overlay" w polu "display_override" w pliku manifestu aplikacji internetowej.
2. Zmienne środowiskowe CSS titlebar-area-x, titlebar-area-y, titlebar-area-width i titlebar-area-height.
3. Standardizacja wcześniej zastrzeżonej właściwości CSS -webkit-app-region jako właściwości app-region służącej do definiowania obszarów do przeciągania w treściach internetowych.
4. Mechanizm umożliwiający wysyłanie zapytań do regionu elementów sterujących okna i obchodzenie go za pomocą elementu windowControlsOverlay w klasie window.navigator.

Co to jest nakładka z elementami sterującymi okna

Obszar paska tytułu to przestrzeń po lewej lub prawej stronie elementów sterujących oknem (czyli przycisków minimalizowania, maksymalizowania, zamykania itp.) i często zawiera tytuł aplikacji. Nakładka z elementami sterującymi okna umożliwia progresywnym aplikacjom internetowym (PWA) działanie bardziej zbliżone do aplikacji natywnych. Polega to na zastąpieniu dotychczasowego paska tytułu o pełnej szerokości małą nakładką zawierającą elementy sterujące oknem. Umożliwia to deweloperom umieszczanie treści niestandardowych w obszarze paska tytułu kontrolowanym wcześniej przez przeglądarkę.

Obecny stan,

Krok	Stan
1. Tworzenie wyjaśnienia	Zakończono
2. Tworzenie wstępnej wersji specyfikacji	Zakończono
3. Zbieraj opinie i ulepszaj projekt	W toku
4. Wersja próbna origin	Zakończone
5. Wprowadzenie na rynek	Ukończone (w Chromium 104)

Jak korzystać z nakładki z elementami sterującymi okna

Dodawanie window-controls-overlay do pliku manifestu aplikacji internetowej

Progresywna aplikacja internetowa może włączyć nakładkę elementów sterujących oknem, dodając "window-controls-overlay" jako głównego użytkownika "display_override" w pliku manifestu aplikacji internetowej:

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

Warstwy kontrolek okna będą widoczne tylko wtedy, gdy spełnione są wszystkie te warunki:

1. Aplikacja nie otwiera się w przeglądarce, ale w osobnym oknie PWA.
2. Manifest zawiera "display_override": ["window-controls-overlay"]. (inne wartości są dozwolone).
3. Progresywna aplikacja internetowa działa w systemie operacyjnym na komputery.
4. Bieżące źródło jest zgodne ze źródłem, w którym zainstalowano PWA.

W efekcie jest to pusta linia tytułu z zwykłymi elementami sterowania oknem po lewej lub prawej stronie, w zależności od systemu operacyjnego.

Pusty pasek tytułu gotowy na treści niestandardowe.

Przenoszenie treści na pasek tytułu

Teraz, gdy na pasku tytułu jest miejsce, możesz tam coś przenieść. Na potrzeby tego artykułu stworzyłem PWA z wyróżnionymi treściami w Wikimedii. Przydatną funkcją w tej aplikacji może być wyszukiwanie słów w tytułach artykułów. Kod HTML funkcji wyszukiwania wygląda tak:

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

Aby przenieść element div do paska tytułu, musisz użyć odrobiny kodu 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);
}

Efekt działania tego kodu możesz zobaczyć na zrzucie ekranu poniżej. Pasek tytułu jest w pełni responsywny. Gdy zmieniasz rozmiar okna aplikacji PWA, pasek tytułu reaguje tak, jakby składał się z treści HTML, co w istocie jest prawdą.

Nowa aktywna i responsywna pasek tytułu.

Określanie, które części paska tytułu można przeciągać

Zrzut ekranu powyżej sugeruje, że wszystko jest już gotowe, ale tak nie jest. Okno aplikacji PWA nie można już przeciągać (poza bardzo małym obszarem), ponieważ przyciski elementów sterujących oknem nie są obszarami przeciągania, a pozostałości paska tytułu składają się z widżetu wyszukiwania. Aby to naprawić, użyj właściwości CSS app-region o wartości drag. W tym konkretnym przypadku możesz dopuścić przeciąganie wszystkich elementów z wyjątkiem elementu 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;
}

Uwaga: na razie app-region nie zostało ujednolicone, dlatego planujemy nadal używać prefiksu -webkit-app-region, dopóki app-region nie zostanie ujednolicona. Obecnie w przeglądarce obsługiwana jest tylko forma -webkit-app-region.

Dzięki temu użytkownik może przeciągać okno aplikacji jak zwykle, przeciągając div, img lub label. Tylko element input jest interaktywny, więc można w nim wpisać zapytanie.

Wykrywanie cech

Obsługę nakładki z elementami sterującymi okna można wykryć, testując obecność: windowControlsOverlay:

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

Wysyłanie zapytania do regionu elementów sterowania okna za pomocą windowControlsOverlay

Kod ma jednak pewien problem: na niektórych platformach kontrolki okna znajdują się po prawej stronie, a na innych – po lewej. Co gorsza, menu z 3 kropkami w Chrome również zmieni swoją pozycję w zależności od platformy. Oznacza to, że obraz tła z gradientem liniowym musi być dynamicznie dostosowywany do zakresu #131313→maroon lub maroon→#131313→maroon, aby był zharmonizowany z kolorem maroon tła paska tytułu, który jest określany przez <meta name="theme-color" content="maroon">. Można to zrobić, wysyłając zapytanie do interfejsu API getTitlebarAreaRect() dotyczące właściwości 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');
}

Zamiast umieszczać obraz tła bezpośrednio w regułach CSS klasy .search (jak wcześniej), zmodyfikowany kod używa teraz 2 klas, które są ustawiane dynamicznie przez kod podany powyżej.

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

Określanie, czy nakładka z elementami sterującymi okna jest widoczna

Nakładka z elementami sterującymi okna nie będzie widoczna w pasku tytułu w każdych okolicznościach. Oczywiście nie będzie ona dostępna w przeglądarkach, które nie obsługują funkcji nakładki elementów sterujących oknem, ale też nie będzie widoczna, gdy PWA będzie działać w karcie. Aby wykryć taką sytuację, możesz wysłać zapytanie do właściwości visible obiektu windowControlsOverlay:

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

Uwaga: widoczność nakładki kontrolek okna nie należy mylić z widocznością w rozumieniu CSS dowolnych treści HTML umieszczonych obok nakładki kontrolek okna. Nawet jeśli ustawisz wartość display: none dla elementu div umieszczonego w nakładce z elementami sterującymi okna, właściwość visible nakładki z elementami sterującymi okna będzie nadal raportować wartość true.

Możesz też użyć zapytania o multimedia display-mode w JavaScript lub 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. */ 
}

otrzymywać powiadomienia o zmianach geometrii;

Zapytanie obszaru nakładki elementów sterujących okna za pomocą getTitlebarAreaRect() może wystarczyć w przypadku jednorazowych czynności, takich jak ustawienie prawidłowego obrazu tła na podstawie położenia elementów sterujących okna, ale w innych przypadkach konieczna jest bardziej szczegółowa kontrola. Przykładem zastosowania może być dostosowanie nakładki elementów sterujących okna na podstawie dostępnej przestrzeni i dodanie dowczasy żartu, gdy jest wystarczająco dużo miejsca.

Elementy sterujące na pasku tytułu dostosowane do wąskiego okna.

Aby otrzymywać powiadomienia o zmianach geometrii, możesz subskrybować zdarzenie navigator.windowControlsOverlay.ongeometrychange lub skonfigurować odbiornik zdarzeń dla zdarzenia geometrychange. To zdarzenie zostanie wywołane tylko wtedy, gdy nakładka elementów sterujących okna jest widoczna, czyli gdy navigator.windowControlsOverlay.visible ma wartość true.

Uwaga: ponieważ to zdarzenie jest wywoływane często (podobnie jak w przypadku odbiorcy przewijania), zawsze zalecam używanie funkcji debounce, aby nie było wywoływane zbyt często.

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

Zamiast przypisywać funkcję do ongeometrychange, możesz też dodać do windowControlsOverlay obiekt nasłuchujący zdarzeń, jak pokazano poniżej. Informacje o różnicach między tymi dwoma typami znajdziesz na stronie MDN.

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

Zgodność podczas uruchamiania w zakładce i w przeglądarkach, które nie obsługują tej funkcji

Należy wziąć pod uwagę 2 możliwe przypadki:

• Przypadek, gdy aplikacja działa w przeglądarce, która obsługuje nakładkę sterowania oknem, ale aplikacja jest używana na karcie przeglądarki.
• aplikacja działa w przeglądarce, która nie obsługuje nakładki z elementami sterującymi okna;

W obu przypadkach kod HTML utworzony na potrzeby okna z kontrolami będzie domyślnie wyświetlany w postaci wbudowanej treści HTML, a wartości zmiennych env() będą używane do pozycjonowania. W obsługiwanych przeglądarkach możesz też zdecydować, aby nie wyświetlać kodu HTML przeznaczonego dla nakładki elementów sterujących okna. Aby to zrobić, sprawdź właściwość visible nakładki. Jeśli zwróci ona wartość false, ukryj ten kod HTML.

Sterowanie przeznaczone dla paska tytułu można łatwo wyświetlić w starszych przeglądarkach.

Przypominamy, że przeglądarki, które nie obsługują tej funkcji, nie będą w ogóle uwzględniać właściwości pliku manifestu aplikacji internetowej "display_override" lub nie będą rozpoznawać wartości "window-controls-overlay", a dlatego użyją następnej możliwej wartości zgodnie z łańcuchem zastępczym, na przykład "standalone".

Sterowanie przeznaczone do paska tytułu można łatwo wyświetlić w starszych przeglądarkach.

Interfejs użytkownika

Chociaż może to być kuszące, nie zalecamy tworzenia klasycznego menu w obszarze okna kontrolnego. Spowoduje to naruszenie wytycznych dotyczących projektowania na system macOS, na którym użytkownicy oczekują, że paski menu (zarówno systemowe, jak i niestandardowe) będą znajdować się u góry ekranu.

Uwaga: prawidłowe interfejsy API menu aplikacji, podobne do interfejsu Menu dostępnego dla aplikacji Electron.js, są śledzone pod adresem crbug/1295253.

Jeśli Twoja aplikacja działa w trybie pełnoekranowym, dokładnie zastanów się, czy ma sens wyświetlanie nakładki elementów sterujących oknem w tym trybie. Możesz chcieć zmienić układ, gdy nastąpi zdarzenie onfullscreenchange.

Prezentacja

Stworzyliśmy demo, które możesz uruchomić w różnych przeglądarkach obsługujących i nieobsługujących tę grę oraz w stanie zainstalowanej i niezainstalowanej. Aby zobaczyć, jak działa nakładka sterowania oknem, musisz zainstalować aplikację. Poniżej znajdziesz 2 zrzuty ekranu pokazujące, czego się spodziewać. Kod źródłowy aplikacji jest dostępny na stronie Glitch.

Aplikacja demonstracyjna jest dostępna do eksperymentowania.

Funkcja wyszukiwania w nakładce z elementami sterującymi okna działa w pełni:

Funkcja wyszukiwania korzystająca z nakładki z elementami sterującymi okna.

Zagadnienia związane z bezpieczeństwem

Zespół Chromium zaprojektował i wdrżał interfejs Window Controls Overlay API, korzystając z podstawowych zasad określonych w artykule Controlling Access to Powerful Web Platform Features (Zarządzanie dostępem do zaawansowanych funkcji platformy internetowej) (w języku angielskim), w tym kontroli użytkownika, przejrzystości i ergonomii.

Podszywanie się

Przyznanie stronom częściowej kontroli nad paskiem tytułu daje deweloperom możliwość podszywania treści w obszarze, który był wcześniej zaufanym obszarem kontrolowanym przez przeglądarkę. Obecnie w przewodniku Chromium tryb samodzielny zawiera pasek tytułu, który po pierwszym uruchomieniu wyświetla po lewej stronie tytuł strony internetowej, a po prawej jej źródło (a zaraz potem przycisk „Ustawienia i więcej” oraz elementy sterujące oknem). Po kilku sekundach tekst źródłowy znika. Jeśli przeglądarka jest skonfigurowana tak, aby wyświetlać tekst w języku zapisywanym od prawej do lewej, układ jest odwrócony, tak aby tekst źródłowy znajdował się po lewej stronie. Otworzy to nakładkę elementów sterujących oknem, aby oszukać źródło, jeśli między źródłem a prawą krawędzią nakładki jest za mało miejsca. Źródło „evil.ltd” może na przykład zawierać zaufany adres „google.com”, co może sprawić, że użytkownicy uznają, że źródło jest godne zaufania. Planujemy zachować ten tekst, aby użytkownicy wiedzieli, skąd pochodzi aplikacja, i mogli się upewnić, że spełnia ich oczekiwania. W przypadku przeglądarek skonfigurowanych do wyświetlania tekstu od prawej do lewej musi być wystarczająca ilość miejsca po prawej stronie tekstu źródła, aby uniemożliwić złośliwej witrynie dodanie do niebezpiecznego źródła zaufanej domeny.

Odciski cyfrowe

Włączenie nakładki z elementami sterującymi okna i przeciągalnych regionów nie wiąże się z poważniejszymi problemami z prywatnością niż wykrywanie funkcji. Jednak ze względu na różne rozmiary i położenia przycisków sterowania oknem w różnych systemach operacyjnych metoda navigator.windowControlsOverlay.getTitlebarAreaRect() zwraca DOMRect, której położenie i wymiary zawierają informacje o systemie operacyjnym, w którym działa przeglądarka. Obecnie deweloperzy mogą już wykrywać system operacyjny na podstawie ciągu user-agenta, ale ze względu na problemy związane z odciskami cyfrowymi toczy się dyskusja na temat zamrożenia ciągu user-agenta i ujednolicania wersji systemu operacyjnego. W środowisku społeczności przeglądarek trwają prace nad ustaleniem, jak często zmienia się rozmiar nakładki elementów sterujących oknem na różnych platformach, ponieważ obecnie zakłada się, że te elementy są dość stabilne w różnych wersjach systemu operacyjnego i nie będą przydatne do obserwacji mniejszych wersji systemu. Chociaż jest to potencjalny problem związany z odciskami palców, dotyczy on tylko zainstalowanych PWA, które korzystają z niestandardowej funkcji paska tytułu. Nie ma zastosowania do ogólnego korzystania z przeglądarki. Dodatkowo interfejs API navigator.windowControlsOverlay nie będzie dostępny dla ramek iframe umieszczonych w aplikacji PWA.

Nawigacja

Przejście do innego źródła w aplikacji PWA spowoduje przejście do zwykłego okna samodzielnego, nawet jeśli spełnia ono powyższe kryteria i jest uruchamiane z nakładką z elementami sterującymi okna. Jest to spowodowane czarnym paskiem, który pojawia się podczas nawigacji do innego miejsca wyjazdu. Po powrocie do pierwotnego źródła ponownie będzie używana nakładka elementów sterujących oknem.

Gdy użytkownik przechodzi do innego źródła, wyświetla się czarny pasek.

Prześlij opinię

Zespół Chromium chce poznać Twoje wrażenia związane z interfejsem Window Controls Overlay API.

Prześlij informacje o projektowaniu interfejsu API

Czy coś w interfejsie API nie działa zgodnie z oczekiwaniami? A może brakuje metod lub właściwości, których potrzebujesz do wdrożenia swojego pomysłu? Masz pytania lub uwagi dotyczące modelu bezpieczeństwa? Zgłoś problem ze specyfikacją w odpowiednim repozytorium GitHub lub dodaj swoje uwagi do istniejącego problemu.

Zgłaszanie problemów z implementacją

Czy znalazłeś błąd w implementacji Chromium? A może implementacja różni się od specyfikacji? Zgłoś błąd na stronie new.crbug.com. Podaj jak najwięcej szczegółów, proste instrukcje odtwarzania błędu i wpisz UI>Browser>WebAppInstalls w polu Składniki. Glitch to świetne narzędzie do szybkiego i łatwego udostępniania informacji.

Pokaż pomoc dotyczącą interfejsu API

Zamierzasz używać interfejsu Window Controls Overlay API? Twoja publiczna pomoc pomaga zespołowi Chromium ustalać priorytety funkcji i pokazuje innym dostawcom przeglądarek, jak ważne jest wspieranie Chromium.

Wyślij tweeta do @ChromiumDev z hasztagiem #WindowControlsOverlay i powiedz nam, gdzie i jak go używasz.

Przydatne linki

• Wyjaśnienie
• Specyfikacja w wersji roboczej
• Błąd w Chromium
• Wpis w pliku Stan platformy Chrome
• Sprawdzanie tagów
• Powiązane dokumenty w Microsoft Edge

Podziękowania

Nakładkę z elementami sterującymi okna wdrożyła i opisywała Amanda Baker z zespołu Microsoft Edge. Ten artykuł został sprawdzony przez Joe Medleya i Kenneth Rohde Christiansena. Baner powitalny autorstwa Sigmund z Unsplash.