Guía de IA

Utilice esta página como referencia compacta al generar ejemplos, tutoriales, migraciones o código de aplicación para @beforesemicolon/router.

Propósito del paquete

@beforesemicolon/router es la primera biblioteca de enrutamiento HTML creada con Web Components. Proporciona elementos personalizados para navegación y representación de rutas, además de una pequeña API JavaScript para navegación programática, suscripciones, guardias, módulos de ruta, metadatos, actualizaciones de consultas y enrutamiento hash.

Importaciones requeridas

Para aplicaciones incluidas:

import '@beforesemicolon/router'

Al utilizar API exportadas:

import {
    goToPage,
    onPage,
    onPageChange,
    registerGlobalGuard,
    registerRouteGuard,
    registerRouteModules,
    updateSearchQuery,
} from '@beforesemicolon/router'

Para uso directo del navegador, cargue primero Web Component:

<script src="https://unpkg.com/@beforesemicolon/web-component/dist/client.js"></script>
<script src="https://unpkg.com/@beforesemicolon/router/dist/client.js"></script>

Las API de CDN están disponibles en BFS.ROUTER.

Elementos personalizados

Utilice estos elementos exactamente:

<page-link path="/docs" title="Docs">Docs</page-link>
<page-route path="/docs" src="./pages/docs.html"></page-route>
<page-route-query key="tab" value="api">API tab</page-route-query>
<page-redirect path="/404"></page-redirect>
<page-data param="id">fallback</page-data>

Patrones de ruta

Utilice :name para parámetros dinámicos:

<page-route path="/users/:userId">
    User <page-data param="userId">unknown</page-data>
</page-route>

Configure exact="false" para rutas de diseño que deben permanecer activas para rutas anidadas:

<page-route path="/docs" exact="false">
    <page-route path="/intro">Intro</page-route>
    <page-route path="/api">API</page-route>
</page-route>

Reglas de enlace

Utilice path para navegación de rutas y search para actualizaciones de consultas. Utilice keep-current-search al actualizar una clave de consulta y conservar las demás.

<page-link path="/projects">Projects</page-link>
<page-link search="view=grid" keep-current-search>Grid</page-link>

Utilice $ dentro de una ruta anidada para hacer referencia a la ruta principal más cercana:

<page-route path="/projects/:projectId" exact="false">
    <page-link path="$/settings">Settings</page-link>
</page-route>

Utilice ~ para hacer referencia a la ruta actual del navegador:

<page-link path="~/edit">Edit current page</page-link>

Contenido de ruta diferida

src puede cargar módulos HTML, texto o JavaScript. Los módulos JavaScript deben exportar de forma predeterminada una cadena, un DOM Node, un Markup HtmlTemplate o una función que reciba (data, params, query).

import { html } from '@beforesemicolon/web-component'

export default (data, params, query) => html`
    <h1>Project ${params.projectId}</h1>
    <p>Filter: ${query.filter || 'all'}</p>
    <p>Opened from: ${data.from || 'direct visit'}</p>
`

Navegación programática

goToPage y replacePage son asíncronos y aceptan una carga útil de estado literal de objeto.

await goToPage('/users/42', { from: 'search' }, 'User 42')
await replacePage('/login', { reason: 'expired' }, 'Login')

guardias

registerGlobalGuard y registerRouteGuard registran guardias y no devuelven funciones de limpieza. Un guardia regresa:

• true para permitir la navegación.
• false para bloquear la navegación.
• Una cadena de ruta para redirigir.
• Una promesa que responde a uno de esos valores.

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

    return true
})

Consultar datos

getSearchParams analiza los valores de búsqueda con el analizador del enrutador JSON. Valores escritos con updateSearchQuery de ida y vuelta a través de la cadena JSON.

updateSearchQuery({ page: 2, tags: ['router', 'web'] })

Evite estos errores

• No utilice la sintaxis de React Router como <Route> o useNavigate.
• No reclamar que el registro de guardia de ruta devuelva una función de cancelación de suscripción.
• No utilice href en <page-link>; utilice path y search.
• No utilice component="..." como cadena en HTML. component es una propiedad para rutas renderizadas por JavaScript.
• No utilice el estado de ruta para datos permanentes. Prefiere parámetros, cadenas de consulta o almacenamiento de aplicaciones.