المحتويات

المسارات
المعاملات الديناميكية

التوجيه والتنقل

التوجيه في Carats بيانات، لا نظام ملفات. كل مسار مصرَّح عنه في كائن أوجه واحد يشترك فيه العميل والخادم.

المسارات

تنتقل خريطة المسارات من نمط مسار إلى مكوّن صفحة. ويُطابَق النمط بدقة، باستثناء المقاطع التي تبدأ بنقطتين، فهي تلتقط معاملًا.

// 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
});

اسم مجلد الصفحة عُرف وليس شرطًا. فالمجلد يُبقي الملفات المترابطة معًا، لكن المسار الذي يخدمه المجلد هو أي سلسلة يُربط بها، لذا يمكن لـ `/market` أن يعيش في مجلد اسمه `browse` إن كان ذلك يقرأ أفضل.

المعاملات الديناميكية

يصبح المقطع ‎:name‎ خاصًا على مكوّن الصفحة، وهو متاح أيضًا كـ params.name داخل دالة خادمية للمسار نفسه. ويجب أن يتطابق الاسم في الجهتين.

// 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` يُصيّر هذه الصفحة مع ‏`data.symbol`‎ المحلولة من الدالة الخادمية المسجَّلة للمسار نفسه، وتُنتج الصفحة عنوان `` مختلفًا لكل رمز. ويقوم الإطار بعملية المطابقة في `getPageComponent` التي تُعيد المكوّن و`params` المستخرجة والمسار `route` المطابَق.<blockquote>تُطابَق أنماط المسارات بواسطة ‎@carats/url‎ مع matchRoute. لا توجد علامة نجمة، ولا مقطع اختياري، ولا التقاط شامل: مسار غير مطابَق يُصيّر مكوّن تعليق notFound بدلًا من ذلك.</blockquote><h2>التوجيه داخل التطبيق</h2>مع تفعيل inAppRouting، يتدخّل العميل في نقرات الروابط الداخلية ويبدّل الصفحة دون تحميل كامل. ويتطلب ذلك أيضًا clientRender() في نقطة دخول العميل. أوقفه عندما تعتمد صفحة على تحميل مستند كامل، مثل صفحة يجب أن تُشغّل سكربت طرف ثالث في كل تنقل.<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>كلا السطرين مطلوب عندما يكون التوجيه داخل التطبيق مُفعَّلًا. ‏`mount` يسجّل الأوجه في المتصفح، و`clientRender` يبدأ التدخل في التنقل.لا تحتاج الروابط إلى مكوّن من الإطار. يُتدخَّل في الوسم المرساة العادي تلقائيًا، ويُتبع الرابط الطبيعي بشكل طبيعي إن عُطِّل التدخل، ما يعني أن تبقى الصفحات قابلة للزحف وتعمل دون JavaScript.<h2>التنقل البرمجي</h2>ينتقل ‏goTo‎ من ‎@carats/csr‎ بالطريقة نفسها التي ينتقل بها النقر على رابط مُتدخَّل فيه. وهو الطريق الصحيح لإرسال مربع بحث أو أي نموذج آخر لا ينبغي أن يُعيد تحميل المستند.<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>ابنِ سلسلة الاستعلام باستخدام ‏`URLSearchParams`‎ القياسية التي تتولى الترميز نيابةً عنك. ولقراءة معاملات المسار الحالي من مكوّن، اسأل دالةً خادمية عنها: تتلقى الدالة الخادمية المعاملات المطابَقة في ‏`req.params`‎، وتستقبل الصفحة ما أعادته الدالة الخادمية.<h2>حالات تعليق التصيير</h2>توفّر خريطة suspense المكونات المستخدمة عندما لا يستطيع مسار إنتاج صفحة: notFound لمسار غير مطابَق، وerror لمكوّن أو دالة خادمية ألقت خطأ. كلاهما اختياري، وerror يتلقى Error المُلقى كوسيطه الوحيد.<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>غلِّف الاثنين في التخطيط المشترك. فالصفحة الفاشلة التي تُصيَّر دون هيكل الموقع أصعب بكثير في التشخيص من واحدة تحتفظ بالترويسة والتنقل.</div> </article> </main> <footer> ◆ carats · التوثيق</footer> </div> <script src="/static/js/ui.js"></script> <script type="module" src="/static/js/search.js" defer></script> </body></html>