@k8ordo/router

リンクと遷移

ルート表のパターンからhrefでリンクのURLを作り、ふつうの<a>に渡します。ボタンを押したあとなど、コードからページを移るときはnavigateToを使います。

このページの内容

リンク先のURL

ts
href('/products'); // '/products'
href('/products/:id', { id: '42' }); // '/products/42'
href('/products/:id', { id: 42 }); // '/products/42'
href('/products/:id', { id: 'a/b' }); // '/products/a%2Fb'

hrefは、パターンとparamからURLの文字列を作ります。paramの無いパターンには、2つ目の引数を渡しません。

paramの値には、文字列のほかに数値とbigintと真偽値を渡せます。値はencodeURIComponentで符号化されるので、/を含む値もパスの1つの区間になります。

返り値は、<a>のhref属性にそのまま渡せます。アプリをベースパスの下で配信しているときは、ベースパスが先頭に付きます。詳しくはベースパスを見てください。

情報

メモ

型エラーを無視して呼ぶと、次の3つの場合に実行時にTypeErrorになります。

  • /*を含むパターン:is a wildcard — it has no href
  • 値の無いparam:needs a value for ":id"
  • オブジェクトなど、URLに書けない値:has no URL spelling

リンクの書き方

src/product-card.tsx
import { href } from '@k8ordo/router';

type Props = { id: string; name: string };

export function ProductCard({ id, name }: Props) {
  return <a href={href('/products/:id', { id })}>{name}</a>;
}

このルーターに<Link>コンポーネントはありません。<a>をクリックするとブラウザがnavigateイベントを発火し、ルーターがそれを受け取ってページを切り替えます。パターンの検査はhrefが行うので、リンクは<a>のまま書きます。

ほかのオリジンやルート表に無いパスへのリンクは、ブラウザがふつうに読み込みます(仕組み)。

今開いているページへのリンクに印を付けるには、useMatchを使います。書き方は現在地を見てください。

ts
navigateTo('/products/:id', { id: '42' });
navigateTo('/products/:id', { id: '42' }, { history: 'replace' });
navigateTo('/products');
navigateTo('/products', { history: 'replace' });

navigateToは、hrefと同じ引数でURLを作り、そのページへ移ります。既定では履歴に新しいエントリを追加するので、ブラウザの戻るボタンで前のページに戻れます。

今のエントリを置き換えるには、{ history: 'replace' }を渡します。paramの無いパターンでは、オプションが2つ目の引数になります。

ページの中の状態だけを変えるときは、@k8ordo/stateのupdate()を使います。詳しくはURLを見てください。

finishedの待ち方

src/open-button.tsx
import { navigateTo } from '@k8ordo/router';
import { useTransition } from 'react';

const isAbort = (error: unknown) =>
  error instanceof DOMException && error.name === 'AbortError';

export function OpenButton({ id }: { id: string }) {
  const [isPending, startTransition] = useTransition();
  const open = () => {
    startTransition(async () => {
      try {
        await navigateTo('/products/:id', { id }).finished;
      } catch (error) {
        if (!isAbort(error)) throw error;
      }
    });
  };

  return (
    <button disabled={isPending} onClick={open} type="button">
      {isPending ? 'Opening…' : 'Open'}
    </button>
  );
}

navigateToは、Navigation APIのnavigation.navigate()と同じ{ committed, finished }を返します。finishedは、新しいページが画面に表示されたときに解決します。

useTransitionのアクションの中でfinishedを待つと、ページが表示されるまでisPendingがtrueになります。

待っている間に別のナビゲーションが始まると、finishedはAbortErrorという名前のDOMExceptionでrejectします。例のように中断だけを無視して、ほかのエラーはthrowし直します。

ファイルへのリンク

tsx
<a download href="/report.pdf">
  Download the report
</a>

ルート表の最後に/*を置くと、表はどのパスにも一致します。ホストが配信するファイルへのリンクもルーターが扱うので、/report.pdfを開くとファイルでなく/*のページが描画されます。

download属性を付けると、navigateイベントのdownloadRequestがnullでなくなります。ルーターはこのイベントを扱わないので、ファイルがそのまま保存されます。

情報

メモ

@k8ordo/frameworkの下でも、downloadを付けると読み込み直しの往復を省けます。詳しくはデプロイを見てください。

k8ordo

Baselineに入った機能を、制限なく使うReactのライブラリ群。