リンクと遷移
ルート表のパターンからhrefでリンクのURLを作り、ふつうの<a>に渡します。ボタンを押したあとなど、コードからページを移るときはnavigateToを使います。
このページの内容
リンク先のURL
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.tsximport { 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を使います。書き方は現在地を見てください。
コードからの遷移
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.tsximport { 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し直します。
ファイルへのリンク
<a download href="/report.pdf">
Download the report
</a>ルート表の最後に/*を置くと、表はどのパスにも一致します。ホストが配信するファイルへのリンクもルーターが扱うので、/report.pdfを開くとファイルでなく/*のページが描画されます。
download属性を付けると、navigateイベントのdownloadRequestがnullでなくなります。ルーターはこのイベントを扱わないので、ファイルがそのまま保存されます。
メモ
@k8ordo/frameworkの下でも、downloadを付けると読み込み直しの往復を省けます。詳しくはデプロイを見てください。