Personalizza l'overlay dei controlli della finestra della barra del titolo della PWA

Usa l'area della barra del titolo accanto ai controlli della finestra per rendere la PWA più simile a un'app.

Amanda Baker

Thomas Steiner

Se ricordi il mio articolo Rendere la tua PWA più simile a un'app, ricorderai come ho menzionato la personalizzazione della barra del titolo dell'app come per creare un'esperienza più simile a quella di un'app. Ecco un esempio di come potrebbe essere strutturata che mostra l'app macOS Podcasts.

Ora potreste avere la tentazione di opporvi dicendo che Podcasts è un'app macOS specifica della piattaforma che non vengono eseguite in un browser e possono quindi fare ciò che vogliono senza dover intervenire le regole del caso. È vero, ma la buona notizia è che la funzionalità Overlay controlli finestra, argomento Questo articolo ti consente di creare interfacce utente simili per la tua PWA.

Componenti Overlay controlli finestra

L'overlay dei controlli delle finestre è costituito da quattro funzionalità secondarie:

1. Il valore "window-controls-overlay" per il campo "display_override" in il file manifest dell'app web.
2. Le variabili di ambiente CSS titlebar-area-x, titlebar-area-y, titlebar-area-width e titlebar-area-height.
3. La standardizzazione della proprietà CSS precedentemente proprietaria -webkit-app-region come app-region per definire le regioni trascinabili nei contenuti web.
4. Un meccanismo per eseguire query e aggirare la regione dei controlli delle finestre tramite windowControlsOverlay membro di window.navigator.

Che cos'è l'overlay dei controlli delle finestre

L'area della barra del titolo fa riferimento allo spazio a sinistra o a destra dei controlli della finestra (ovvero, pulsanti per ridurre a icona, ingrandire, chiudere e così via) e spesso contiene il titolo dell'applicazione. Finestra L'overlay dei controlli consente alle applicazioni web progressive (PWA) di offrire un'interfaccia più simile a quella di un'app scambiando la barra del titolo a larghezza intera esistente per un piccolo overlay contenente i controlli delle finestre. Ciò consente agli sviluppatori di inserire contenuti personalizzati in quella che in precedenza era l'area della barra del titolo controllata dal browser.

Stato attuale

Come utilizzare l'overlay dei controlli delle finestre

Aggiunta di window-controls-overlay al file manifest dell'app web in corso...

Un'app web progressiva può attivare l'overlay dei controlli delle finestre aggiungendo "window-controls-overlay" come membro principale "display_override" nel file manifest dell'app web:

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

L'overlay dei controlli delle finestre sarà visibile solo se vengono soddisfatte tutte le seguenti condizioni:

1. L'app non viene aperta nel browser, ma in una finestra PWA separata.
2. Il file manifest include "display_override": ["window-controls-overlay"]. (Altri valori sono consentito in seguito).
3. La PWA viene eseguita su un sistema operativo desktop.
4. L'origine attuale corrisponde all'origine per cui è stata installata la PWA.

Il risultato è un'area della barra del titolo vuota con i normali controlli della finestra sulla sinistra o corretto, a seconda del sistema operativo.

Spostamento dei contenuti nella barra del titolo

Ora che la barra del titolo contiene uno spazio, puoi spostare qualcosa lì. In questo articolo, ha creato una PWA per i contenuti in primo piano su Wikimedia. Una funzionalità utile per questa app potrebbe essere la ricerca di parole in i titoli degli articoli. L'HTML per la funzionalità di ricerca ha il seguente aspetto:

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

Per spostare questo div in alto nella barra del titolo, sono necessari alcuni 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);
}

Puoi vedere l'effetto di questo codice nello screenshot riportato di seguito. La barra del titolo è completamente reattiva. Quando ridimensiona la finestra della PWA, la barra del titolo reagisce come se fosse composta da normali contenuti HTML, e in effetti lo è.

Determinare quali parti della barra del titolo possono essere trascinate

Anche se lo screenshot riportato sopra suggerisce che hai finito, non hai ancora finito. La finestra PWA è non è più trascinabile (a parte un'area molto piccola), poiché i pulsanti dei controlli della finestra non sono trascinabili e il resto della barra del titolo è costituito dal widget Ricerca. Risolvi il problema utilizzando la proprietà CSS app-region con il valore drag. Nel caso concreto, è corretto effettuare tutti gli elementi tranne l'elemento input trascinabili.

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

Con questo CSS attivo, l'utente può trascinare la finestra dell'app come di consueto trascinando div, img, o label. Solo l'elemento input è interattivo, quindi è possibile inserire la query di ricerca.

Rilevamento delle caratteristiche

Il supporto dell'overlay dei controlli delle finestre può essere rilevato testando l'esistenza di windowControlsOverlay:

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

Una query sulla regione della finestra controlla con windowControlsOverlay

Finora il codice presenta un problema: su alcune piattaforme i controlli delle finestre si trovano sulla destra, nella gli altri sono a sinistra. A peggiorare le cose, i "tre puntini" Il menu Chrome verrà modificato media in base alla piattaforma. Ciò significa che l'immagine di sfondo con gradiente lineare deve adattarsi dinamicamente per l'esecuzione da #131313→maroon o maroon→#131313→maroon, in modo si integra con il colore di sfondo maroon della barra del titolo, che viene determinato <meta name="theme-color" content="maroon">. A questo scopo, si esegue una query API getTitlebarAreaRect() nella proprietà 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');
}

Anziché avere l'immagine di sfondo direttamente nelle regole CSS della classe .search (come prima), il il codice modificato ora utilizza due classi impostate in modo dinamico dal codice riportato sopra.

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

Stabilire se l'overlay dei controlli delle finestre è visibile

L'overlay dei controlli delle finestre non sarà sempre visibile nell'area della barra del titolo. Mentre naturalmente non sarà presente sui browser che non supportano la funzione overlay controlli finestra. non sarà presente nemmeno quando la PWA in questione viene eseguita in una scheda. Per rilevare questa situazione, puoi esegui una query sulla proprietà visible di windowControlsOverlay:

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

In alternativa, puoi anche utilizzare la query multimediale display-mode in JavaScript e/o 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. */ 
}

Ricevere notifiche sulle modifiche alla geometria

Può essere sufficiente eseguire una query sull'area di overlay dei controlli della finestra con getTitlebarAreaRect() come impostare l'immagine di sfondo corretta in base alla posizione dei controlli della finestra, ma in in altri casi, è necessario un controllo più granulare. Ad esempio, un possibile caso d'uso potrebbe essere adattare l'overlay dei controlli delle finestre in base allo spazio disponibile e aggiungere una barzelletta direttamente nella finestra quando lo spazio è sufficiente.

Puoi ricevere notifiche in caso di modifiche alla geometria iscrivendoti a navigator.windowControlsOverlay.ongeometrychange o impostando un listener di eventi per l'evento Evento geometrychange. Questo evento si attiverà solo quando l'overlay dei controlli della finestra è visibile, ovvero è, quando 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);
}

Anziché assegnare una funzione a ongeometrychange, puoi anche aggiungere un listener di eventi a windowControlsOverlay come indicato di seguito. Puoi scoprire la differenza tra i due modelli su MDN:

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

Compatibilità in esecuzione in una scheda e su browser non supportati

Ci sono due casi da prendere in considerazione:

• Il caso in cui un'app è in esecuzione in un browser che supporta l'overlay dei controlli delle finestre, ma in cui l'app è utilizzata in una scheda del browser.
• Il caso in cui un'app è in esecuzione in un browser che non supporta l'overlay dei controlli delle finestre.

In entrambi i casi, per impostazione predefinita, il codice HTML creato per i controlli delle finestre l'overlay mostrerà in linea, come i normali contenuti HTML e le env() variabili valori di riserva verrà attivato per il posizionamento. Sui browser di supporto, puoi anche decidere di non visualizzare HTML designato per l'overlay dei controlli delle finestre controllando la proprietà visible dell'overlay e se riporterà false, nascondendo i contenuti HTML.

Ti ricordiamo che i browser non supportati non prenderanno in considerazione "display_override" proprietà manifest dell'app web o non riconoscere la proprietà "window-controls-overlay" e quindi utilizza il successivo valore possibile in base alla catena di riserva, ad esempio "standalone".

Considerazioni sull'interfaccia utente

Per quanto sia allettante, non è consigliabile creare un menu a discesa classico nell'area Overlay controlli finestra. Ciò violerebbe le linee guida sulla progettazione su macOS, una piattaforma su cui gli utenti si aspettano le barre dei menu (sia quelle fornite dal sistema che quelli personalizzati) nella parte superiore dello schermo.

Se la tua app offre un'esperienza a schermo intero, valuta attentamente se ha senso per visualizzare l'overlay dei controlli delle finestre nella visualizzazione a schermo intero. Potresti vuoi riorganizzare il layout quando onfullscreenchange di eventi.

Demo

Ho creato una demo con cui puoi sperimentare diversi browser di supporto e non supportati e nello stato installato e non installato. Per l'esperienza effettiva con l'overlay dei controlli della finestra, devi installare l'app. Di seguito puoi vedere due screenshot di cosa aspettarsi. La il codice sorgente dell'app è disponibile su Glitch.

La funzione di ricerca nell'overlay dei controlli delle finestre è perfettamente funzionante:

Considerazioni sulla sicurezza

Il team di Chromium ha progettato e implementato l'API Window Controls Overlay utilizzando i principi fondamentali definita in Controllo dell'accesso a funzionalità avanzate della piattaforma web, tra cui le controllo, trasparenza ed ergonomia.

Spoofing

Concedere ai siti il controllo parziale della barra del titolo lascia spazio agli sviluppatori per lo spoofing dei contenuti in in precedenza era una regione attendibile controllata da browser. Attualmente, nei browser Chromium, la versione autonoma include una barra del titolo che, all'avvio iniziale, visualizza il titolo della pagina web a sinistra e l'origine della pagina a destra (seguita dal pulsante "Impostazioni e altro" e dalla finestra ). Dopo alcuni secondi, il testo di origine scompare. Se il browser è impostato sulla scrittura da destra a sinistra (RTL), questo layout è capovolto in modo che il testo di origine si trovi a sinistra. Si apre i controlli delle finestre si sovrappongono per lo spoofing dell'origine se non c'è spaziatura interna sufficiente tra l'origine e sul bordo destro dell'overlay. Ad esempio, l'origine "evil.ltd" potrebbe essere aggiunto con un sito "google.com", che induce gli utenti a credere che la fonte sia affidabile. Il nostro piano è mantenere questo testo dell'origine, in modo che gli utenti sappiano qual è l'origine dell'app e possano garantire che corrisponda le aspettative. Per i browser configurati con RTL, deve essere presente una spaziatura interna sufficiente a destra dell'origine per evitare che un sito web dannoso aggiunga l’origine non sicura con un’origine attendibile.

Fingerprinting

Attivazione dell'overlay dei controlli delle finestre e delle regioni trascinabili non posate notevoli problemi di privacy, oltre al rilevamento delle funzionalità. Tuttavia, a causa posizioni e dimensioni diverse dei pulsanti di controllo della finestra sistemi, navigator.windowControlsOverlay.getTitlebarAreaRect() restituisce un valore DOMRect la cui posizione e le cui dimensioni rivelano informazioni sul sistema operativo su cui è in esecuzione il browser. Al momento, gli sviluppatori possono già trovare il sistema operativo dalla stringa user agent, ma a causa di problemi di fingerprinting, sul blocco della stringa UA e sull'unificazione delle versioni del sistema operativo. C'è un all'interno della community dei browser per comprendere con quale frequenza le dimensioni della finestra controlli che si sovrappongono alle modifiche su più piattaforme, come è che siano abbastanza stabili nelle varie versioni del sistema operativo e, di conseguenza, utili per osservare le versioni secondarie del sistema operativo. Sebbene questo sia un potenziale di fingerprinting, si applica solo alle PWA installate che utilizzano barra del titolo e non riguarda l'utilizzo generico del browser. Inoltre, L'API navigator.windowControlsOverlay non sarà disponibile per iframe incorporati all'interno di una PWA.

Navigazione

Il passaggio a un'origine diversa all'interno di una PWA farà tornare alla normale modalità autonoma barra del titolo, anche se soddisfa i criteri di cui sopra e viene avviata con l'overlay dei controlli delle finestre. per sistemare la barra nera visualizzata durante la navigazione verso un'origine diversa. Dopo il giorno tornando all'origine originale, verrà utilizzato di nuovo l'overlay dei controlli delle finestre.

Feedback

Il team di Chromium vuole saperne di più sulla tua esperienza con l'API Window Controls Overlay.

Parlaci della progettazione dell'API

C'è qualcosa nell'API che non funziona come previsto? Oppure mancano metodi o le proprietà necessarie per implementare la tua idea? Hai una domanda o un commento sulla sicurezza modello? Segnala un problema relativo alle specifiche sul repository GitHub corrispondente o aggiungi le tue opinioni a un problema esistente.

Segnalare un problema con l'implementazione

Hai trovato un bug nell'implementazione di Chromium? Oppure l'implementazione è diversa dalle specifiche? Segnala un bug all'indirizzo new.crbug.com. Includi il maggior numero di dettagli possibile, semplici istruzioni per la riproduzione e inserisci UI>Browser>WebAppInstalls nel campo Componenti . Glitch è la soluzione perfetta per condividere riproduzioni in modo facile e veloce.

Mostra il supporto per l'API

Intendi utilizzare l'API Window Controls Overlay? Il tuo supporto pubblico aiuta il team di Chromium per dare priorità alle funzionalità e mostra agli altri fornitori di browser quanto sia fondamentale supportarli.

Invia un tweet a @ChromiumDev con il #WindowControlsOverlay: e facci sapere dove e come lo utilizzi.

Link utili

• Spiegazione
• Bozza delle specifiche
• Bug di Chromium
• Voce relativa allo stato della piattaforma Chrome
• Revisione TAG
• Documentazione correlata di Microsoft Edge

Ringraziamenti

L'overlay dei controlli delle finestre è stato implementato e specificato da Amanda Baker del team di Microsoft Edge. Questo articolo è stato esaminato da Joe Medley e Kenneth Rohde Christiansen. Immagine hero di Sigmund su Unsplash.