@k8ordo/router

ルート表

defineRoutesでルート表を書き、どのパスがどのページになるかを決められるようになります。

このページの内容

ページとレイアウト

src/routes.ts
export const routes = defineRoutes({
  '/': Home,
  '/products': {
    layout: ProductsLayout,
    children: {
      '/': ProductList,
      '/:id': ProductPage,
    },
  },
});

ルート表の値は、ページのコンポーネントか、childrenを持つオブジェクトです。オブジェクトは下のページをまとめ、layoutがあればそのコンポーネントで包みます。

childrenのキーは、親のパターンに続けて読みます。/:idは/products/:idのページで、/は/productsのページです。/products/42を開くと、ProductsLayoutの<Outlet />の位置にProductPageが表示されます。

オブジェクトは入れ子にでき、レイアウトも外側から順に入れ子になります。末尾のスラッシュは無いものとして照合するので、/products/は/productsと同じページです。

情報

メモ

オブジェクトにはerrorとloadingも書けます。書き方はエラーと読み込み中を見てください。

パスのparam

ts
const routes = defineRoutes({ '/products/:id': ProductPage });

routes.match('/products/42')?.params; // { id: '42' }
routes.match('/products/a%2Fb')?.params; // { id: 'a/b' }
routes.match('/products/a/b'); // null
routes.match('/products/'); // null

:nameの区間は、パスのその位置にある文字列を受け取ります。受け取るのは空でない1区間だけで、/をまたぎません。値はデコードされるので、%2Fは/に戻ります。

paramの型はパターンの文字列から決まります。/:locale/products/:idなら{ locale: string; id: string }です。

matchは、<Router>が内部で行う照合をそのまま呼ぶ関数です。ブラウザが無くても動くので、パスがどのページになるかをこうして確かめられます。

/*

ts
const routes = defineRoutes({
  '/': Home,
  '/products/:id': ProductPage,
  '/*': NotFound,
});

routes.match('/products/42/reviews')?.pattern; // '/*'
routes.match('/no/such/page')?.pattern; // '/*'

/*は、それより前のどのパターンにも合わなかったパスに合います。:nameと違って区間の数を問いません。/*に合った部分はparamsに入りません。

/products/*のように前に区間を付けて書くと、/productsより下のパスだけに合います。/productsそのものには合いません。

/*は照合のためのパターンで、リンク先にはなりません。hrefに渡すと、実行時にTypeErrorになります("/*" is a wildcard — it has no href)。

警告

落とし穴

表の最後に/*を置くときは、ファイルへのリンクにdownload属性を付けます。詳しくはリンクと遷移を見てください。

グループ

src/routes.ts
export const routes = defineRoutes({
  '/(marketing)': {
    layout: MarketingLayout,
    children: {
      '/': Home,
      '/pricing': Pricing,
    },
  },
  '/(docs)': {
    layout: DocsLayout,
    children: { '/guide': Guide },
  },
});

/(name)のキーはグループです。下のページをレイアウトで包みますが、パスには何も足しません。/pricingはMarketingLayoutの中に、/guideはDocsLayoutの中に表示されます。

グループは、同じ深さにある2つのまとまりに別々のレイアウトを付けるときに使います。1つのオブジェクトに/のキーは1度しか書けないので、/のオブジェクトを2つ並べられません。

照合の順序

ts
defineRoutes({
  '/products/:id': ProductPage,
  '/products/new': NewProduct,
このパターンが選ばれることはない
});

照合は表を上から順にたどり、最初に合ったパターンを選びます。具体的なパターンを優先する規則は無く、書いた順がそのまま優先順位です。この順では/products/newも/products/:idに合い、idが'new'のProductPageが表示されます。

ts
defineRoutes({
  '/products/new': NewProduct,
  '/products/:id': ProductPage,
});

決まった区間のパターンを先に書けば、/products/newはNewProductになります。/*を最後に置くのも同じ理由です。

表に無いパス

/*を置かない表では、どのパターンにも合わないパスがあります。<Router>はそのパスへの移動を処理しません。ブラウザが通常どおりページを読み込み、サーバーが返す404が表示されます。

表に無いパスでアプリを開いたとき、<Router>は何も表示しません。

拒まれる書き方

ルート表は、defineRoutesを呼んだ時点で検査されます。書き間違いはアプリを起動したときに分かります。エラーはどれもTypeErrorです。

  • /で始まらないキーroute pattern "products" must start with "/"
  • グループの形になっていない括弧(/(admin)/newなど)route group "/(admin)/new" must be "/(name)" and nothing else — a regular expression is not part of the grammar
  • childrenを持たないグループroute group "/(oops)" must have children
  • 同じパターンの2度目の宣言(入れ子の位置が違っても数えます)route pattern "/x" is declared twice
  • URLPatternが解釈できないパターン:URLPattern自身のTypeErrorになります

括弧を拒むのは、URLPatternが(…)を正規表現として読むからです。childrenの無いグループは、親の/のページの2度目の宣言になります。

k8ordo

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