Contenido

Rutas
Parámetros dinámicos

Enrutamiento y navegación

El enrutamiento en Carats son datos, no un sistema de archivos. Cada ruta se declara en un único objeto de facetas que comparten el cliente y el servidor.

Rutas

El mapa de rutas va de un patrón de ruta a un componente de página. El patrón se compara de forma exacta, salvo en los segmentos que empiezan por dos puntos, que capturan un parámetro.

// src/client/facets.cara.ts
import { defineFacets } from '@carats/render';
import ErrorPage from './pages/_error';
import NotFound from './pages/_not_found';
import Home from './pages/home';
import Market from './pages/market';
import Profile from './pages/profile';
import Trade from './pages/trade';

export default defineFacets({
    routes: {
        '/': Home,
        '/profile': Profile,
        '/market': Market,
        '/trade/:symbol': Trade
    },
    suspense: {
        error: ErrorPage,
        notFound: NotFound
    },
    inAppRouting: true
});

El nombre de la carpeta de una página es una convención, no un requisito. La carpeta mantiene juntos los archivos relacionados, pero la ruta que sirve una carpeta es la cadena a la que esté mapeada, así que /market puede vivir en una carpeta llamada browse si se lee mejor.

Parámetros dinámicos

Un segmento :name se convierte en una prop del componente de página, y también está disponible como params.name dentro de un culet de la misma ruta. El nombre debe coincidir en ambos lados.

// src/client/pages/trade/index.tsx
import { Burnish } from '@carats/render';
import Layout from '../_layout';
import './trade.sass';

export default Burnish<TradeData>(function (data) {
    this.head = <title>Trade {data.symbol}</title>;
    return (
        <Layout>
            <h1>{data.symbol}</h1>
        </Layout>
    );
});

`/trade/btc` renderiza esta página con `data.symbol` resuelto a partir del culet registrado para la misma ruta, y la página renderiza un `` distinto para cada símbolo. El framework hace la comparación en `getPageComponent`, que devuelve el componente, los `params` extraídos y la `route` coincidente.<blockquote>Los patrones de ruta los compara @carats/url con matchRoute. No hay comodín, ni segmento opcional, ni patrón que capture todo: una URL sin coincidencia renderiza el componente de suspensión notFound.</blockquote><h2>Enrutamiento dentro de la aplicación</h2>Con inAppRouting activado, el cliente intercepta los clics en anclas internas y cambia de página sin una carga completa. También requiere clientRender() en el punto de entrada del cliente. Desactívalo cuando una página dependa de una carga completa del documento, por ejemplo una que deba ejecutar un script de terceros en cada navegación.<pre><code class="hljs language-typescript">// src/client/entrypoint.tsimport { mount, clientRender } from '@carats/csr';import facets from './facets.cara';mount(facets);clientRender();</code></pre>Hacen falta las dos líneas cuando el enrutamiento dentro de la aplicación está activo. mount registra las facetas en el navegador, y clientRender empieza a interceptar la navegación.Los enlaces no necesitan ningún componente del framework. Un ancla normal se intercepta automáticamente, y un enlace corriente se sigue con normalidad si la interceptación está desactivada, lo que significa que las páginas siguen siendo rastreables y funcionan sin JavaScript.<h2>Navegación programática</h2>goTo de @carats/csr navega del mismo modo que un clic en un enlace interceptado. Es la forma correcta de enviar un cuadro de búsqueda o cualquier otro formulario que no deba recargar el documento.<pre><code class="hljs language-tsx">import { goTo } from '@carats/csr';import { afterMount } from '@carats/hooks';import './search-bar.sass';export default function SearchInput() { afterMount(() => { const form=document.getElementById('search-bar'); const submit=(e: Event) => { e.preventDefault(); const input=document.getElementById('search-input') as HTMLInputElement; goTo(`/search?q=${input.value}`); }; form?.addEventListener('submit', submit); return () => form?.removeEventListener('submit', submit); }); return ( <form id="search-bar"> <input id="search-input" name="q" type="text" /> </form> );}</code></pre>Construye la cadena de consulta con el URLSearchParams estándar, que se encarga de la codificación por ti. Para leer los parámetros de la ruta actual desde un componente, pídeselos a un culet: un culet recibe los parámetros coincidentes en req.params, y la página recibe lo que el culet devolvió.<h2>Estados de suspensión</h2>El mapa suspense aporta los componentes que se usan cuando una ruta no puede producir una página: notFound para una URL sin coincidencia y error para un componente o culet que lanzó una excepción. Ambos son opcionales, y error recibe el Error lanzado como único argumento.<pre><code class="hljs language-tsx">// src/client/pages/_not_found/index.tsximport Layout from '../_layout';import './notfound.sass';export default function NotFound() { return ( <Layout> <section class="notfound-page container"> <div class="notfound-code">404</div> <h1>Page not found</h1> <a href="/" class="btn btn-primary">Return to Dashboard</a> </section> </Layout> );}</code></pre><pre><code class="hljs language-tsx">// src/client/pages/_error/index.tsximport Layout from '../_layout';import './error.sass';export default function ErrorPage(error: Error) { return ( <Layout> <section class="error-page container"> <h1>Something went wrong</h1> <p class="error-message">{error.message}</p> <a href="/" class="btn btn-primary">Return to Dashboard</a> </section> </Layout> );}</code></pre>Envuelve ambos en el diseño compartido. Una página que falla y se renderiza sin el armazón del sitio es mucho más difícil de diagnosticar que otra que conserva la cabecera y la navegación.</div> </article> </main> <footer> ◆ carats · documentación</footer> </div> <script src="/static/js/ui.js"></script> <script type="module" src="/static/js/search.js" defer></script> </body></html>