App web progressive: potenziare la tua PWA

1. Ti diamo il benvenuto

In questo lab, prenderai un'applicazione web esistente e aggiungerai funzionalità avanzate. Questo è il sesto di una serie di codelab complementari per il workshop sulle app web progressive. Il codelab precedente era Prompting & Measuring Install. In questa serie ci sono altri due codelab.

Obiettivi didattici

  • Aprire e salvare file dal file system dell'utente utilizzando l'API File System Access
  • Registra la PWA installata come gestore di file con l'API File Handling
  • Scegliere lo schermo giusto per aprire una finestra utilizzando l'API Multi-Screen Window Placement
  • Impedire che uno schermo vada in modalità di sospensione utilizzando l'API Screen Wake Lock

Che cosa devi sapere

  • JavaScript

Che cosa ti serve

  • Un browser che supporti le API indicate sopra. Per alcune API, potrebbe essere necessario utilizzare un browser con una prova per sviluppatori o una prova dell'origine attiva per completare l'operazione.

2. Configurazione

Inizia clonando o scaricando il codice iniziale necessario per completare questo codelab:

Se cloni il repository, assicurati di trovarti nel ramo pwa05--empowering-your-pwa. Il file zip contiene anche il codice per questo ramo.

Questo codebase richiede Node.js 14 o versioni successive. Una volta disponibile il codice, esegui npm ci dalla riga di comando nella cartella del codice per installare tutte le dipendenze necessarie. Poi, esegui npm start per avviare il server di sviluppo per il codelab.

Il file README.md del codice sorgente fornisce una spiegazione per tutti i file distribuiti. Inoltre, i seguenti sono i file esistenti chiave con cui lavorerai durante questo codelab:

File delle chiavi

  • js/lib/actions.js - Fornisce una classe base per il menu

Nota importante sull'architettura

In questo codelab, modificherai js/lib/action.js, che gestisce le azioni per i diversi pulsanti nel menu dell'app. Puoi accedere a qualsiasi proprietà nel costruttore del menu inizializzato, che includerà this.editor per un'istanza dell'editor di testo principale. Due metodi importanti dell'editor che utilizzerai in questo codelab sono:

  • this.editor.setContent(content) - Imposta i contenuti dell'editor sull'argomento dei contenuti fornito
  • this.editor.content() - Ottiene i contenuti correnti dell'editor

3. Gestisci i file

L'apertura, il salvataggio e la creazione di nuovi file sul computer di un utente sono ora possibili grazie all'API File System Access. In combinazione con l'API File Handling, che consente agli utenti di aprire i file direttamente nella tua PWA, la tua PWA può sembrare perfettamente integrata nella vita quotidiana degli utenti.

Aprire dall'app

La prima azione da collegare è la possibilità di aprire un file dal file system dell'utente all'interno dell'app. In js/lib/actions.js, nel metodo open della classe Actions, scrivi il codice che esegue le seguenti operazioni:

  • Apri un selettore di file che accetta file text/markdown con estensioni .md o .markdown
  • Imposta il titolo della pagina sul nome dei file aperti, più PWA Edit
  • Memorizza il gestore di file in this.handler
  • Imposta i contenuti dell'editor sui contenuti di testo del file
  • Salva l'handler nell'archivio oggetti settings nel database IndexedDB settings-store.

Positivo : ricorda: i costruttori di classi non possono essere funzioni async, ma puoi chiamare le promesse al loro interno.

Ora che puoi aprire un file e salvare il file aperto tra i caricamenti, ci sono altre due cose da fare: impostare di nuovo il gestore quando l'app viene caricata e annullarlo quando l'utente reimposta l'app.

Per eseguire la prima operazione, nel costruttore della classe Actions in js/lib/actions.js, procedi nel seguente modo:

  • Apri il database settings-store
  • Recupera l'handler salvato dall'archivio di oggetti settings
  • Imposta this.handler sul valore recuperato e il titolo della pagina sul nome file del gestore (più PWA Edit) se è presente un gestore salvato

Per reimpostare lo stato dell'app (operazione che può essere eseguita con CTRL/CMD+Shift+R), aggiorna il metodo reset della classe Actions in js/lib/actions.js per eseguire le seguenti operazioni:

  • Imposta il titolo del documento su PWA Edit
  • Imposta i contenuti dell'editor su una stringa vuota
  • Imposta this.handler su null
  • Elimina l'handler salvato dall'archivio oggetti settings

Apri dal file system dell'utente

Ora che puoi aprire un file dalla tua app, dovresti consentire agli utenti di aprire la tua app con il loro file. La registrazione come gestore di file per un dispositivo consente a un utente di aprire i file nella tua app da qualsiasi posizione del file system.

Negativo : per il funzionamento, potrebbe essere necessario attivare una prova di origine o per sviluppatori. Se devi attivare una versione di prova per sviluppatori, ti consigliamo di farlo in una copia di Chrome Canary anziché nel browser normale. Se devi attivare una prova dell'origine, devi registrarti normalmente e aggiungere il tag a index.html

Per iniziare, in manifest.json, aggiungi una voce file_handlers che:

  • Apertura: /
  • Accetta text/markdown con estensioni di file .md o .markdown.

In questo modo gli utenti potranno aprire i file con la tua app, ma non aprirli effettivamente. Per farlo, nella classe Actions in js/lib/actions.js, procedi nel seguente modo:

  • Aggiungi un consumatore window.launchQueue nel costruttore, chiamando this.open con il gestore, se presente.
  • Aggiorna this.open per accettare un gestore di avvio facoltativo
    • Se esiste ed è un'istanza di FileSystemFileHandle, utilizzalo come gestore di file per la funzione
    • In caso contrario, apri il selettore di file.

Dopo aver eseguito entrambe le operazioni sopra descritte, installa la PWA e prova ad aprire un file con questa dal file system.

Salvataggio di un file

Un utente può scegliere tra due percorsi di salvataggio diversi: salvare le modifiche in un file già aperto o salvare in un nuovo file. Con l'API File System Access, il salvataggio in un nuovo file consiste nel creare un nuovo file e recuperare un gestore di file. Per iniziare, salviamo da un gestore esistente.

Nel metodo save della classe Actions in js/lib/actions.js, segui questi passaggi:

  • Recupera il gestore da this.handler o, se non esiste, recupera il gestore salvato dal database
  • Crea il FileSystemWritableFileStream del gestore di file
  • Scrivi i contenuti dell'editor nello stream
  • Chiudere lo stream

Una volta salvato un file, è il momento di implementare il salvataggio con nome. Per farlo, nel metodo saveAs della classe Actions in js/lib/actions.js, segui questi passaggi:

  • Mostra il selettore di salvataggio dei file, descrivendolo come Markdown File e fai in modo che accetti file text/markdown con estensione .md
  • Imposta this.handler sul gestore restituito
  • Salva l'handler nell'archivio oggetti settings
  • Attendi il completamento di this.save per salvare i contenuti nel file appena creato

Una volta fatto, torna al metodo save, controlla se esiste handler prima di provare a scriverci e, in caso contrario, attendi il completamento di this.saveAs.

4. Mostrare un'anteprima

Con un editor Markdown, gli utenti vogliono vedere un'anteprima dell'output di rendering. Utilizzando l'API Window Management, aprirai un'anteprima dei contenuti sottoposti a rendering sullo schermo principale dell'utente.

Prima di iniziare, crea un file js/preview.js e aggiungi il seguente codice per visualizzare un'anteprima quando viene caricato:

import { openDB } from 'idb';
import { marked } from 'marked';

window.addEventListener('DOMContentLoaded', async () => {
  const preview = document.querySelector('.preview');
  const db = await openDB('settings-store');
  const content = (await db.get('settings', 'content')) || '';

  preview.innerHTML = marked(content);
});

L'anteprima dovrebbe comportarsi nei seguenti modi:

  • Quando un utente fa clic sul pulsante di anteprima e non è aperta alcuna anteprima, dovrebbe aprirsi l'anteprima
  • Quando un utente fa clic sul pulsante di anteprima e un'anteprima è aperta, questa deve chiudersi
  • Quando l'utente chiude o aggiorna la PWA, l'anteprima deve chiudersi

Inizia modificando il metodo preview nella classe Actions in js/lib/actions.js per eseguire le seguenti operazioni:

  • Recuperare gli schermi disponibili utilizzando l'API Window Management
  • Filtra le schermate per trovare quella principale.
  • Apri una finestra per /preview con il titolo Markdown preview che occupa metà della larghezza disponibile e tutta l'altezza disponibile dello schermo principale, posizionata in modo da occupare tutta la metà destra disponibile dello schermo. Le dimensioni disponibili escludono le aree riservate dello schermo, come la barra dei menu, la barra degli strumenti, lo stato o la posizione del sistema.
  • Salva questa finestra aperta in this.previewWindow
  • Nella parte superiore del metodo, controlla se esiste this.previewWindow e, in caso affermativo, chiudi la finestra e deseleziona this.previewWindow anziché aprire un'anteprima della finestra.

Infine, esegui le seguenti operazioni alla fine del costruttore della classe Actions in js/lib/actions.js:

  • Chiusura di this.previewWindow durante l'evento beforeunload

5. Concentrazione

Infine, vogliamo offrire agli utenti una modalità di scrittura senza distrazioni. Senza distrazioni non significa solo assenza di disordine dovuto ad altre app, ma anche impedire che lo schermo dell'utente si spenga. Per farlo, utilizzerai l'API Screen Wake Lock.

Il pulsante di blocco della riattivazione funziona come il pulsante di anteprima, alternando lo stato di attivazione e disattivazione. Per farlo, nel metodo focus della classe Actions in js/lib/actions.js, segui questi passaggi:

  • Controlla se il documento contiene un elemento a schermo intero
  • Se è così:
    • Esci da schermo intero
    • Se esiste this.wakeLock, rilascia il wakelock e reimposta this.wakeLock
  • In caso contrario:
    • Richiedi un sentinel di riattivazione e impostalo su this.wakeLock
    • Richiedi che il corpo del documento venga visualizzato a schermo intero.

6. Complimenti!

Hai imparato a gestire i file di sistema e a integrare la tua PWA con un sistema utilizzando l'API File System Access e l'API File Handling, ad aprire finestre su schermi diversi con l'API Window Management e a impedire che uno schermo si spenga con l'API Screen Wake Lock.

Il prossimo codelab della serie è Service Worker Includes