Usa l'area della barra del titolo accanto ai controlli della finestra per rendere la PWA più simile a un'app.
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.
![Una barra del titolo dell'app macOS Podcasts che mostra i pulsanti di controllo dei contenuti multimediali e i metadati relativi al podcast attualmente in riproduzione.](https://web.dev/static/articles/window-controls-overlay/image/a-macos-podcasts-app-titl-20aca29098b84.png?authuser=0&hl=it)
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:
- Il valore
"window-controls-overlay"
per il campo"display_override"
in il file manifest dell'app web. - Le variabili di ambiente CSS
titlebar-area-x
,titlebar-area-y
,titlebar-area-width
etitlebar-area-height
. - La standardizzazione della proprietà CSS precedentemente proprietaria
-webkit-app-region
comeapp-region
per definire le regioni trascinabili nei contenuti web. - Un meccanismo per eseguire query e aggirare la regione dei controlli delle finestre tramite
windowControlsOverlay
membro diwindow.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
Passaggio | Stato |
---|---|
1. Crea messaggio esplicativo | Completato |
2. Crea la bozza iniziale delle specifiche | Completato |
3. Raccogli feedback e esegui l'iterazione del design | In corso |
4. Prova dell'origine | Completa |
5. Lancio | Completata (in Chromium 104) |
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:
- L'app non viene aperta nel browser, ma in una finestra PWA separata.
- Il file manifest include
"display_override": ["window-controls-overlay"]
. (Altri valori sono consentito in seguito). - La PWA viene eseguita su un sistema operativo desktop.
- 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.
![Una finestra dell'app con una barra del titolo vuota e i controlli della finestra a sinistra.](https://web.dev/static/articles/window-controls-overlay/image/an-app-window-an-empty-t-43c563112c2d7.png?authuser=0&hl=it)
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 è.
![Una finestra dell'app con una barra di ricerca nella barra del titolo.](https://web.dev/static/articles/window-controls-overlay/image/an-app-window-a-search-b-e0052c91f794c.png?authuser=0&hl=it)
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.
![I controlli della finestra si sovrappongono a una finestra stretta con testo abbreviato.](https://web.dev/static/articles/window-controls-overlay/image/window-controls-overlay-a-383c6a756329.png?authuser=0&hl=it)
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.
![Una PWA in esecuzione in una scheda del browser con l'overlay dei controlli delle finestre visualizzato nel corpo.](https://web.dev/static/articles/window-controls-overlay/image/a-pwa-running-a-browser-404595bd2cb6d.png?authuser=0&hl=it)
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"
.
![Una PWA in esecuzione in modalità autonoma con l'overlay dei controlli delle finestre visualizzato nel corpo.](https://web.dev/static/articles/window-controls-overlay/image/a-pwa-running-standalone-2badef6176edf.png?authuser=0&hl=it)
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.
![L'app demo Contenuti in primo piano Wikimedia con overlay dei controlli delle finestre.](https://web.dev/static/articles/window-controls-overlay/image/the-wikimedia-featured-co-1d13973f05a73.png?authuser=0&hl=it)
La funzione di ricerca nell'overlay dei controlli delle finestre è perfettamente funzionante:
![App demo dei contenuti in primo piano di Wikimedia con overlay dei controlli delle finestre e ricerca attiva del termine "cleopa..." in cui viene evidenziato uno degli articoli con il termine corrispondente "Cleopatra".](https://web.dev/static/articles/window-controls-overlay/image/the-wikimedia-featured-co-b28ddfbf5edaf.png?authuser=0&hl=it)
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.
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.
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.
![Una barra dell'URL nera per la navigazione fuori origine.](https://web.dev/static/articles/window-controls-overlay/image/a-black-url-bar-out-ori-e3d2faea499bf.png?authuser=0&hl=it)
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.