Guia e Boas Práticas

O Router funciona melhor quando a URL é tratada como fonte da verdade para navegação, filtros, abas e estados de interface compartilháveis. Mantenha as declarações de rota próximas ao layout que controlam e use a API JavaScript somente para comportamentos que não possam ser expressos de forma clara em HTML.

Comece com rotas declarativas

Para a maioria das páginas, use <page-route>, <page-link> e <page-redirect> diretamente no documento. Assim, a aplicação pode ser compreendida apenas pela estrutura HTML.

html
<nav>
    <page-link path="/" title="Home">Home</page-link>
    <page-link path="/projects" title="Projects">Projects</page-link>
    <page-link path="/settings" title="Settings">Settings</page-link>
</nav>

<main>
    <page-route path="/" src="./pages/home.html"></page-route>
    <page-route
        path="/projects"
        exact="false"
        src="./pages/projects.js"
    ></page-route>
    <page-route path="/settings" src="./pages/settings.html"></page-route>
    <page-route path="/404">Page not found.</page-route>
    <page-redirect path="/404"></page-redirect>
</main>

Use rotas aninhadas para layouts

Rotas pai são úteis para seções que compartilham navegação, títulos ou dados de rota. Caminhos filhos estendem a rota pai mais próxima.

html
<page-route path="/projects/:projectId" exact="false">
    <header>
        <h1>Project <page-data param="projectId">unknown</page-data></h1>
        <page-link path="$/overview">Overview</page-link>
        <page-link path="$/activity">Activity</page-link>
        <page-link path="$/settings">Settings</page-link>
    </header>

    <page-route path="/overview" src="./projects/overview.js"></page-route>
    <page-route path="/activity" src="./projects/activity.html"></page-route>
    <page-route path="/settings" src="./projects/settings.js"></page-route>
    <page-redirect path="$/overview" type="always"></page-redirect>
</page-route>

Use rotas de consulta para o estado da interface

Use <page-route-query> quando a visualização continuar na mesma página, mas um valor de consulta precisar escolher uma aba, gaveta, filtro ou modal.

html
<page-link search="panel=details" keep-current-search>Details</page-link>
<page-link search="panel=activity" keep-current-search>Activity</page-link>

<page-route-query key="panel" value="details">
    <h2>Details</h2>
</page-route-query>

<page-route-query key="panel" value="activity" src="./panels/activity.html">
    <p slot="loading">Loading activity...</p>
</page-route-query>

Prefira component em aplicações tipadas

Se você renderiza rotas com código Markup ou Web Component, a propriedade component evita imports dinâmicos baseados em strings e fornece uma referência direta aos bundlers.

javascript
import { html } from '@beforesemicolon/web-component'
import HomePage from './pages/HomePage.js'
import ProjectPage from './pages/ProjectPage.js'

export const routes = html`
    <page-route path="/" component="${HomePage}"></page-route>
    <page-route
        path="/projects/:projectId"
        component="${ProjectPage}"
    ></page-route>
`

Registre guards antes da navegação

Guards executam antes que listeners de rota e componentes de rota sejam notificados. Registre-os durante a inicialização da aplicação, antes de renderizar rotas protegidas ou iniciar uma navegação.

javascript
import {
    registerGlobalGuard,
    registerRouteGuard,
} from '@beforesemicolon/router'

registerGlobalGuard((pathname) => {
    if (pathname.startsWith('/account') && !session.currentUser) {
        return '/login'
    }

    return true
})

registerRouteGuard('/admin/:section', async () => {
    return (await session.hasRole('admin')) || '/unauthorized'
})

Mantenha páginas 404 por último

<page-redirect> verifica as rotas que já foram registradas. Coloque redirecionamentos de fallback depois das declarações válidas de <page-route> das quais dependem.

html
<page-route path="/">Home</page-route>
<page-route path="/docs" exact="false">Docs</page-route>
<page-route path="/404">Not found</page-route>

<page-redirect path="/404"></page-redirect>

Escolha o roteamento History ou Hash desde o início

O roteamento History fornece URLs limpas e é o padrão. O roteamento Hash é útil quando o provedor de hospedagem não consegue reescrever caminhos desconhecidos para index.html.

javascript
import { setRoutingMode } from '@beforesemicolon/router'

setRoutingMode('hash')

Checklist de produção

<< InstalaçãoGuia para IA >>
editar este documento