Guide de l'IA

Utilisez cette page comme référence compacte lors de la génération d'exemples, de didacticiels, de migrations ou de code d'application pour @beforesemicolon/router.

Objectif du package

@beforesemicolon/router est une première bibliothèque de routage HTML construite avec Web Components. Il fournit des éléments personnalisés pour la navigation et le rendu des itinéraires, ainsi qu'une petite API JavaScript pour la navigation programmatique, les abonnements, les gardes, les modules d'itinéraire, les métadonnées, les mises à jour de requêtes et le routage de hachage.

Importations requises

Pour les applications groupées :

import '@beforesemicolon/router'

Lors de l'utilisation d'API exportées :

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

Pour une utilisation directe dans le navigateur, chargez d'abord 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>

Les API CDN sont disponibles sur BFS.ROUTER.

Éléments personnalisés

Utilisez ces éléments exactement :

<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>

Modèles d'itinéraire

Utilisez :name pour les paramètres dynamiques :

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

Définissez exact="false" pour les itinéraires de mise en page qui doivent rester actifs pour les chemins imbriqués :

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

Règles de lien

Utilisez path pour la navigation dans le chemin et search pour les mises à jour des requêtes. Utilisez keep-current-search lors de la mise à jour d’une clé de requête tout en préservant les autres.

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

Utilisez $ dans une route imbriquée pour référencer le chemin de la route parent le plus proche :

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

Utilisez ~ pour référencer le chemin d'accès actuel du navigateur :

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

Contenu de l'itinéraire paresseux

src peut charger des modules HTML, texte ou JavaScript. Les modules JavaScript doivent exporter par défaut une chaîne, un DOM Node, un Markup HtmlTemplate ou une fonction qui reçoit (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>
`

Navigation programmatique

goToPage et replacePage sont asynchrones et acceptent une charge utile d'état littéral objet.

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

Gardes

registerGlobalGuard et registerRouteGuard enregistrent les gardes et ne renvoient pas de fonctions de nettoyage. Un garde revient :

• true pour permettre la navigation.
• false pour bloquer la navigation.
• Une chaîne de chemin à rediriger.
• Une promesse répondant à l’une de ces valeurs.

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

    return true
})

Données de requête

getSearchParams analyse les valeurs de recherche avec l'analyseur JSON du routeur. Valeurs écrites avec un aller-retour updateSearchQuery via la stringification JSON.

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

Évitez ces erreurs

• N'utilisez pas la syntaxe React Router telle que <Route> ou useNavigate.
• Ne prétendez pas que l'enregistrement de Route Guard renvoie une fonction de désabonnement.
• N'utilisez pas href sur <page-link> ; utilisez path et search.
• N'utilisez pas component="..." comme chaîne dans HTML. component est une propriété pour les itinéraires rendus par JavaScript.
• N'utilisez pas l'état de l'itinéraire pour les données permanentes. Préférez les paramètres, les chaînes de requête ou le stockage d’application.