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‚Äč

  • Type: ('appInstalled' | 'mobile' | 'saveData'| 'queryString' | 'always')[]
  • Default: ['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}'],
// ...
},
},
],
],
};

pwaHead‚Äč

  • Type: ({ tagName: string; [attributeName: 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"
}
]
}

Customizing reload popup‚Äč

The @theme/PwaReloadPopup component is rendered when a new service worker is waiting to be installed, and we suggest a reload to the user. You can swizzle this component and implement your own UI. It will receive an onReload callback as props, which should be called when the reload button is clicked. Isso dir√° ao service worker para instalar o service worker em espera e recarregar a p√°gina.

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

pwa_reload.gif

Your component can render null, but this is not recommended: users won't have a way to get up-to-date content.