Ir para o conte√ļdo principal
Version: 2.0.0-beta.21 ūüöß

ūüď¶ plugin-pwa

Plugin Docusaurus para adicionar suporte à PWA usando [Workbox](https://developers. google. com/web/tools/workbox). Este plugin gera um Service Worker somente na compilação de produção, e permite que você crie um site de documentação compatível com PWA, com suporte offline e instalação.

Instala√ß√£o‚Äč

npm install --save @docusaurus/plugin-pwa

Configura√ß√£o‚Äč

Crie um manifesto PWA em ./static/manifest.json.

Modifique docusaurus.config.js com uma configuração PWA mínima, como:

docusaurus.config.js
module.exports = {
plugins: [
[
'@docusaurus/plugin-pwa',
{
debug: true,
offlineModeActivationStrategies: [
'appInstalled',
'standalone',
'queryString',
],
pwaHead: [
{
tagName: 'link',
rel: 'icon',
href: '/img/docusaurus.png',
},
{
tagName: 'link',
rel: 'manifest',
href: '/manifest.json', // your PWA manifest
},
{
tagName: 'meta',
name: 'theme-color',
content: 'rgb(37, 194, 160)',
},
],
},
],
],
};

App Web Progressivo‚Äč

Ter um worker de servi√ßo instalado n√£o √© suficiente para fazer da sua aplica√ß√£o um PWA. Voc√™ precisa incluir pelo menos um manifesto do Web App e ter as tags corretas em <head> (Op√ß√Ķes > pwaHead).

Após a implantação, você pode usar Farol para executar uma auditoria no seu site.

Para uma lista mais exaustiva do que é preciso para o seu site ser um PWA, consulte a Checklist PWA

Suporte para instala√ß√£o do aplicativo‚Äč

Se seu navegador suporta isso, você deve ser capaz de instalar um site do Docusaurus como um aplicativo.

pwa_install.gif

note

A instalação de aplicativos requer o protocolo https e um manifesto válido.

Modo off-line (sobreposi√ß√£o)‚Äč

Permite que os usuários navegue em um site do Docusaurus off-line, usando a predefinição do colaborador do serviço.

O que √© Precaching?‚Äč

Uma das caracter√≠sticas dos workers do servi√ßo √© a capacidade de salvar um conjunto de arquivos no cache quando o trabalhador do servi√ßo estiver instalando. Isso √© frequentemente referido como "precurso", j√° que voc√™ est√° fazendo cache de conte√ļdo √† frente do trabalhador do servi√ßo sendo usado.

A principal razão para fazer isso é que ele dá aos desenvolvedores controle sobre o cache, significando que eles podem determinar quando e por quanto tempo um arquivo é armazenado em cache e também servi-lo para o navegador sem ir para a rede, o que significa que pode ser usado para criar aplicativos web que trabalham offline.

Caixa de trabalho leva muito do trabalho para fora do processo de perfuração, simplificando a API e garantindo que os ativos sejam baixados eficientemente.

Por padrão, o modo offline é ativado quando o site é instalado como um aplicativo. Consulte a opção offlineModeActivationStrategies para obter detalhes.

Depois que o site for precedido, o trabalhador do servi√ßo ir√° servir respostas em cache para visitas posteriores. Quando uma nova compila√ß√£o √© implantada junto com um novo funcion√°rio, o novo vai come√ßar a instalar e eventualmente passar para um estado de espera. Durante este estado de espera, um pop-up de recarga ser√° exibido e pedir√° ao usu√°rio para recarregar a p√°gina para um novo conte√ļdo. At√© que o usu√°rio limpe o cache do aplicativo ou clica no bot√£o de recarregar `` no popup, o trabalhador dos servi√ßos continuar√° a servir o conte√ļdo antigo.

caution

Modo Offline / precaching requer baixar todos os recursos est√°ticos do site antes do tempo, e pode consumir largura de banda desnecess√°ria. Poder√° n√£o ser uma boa ideia activ√°-la para todo o tipo de sites.

Op√ß√Ķes‚Äč

debug‚Äč

  • Tipo: boolean
  • Padr√£o: false

Ativar modo depuração:

  • Registros de workbox
  • Logs adicionais do Docusaurus
  • Sa√≠da de arquivo SW n√£o otimizada
  • Mapas de origem

offlineModeActivationStrategies‚Äč

  • Tipo: Array<'appInstalled' | 'mobile' | 'saveData'| 'queryString' | 'always'>
  • Padr√£o: ['appInstalled','queryString','standalone']

Estratégias usadas para ativar o modo offline em:

  • appInstalled: ativa para usu√°rios que instalaram o site como um aplicativo (n√£o 100% confi√°vel)
  • standalone: ativa para usu√°rios que executam o aplicativo como standalone (muitas vezes o caso, uma vez que um PWA √© instalado)
  • queryString: ativa se queryString cont√©m offlineMode=true (conveniente para depura√ß√£o de PWA)
  • mobile: ativa para usu√°rios de dispositivos m√≥veis (largura <= 940px)
  • saveData: ativa para usu√°rios com navigator.connection.saveData === true
  • always: ativa para todos os usu√°rios
caution

Use com cuidado: alguns usuários podem não gostar de ser forçados a usar o modo offline.

danger

Não é possível detectar se um é um PWA de uma forma muito confiável.

O evento appinstalled foi removido da especifica√ß√£o e o navigator.getInstalledRelatedApps() API s√≥ √© compat√≠vel com as vers√Ķes recentes do Chrome e requer related_applications declarado no manifesto.

A estratégia standalone é um bom substituto para ativar a modo offline (pelo menos ao executar o aplicativo instalado).

injectManifestConfig‚Äč

Op√ß√Ķes da caixa de trabalho para passar para workbox.injectManifest(). Ele fornece controle sobre quais arquivos ser√£o precedidos e dispon√≠veis offline.

  • Tipo: InjectManifestOptions
  • Padr√£o: {}
docusaurus.config.js
module.exports = {
plugins: [
[
'@docusaurus/plugin-pwa',
{
injectManifestConfig: {
manifestTransforms: [
//...
],
modifyURLPrefix: {
//...
},
// We already add regular static assets (html, images...) to be available offline
// You can add more files according to your needs
globPatterns: ['**/*.{pdf,docx,xlsx}'],
// ...
},
},
],
],
};

reloadPopup‚Äč

  • Tipo: string | false
  • Padr√£o: '@theme/PwaReloadPopup'

Caminho do módulo para recarregar o componente pop-up. Este pop-up é renderizado quando um novo trabalhador de serviços está esperando para ser instalado, e sugerimos uma recarga para o usuário.

Passando false ir√° desativar o popup, mas isto n√£o √© recomendado: os usu√°rios n√£o ter√£o uma maneira de ter conte√ļdo atualizado.

Um componente personalizado pode ser usado, contanto que aceite onReload como uma prop. O retorno de chamada onReload deve ser chamado quando o botão reload é clicado. Isso dirá ao service worker para instalar o service worker em espera e recarregar a página.

interface PwaReloadPopupProps {
onReload: () => void;
}

O tema padrão inclui uma implementação para o pop-up de recarga e usa Infima Alerts.

pwa_reload.gif

pwaHead‚Äč

  • Tipo: Array<{ tagName: string } & Record<string,string>>
  • Padr√£o: []

Array de objetos contendo tagName e pares chave-valor para atributos injetar na tag <head>. Tecnicamente, você pode injetar qualquer tag head através disto, mas é idealmente usado para tags para tornar o PWA compatível com seu site. Aqui está uma lista de tags para tornar seu aplicativo totalmente compatível:

module.exports = {
plugins: [
[
'@docusaurus/plugin-pwa',
{
pwaHead: [
{
tagName: 'link',
rel: 'icon',
href: '/img/docusaurus.png',
},
{
tagName: 'link',
rel: 'manifest',
href: '/manifest.json',
},
{
tagName: 'meta',
name: 'theme-color',
content: 'rgb(37, 194, 160)',
},
{
tagName: 'meta',
name: 'apple-mobile-web-app-capable',
content: 'yes',
},
{
tagName: 'meta',
name: 'apple-mobile-web-app-status-bar-style',
content: '#000',
},
{
tagName: 'link',
rel: 'apple-touch-icon',
href: '/img/docusaurus.png',
},
{
tagName: 'link',
rel: 'mask-icon',
href: '/img/docusaurus.svg',
color: 'rgb(37, 194, 160)',
},
{
tagName: 'meta',
name: 'msapplication-TileImage',
content: '/img/docusaurus.png',
},
{
tagName: 'meta',
name: 'msapplication-TileColor',
content: '#000',
},
],
},
],
],
};

swCustom‚Äč

  • Tipo: string | undefined
  • Padr√£o: undefined

Útil para regras adicionais da caixa de trabalho. Você pode fazer tudo o que um service worker pode fazer aqui e usar todo o poder das bibliotecas da caixa de trabalho. O código foi transpilado, então você pode usar a sintaxe moderna ES6+ aqui.

Por exemplo, para armazenar em cache arquivos de rotas externas:

import {registerRoute} from 'workbox-routing';
import {StaleWhileRevalidate} from 'workbox-strategies';

// default fn export receiving some useful params
export default function swCustom(params) {
const {
debug, // :boolean
offlineMode, // :boolean
} = params;

// Cache responses from external resources
registerRoute((context) => {
return [
/graph\.facebook\.com\/.*\/picture/,
/netlify\.com\/img/,
/avatars1\.githubusercontent/,
].some((regex) => context.url.href.match(regex));
}, new StaleWhileRevalidate());
}

O m√≥dulo deve ter um default de exporta√ß√£o de fun√ß√£o, e receber alguns par√Ęmetros.

swRegister‚Äč

  • Tipo: string | false
  • Padr√£o: 'docusaurus-plugin-pwa/src/registerSW.js'

Adiciona uma entrada antes do aplicativo Docusaurus para que o registro possa acontecer antes que o aplicativo seja executado. O arquivo padrão registerSW.js é suficiente para um simples registro.

Passar false desativar√° o registro completamente.

Exemplo de manifesto‚Äč

O manifesto do site Docusaurus pode servir como inspiração:

{
"name": "Docusaurus v2",
"short_name": "Docusaurus",
"theme_color": "#2196f3",
"background_color": "#424242",
"display": "standalone",
"scope": "./",
"start_url": "./index.html",
"related_applications": [
{
"platform": "webapp",
"url": "https://docusaurus.io/manifest.json"
}
],
"icons": [
{
"src": "img/icons/icon-72x72.png",
"sizes": "72x72",
"type": "image/png"
},
{
"src": "img/icons/icon-96x96.png",
"sizes": "96x96",
"type": "image/png"
},
{
"src": "img/icons/icon-128x128.png",
"sizes": "128x128",
"type": "image/png"
},
{
"src": "img/icons/icon-144x144.png",
"sizes": "144x144",
"type": "image/png"
},
{
"src": "img/icons/icon-152x152.png",
"sizes": "152x152",
"type": "image/png"
},
{
"src": "img/icons/icon-192x192.png",
"sizes": "192x192",
"type": "image/png"
},
{
"src": "img/icons/icon-384x384.png",
"sizes": "384x384",
"type": "image/png"
},
{
"src": "img/icons/icon-512x512.png",
"sizes": "512x512",
"type": "image/png"
}
]
}