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

Aby Twoja aplikacja PWA przypominała aplikację, użyj obszaru paska tytułu obok elementów sterujących w oknie.

Amanda Baker

Thomas Steiner

Z naszego artykułu Spraw, by aplikacja PWA bardziej przypominała aplikację, być może pamiętasz. o dostosowaniu paska tytułu aplikacji która pozwala tworzyć treści bardziej podobne do aplikacji. Oto przykład, z aplikacją Podcasty na system macOS.

Teraz możesz wydawać się kuszący, jeśli twierdzi, że podcasty to specyficzna platforma dla systemu macOS, nie są uruchamiane w przeglądarce, więc mogą robić to, co chce, bez konieczności odtwarzania reguł. To prawda, ale mamy też dobrą wiadomość: funkcja Nakładka z elementami sterującymi okna, której temat już wkrótce będzie można utworzyć podobne interfejsy użytkownika do 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" pola "display_override" w argumencie pliku manifestu aplikacji internetowej.
2. Zmienne środowiskowe CSS titlebar-area-x, titlebar-area-y, titlebar-area-width i titlebar-area-height
3. Standaryzacja wcześniej zastrzeżonej właściwości CSS -webkit-app-region jako app-region do definiowania regionów, które można przeciągać w treści internetowej.
4. Mechanizm do wysyłania zapytań dotyczących regionu okna i obchodzenia go windowControlsOverlay członek grupy window.navigator.

Czym jest nakładka z elementami sterującymi okna

Obszar paska tytułu odnosi się do obszaru z lewej lub prawej strony elementów sterujących okna (czyli do minimalizowania, maksymalizacji, zamykania itp.) i często zawiera tytuł aplikacji. Okno Nakładka elementów sterujących pozwala progresywnym aplikacjom internetowym (PWA) przypominać aplikacje, zmieniając je obecnego paska tytułu o pełnej szerokości dla małej nakładki z elementami sterującymi okna. Dzięki temu na umieszczanie własnych treści w miejscu, które wcześniej było zarządzane przez przeglądarkę w obszarze paska tytułu.

Obecny stan,

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

Dodaję window-controls-overlay do pliku manifestu aplikacji internetowej

Progresywna aplikacja internetowa może włączyć nakładkę z elementami sterującymi okna, dodając "window-controls-overlay" jako główny członek grupy "display_override" w manifeście aplikacji internetowej:

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

Nakładka z elementami sterującymi okna jest widoczna tylko wtedy, gdy są spełnione wszystkie te warunki:

1. Aplikacja nie jest otwierana w przeglądarce, tylko w osobnym oknie aplikacji PWA.
2. Plik manifestu zawiera "display_override": ["window-controls-overlay"]. (Inne wartości to dozwolone później).
3. Progresywna aplikacja internetowa działa w systemie operacyjnym na komputerze.
4. Bieżące źródło pasuje do punktu początkowego, dla którego zainstalowano PWA.

Efektem jest pusty obszar paska tytułu ze zwykłymi elementami sterującymi okna po lewej stronie lub zależnie od systemu operacyjnego.

Przenoszenie treści na pasek tytułu

Gdy masz już miejsce na pasku tytułu, możesz je przenieść. W tym artykule stworzył progresywną aplikację internetową Wikimedia Polecane treści. Przydatną funkcją tej aplikacji może być wyszukiwanie słów w języku: tytuły 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ść ten element (div) w górę na pasek tytułu, potrzebny jest arkusz 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 kodu jest widoczny na zrzucie ekranu poniżej. Pasek tytułu jest w pełni elastyczna. Kiedy jeśli zmienisz rozmiar okna PWA, pasek tytułu będzie wyglądać tak, jakby składał się ze zwykłej treści HTML, które w rzeczywistości jest nim.

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

Zrzut ekranu sugeruje, że wszystko jest już gotowe, ale to jeszcze nie koniec. Okno PWA to nie można już przeciągać (niezależnie od bardzo małego obszaru), ponieważ przyciski sterujące oknem nie są przeciągane obszarów, a reszta paska tytułu składa się z widżetu wyszukiwania. Napraw to, używając właściwość CSS app-region z wartością drag. W konkretnym przypadku dobrze jest sprawić, wszystko poza elementem input, który można przeciągać.

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

Po dodaniu kodu CSS użytkownik może w zwykły sposób przeciągnąć okno aplikacji, przeciągając atrybuty div, img, lub label. Interaktywny jest tylko element input, więc można wpisać zapytanie.

Wykrywanie cech

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

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

Wysyłanie zapytania do regionu ustawień okna za pomocą funkcji windowControlsOverlay

Jak na razie w kodzie występuje jeden problem: na niektórych platformach elementy sterujące okna znajdują się po prawej stronie, a inne po lewej. Aby pogorszyć sprawę, „trzy kropki” Menu Chrome zmieni się pozycji reklamy, również na podstawie platformy. Oznacza to, że obraz tła z gradientem liniowym musi: może zostać dynamicznie dostosowany tak, aby działał od #131313→maroon lub maroon→#131313→maroon, tak aby zlewa się z kolorem tła maroon paska tytułu, który jest określany przez <meta name="theme-color" content="maroon"> Można to osiągnąć, wysyłając zapytanie do Interfejs API getTitlebarAreaRect() w usłudze 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 obrazu tła w regułach CSS klasy .search bezpośrednio (jak wcześniej), funkcja zmodyfikowany kod używa teraz dwóch klas, które powyższy kod ustawia dynamicznie.

/* 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 widoczna jest nakładka z elementami sterującymi okna

W każdym przypadku nakładka z elementami sterującymi okna nie będzie widoczna w obszarze paska tytułu. Choć nie będzie działać w przeglądarkach, które nie obsługują funkcji nakładki z ustawieniami okien, nie pojawi się też wtedy, gdy aplikacja PWA działa na karcie. Aby wykryć taką sytuację, możesz: wysyła zapytanie do właściwości visible elementu windowControlsOverlay:

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

Możesz też użyć zapytania o media 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. */ 
}

Powiadomienia o zmianach geometrycznych

Wystarczy jednorazowe zapytanie o obszar nakładki z elementami sterującymi okna za pomocą parametru getTitlebarAreaRect(). na przykład ustawić odpowiedni obraz tła w zależności od tego, gdzie znajdują się elementy sterujące okna, w innych przypadkach konieczna jest bardziej szczegółowa kontrola. Przykładem może być Dostosuj nakładkę z elementami sterującymi okna do wolnego miejsca i dodawaj żart bezpośrednio w oknie nad powierzchnią, gdy jest wystarczająco dużo miejsca.

Możesz otrzymywać powiadomienia o zmianach geometrycznych, subskrybując navigator.windowControlsOverlay.ongeometrychange lub konfigurując detektor zdarzeń dla geometrychange. To zdarzenie jest uruchamiane tylko wtedy, gdy widoczna jest nakładka z elementami sterującymi okna, która jest, gdy navigator.windowControlsOverlay.visible to 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);
}

Zamiast przypisywać funkcję do funkcji ongeometrychange, możesz też dodać do niej odbiornik windowControlsOverlay jak poniżej. Różnicę między tymi usługami znajdziesz na stronie MDN:

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

Zgodność zarówno na karcie, jak i w nieobsługiwanych przeglądarkach

Istnieją 2 przypadki, które warto rozważyć:

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

W obu przypadkach domyślnie kod HTML utworzony dla elementów sterujących okna będzie wyświetlać się w tekście, tak jak zwykła treść HTML, a zmienne env() będą wyświetlane w tekście wartości kreacji zastępczych przejdzie do pozycjonowania. W obsługiwanych przeglądarkach możesz też nie wyświetlać kodu HTML określonej dla nakładki z elementami sterującymi okna. W tym celu sprawdź jej właściwość visible, a jeśli zgłasza false, a potem ukrywa tę treść HTML.

Przypominamy, że nieobsługujące przeglądarki nie uwzględniają "display_override" w ogóle nie rozpoznaje właściwości manifestu aplikacji internetowej lub "window-controls-overlay", a tym samym użyć następnej możliwej wartości w łańcuchu kreacji zastępczych, na przykład "standalone".

Uwagi na temat interfejsu

Chociaż może się to wydawać kuszące, nie zalecamy tworzenia klasycznego menu w obszarze Nakładka z elementami sterującymi okna. Naruszałoby to wytycznych dotyczących projektowania w systemie macOS, na platformie, na której użytkownicy oczekują pasków menu (zarówno tych dostarczanych przez system, niestandardowe) u góry ekranu.

Jeśli aplikacja działa na pełnym ekranie, zastanów się, czy ma to sens aby nakładka z elementami sterującymi okna była częścią widoku pełnoekranowego. Potencjalnie można chcesz zmienić układ, gdy onfullscreenchange pożary zdarzeń.

Prezentacja

Mam wersję demonstracyjną, w której możesz zagrać różne przeglądarki obsługujące i nieobsługujące oraz zainstalowane i niezainstalowane. Dla: w przypadku nakładki z elementami sterującymi okna, musisz zainstalować aplikację. Poniżej znajdziesz 2 zrzuty ekranu tego, czego możesz się spodziewać. kod źródłowy aplikacji jest dostępny w usłudze Glitch.

Funkcja wyszukiwania w nakładce z elementami sterującymi w oknie jest w pełni funkcjonalna:

Bezpieczeństwo

Zespół Chromium zaprojektował i wdrożył interfejs Window Controls Overlay API z zastosowaniem podstawowych zasad. w artykule Kontrola nad dostępem do zaawansowanych funkcji platform internetowych, w tym kontrolę, przejrzystość i ergonomię.

Podszywanie się

Dajemy witrynom częściową kontrolę nad paskiem tytułu, dzięki czemu deweloperzy mogą fałszować treści w był zaufanym regionem kontrolowanym przez przeglądarkę. Obecnie w przeglądarkach Chromium dostępne są Tryb obejmuje pasek tytułu, który przy pierwszym uruchomieniu wyświetla po lewej stronie tytuł strony. początek strony po prawej stronie (następnie przycisk „Ustawienia i inne” oraz okno) ). Po kilku sekundach tekst źródłowy zniknie. Jeśli w przeglądarce jest ustawiony kierunek od prawej do lewej (RTL), ten układ jest odwrócony w taki sposób, że tekst źródłowy znajduje się po lewej stronie. Otworzy się nakładka z elementami sterującymi okna, aby imitować źródło w przypadku niewystarczającego dopełnienia między punktem początkowym od prawej krawędzi nakładki. Na przykład źródło „evil.ltd” może zostać dodany do listy zaufanej „google.com”, przez co użytkownicy uważają, że źródło jest wiarygodne. Planujemy utrzymać tekstu źródłowego, dzięki któremu użytkownicy wiedzą, jakie jest pochodzenie aplikacji, i mają pewność, że pasuje ona do z oczekiwaniami. W przypadku przeglądarek ze skonfigurowanym ustawieniem od prawej do lewej musi być wystarczające dopełnienie po prawej stronie punktu początkowego. tekst, który uniemożliwia złośliwej witrynie dołączanie niebezpiecznego źródła do zaufanego źródła.

Odciski cyfrowe

Włączam nakładkę z elementami sterującymi okna, a regiony, które można przeciągać, nie są ustawione istotne kwestie dotyczące prywatności, inne niż wykrywanie funkcji. Jednak ze względu na różnych rozmiarów i umiejscowienia przycisków sterowania oknami w różnych algorytm, navigator.windowControlsOverlay.getTitlebarAreaRect() zwraca DOMRect których położenie i wymiary ujawniają informacje o systemie operacyjnym które jest uruchomione w przeglądarce. Obecnie deweloperzy mogą już wykryć system operacyjny. z ciągu znaków klienta użytkownika, ale ze względu na problemy z odciskami cyfrowymi Rozmowa na temat wstrzymywania ciągu UA i ujednolicania wersji systemu operacyjnego. Istnieje nieustanne wysiłki społeczności przeglądarek, aby dowiedzieć się, jak często rozmiar nakładki z elementami sterującymi w oknie zmienia się na różnych platformach, Zakładamy, że są one dość stabilne niezależnie od wersji systemu operacyjnego, może być przydatna przy obserwacji mniejszych wersji systemów operacyjnych. Chociaż może to być dotyczy tylko zainstalowanych aplikacji PWA korzystających z paska tytułu i nie ma zastosowania do ogólnego użytkowania przeglądarki. Dodatkowo Interfejs API navigator.windowControlsOverlay nie będzie dostępny dla: Elementy iframe umieszczone w aplikacji PWA.

Nawigacja

Przejście do innego źródła w ramach PWA spowoduje powrót do normalnej samodzielnej aplikacji na pasku tytułu, nawet jeśli spełnia powyższe kryteria i jest uruchamiany z nakładką z elementami sterującymi okna. Ma to na celu uwzględnienie czarnego paska wyświetlanego podczas nawigacji do innego punktu początkowego. Po gdy wrócisz do pierwotnego punktu początkowego, nakładka z elementami sterującymi okna zostanie użyta ponownie.

Prześlij opinię

Zespół Chromium chce poznać Twoją opinię na temat korzystania z interfejsu Window Controls Overlay API.

Opowiedz nam o konstrukcji interfejsu API

Czy jest coś, co nie działa w interfejsie API zgodnie z oczekiwaniami? Czy może brakuje tu metod lub właściwości potrzebne do realizacji pomysłu? Masz pytanie lub komentarz na temat zabezpieczeń model? Zgłoś problem ze specyfikacją w odpowiednim repozytorium GitHub lub dodaj swoje uwagi do do istniejącego problemu.

Zgłoś problem z implementacją

Czy wystąpił błąd związany z implementacją Chromium? Czy implementacja różni się od specyfikacji? Zgłoś błąd na new.crbug.com. Podaj jak najwięcej szczegółów. instrukcje dotyczące odtwarzania i wpisz UI>Browser>WebAppInstalls w sekcji Komponenty. . Usługa Glitch świetnie nadaje się do szybkiego i łatwego udostępniania poprawek.

Pokaż wsparcie dla interfejsu API

Czy planujesz korzystać z interfejsu Window Controls Overlay API? Twoje publiczne wsparcie pomaga zespołowi Chromium nadając priorytet funkcjom i pokazując innym dostawcom przeglądarek, jak ważne jest ich wsparcie.

Wyślij tweeta na adres @ChromiumDev ze #WindowControlsOverlay. i daj nam znać, gdzie i jak go używasz.

Przydatne linki

• Wyjaśnienie
• Wersja robocza specyfikacji
• Błąd Chromium
• Wpis Stan platformy Chrome
• Ocena TAG
• Dokumentacja Microsoft Edge

Podziękowania

Nakładka z elementami sterującymi okna została wdrożona i określona przez Amanda Baker z zespołu Microsoft Edge Ten artykuł został zrecenzowany przez Joe Medley i Kenneth Rohde Christiansen Baner powitalny: Sigmund w sekcji Unsplash.