ReactとURLPatternでURLから値を取り出す方法

​​React​Playwright,TypeScript,URLPattern,useSyncExternalStore

/items/42 の 42 や、/tags/猫 の「猫」のように、URL のパスに入った値を取り出したいときは、ブラウザ標準の URLPattern が使えます。/items/:id のような形を書いておくと、exec() が { id: '42' } を返します。

商品の詳細ページや記事のページのように、URL によって表示を切り替えたいけれど、ルーターのライブラリを入れるほどではない小さなアプリで、URLPattern は役に立ちます。ここでは、URL から「どの画面か」と「その画面で使う値」を取り出す関数を作り、React の表示につなげました。

補足

検証環境は Ubuntu 24.04、Node.js 22.23.4 です。react / react-dom 19.3.1、@types/react 19.3.0、typescript 7.0.2、esbuild 0.28.2 を使い、.tsx を tsc で型チェックしてから esbuild の開発用ビルドで変換しました。ブラウザは Playwright 1.63.0 で動かした Chromium 153(ヘッドレス)だけです。Firefox、Safari、サーバーサイドレンダリング、React Router などのルーターとの組み合わせ、ブラウザで polyfill を読み込む使い方は試していません。

どのブラウザで使えるか

MDN の互換性データでは、URLPattern は Chrome と Edge がバージョン95から、Firefox が142から、Safari が26から対応しています。Node.js は24からです。

型は TypeScript の DOM の型定義に入っています。検証環境の TypeScript 7.0.2 では、"lib": ["ES2022", "DOM"] のままで new URLPattern() と exec() の結果の型チェックが通りました。

exec() でパスの値を取り出す

URLPattern には、URL のどの部分をどんな形で照合するかを渡します。パスだけを決めたいときは pathname を渡します。:id のように : で始まる部分が、名前付きのグループです。

ts
const p = new URLPattern({ pathname: '/items/:id' });

p.test('https://example.com/items/3');                  // true
p.exec('https://example.com/items/3')?.pathname.groups; // { id: '3' }

exec() は、合わなければ null を、合えば URL の部分ごとの結果を返します(MDN の exec() の説明)。パスの値は pathname.groups に入っています。検証環境の Chromium で、いくつかの URL を試した結果は次のとおりです。

照合した URL pathname.groups
https://example.com/items/3 { id: '3' }
https://example.com/items/3?tab=a#x { id: '3' }
https://example.com/items/3/ 合わない(null)
https://example.com/items/ 合わない(null)
https://example.com/items/猫 { id: '%E7%8C%AB' }

取り出した値には、気をつけることが3つあります。

1つ目は、値がいつも文字列であることです。/items/:id(\\d+) と数字だけに絞っても、typeof は 'string' でした。数として使うなら Number() で変換します。

2つ目は、日本語などの文字が、パーセントエンコードされたまま返ることです。/items/猫 を渡しても %E7%8C%AB が返りました。画面に出すときは decodeURIComponent() で「猫」に戻します。

3つ目は、末尾のスラッシュです。/items/:id は /items/3/ に合いません。MDN の URL Pattern API の説明にあるとおり、{/}? を末尾に付けると、スラッシュがあってもなくても合います。検証環境でも、/items/:id{/}? は /items/3 と /items/3/ の両方で { id: '3' } を返しました。

パターンの書き方で、合う URL を絞る

グループの後ろに ( ) で正規表現を書くと、合う値を絞れます(MDN のパターンの書き方の説明)。正規表現は文字列の中に書くので、\d はコードでは \\d と書きます。検証環境で試した結果は次のとおりです。

パターン 照合したパス 結果
/items/:id(\\d+) /items/3 合う
/items/:id(\\d+) /items/abc 合わない
/blog/:year/:month? /blog/2026 { year: '2026' }
/blog/:year/:month? /blog/2026/11 { year: '2026', month: '11' }
/files/:path+ /files/a/b { path: 'a/b' }
/docs/* /docs/a/b/c { '0': 'a/b/c' }

? を付けたグループは、なくても合います。/blog/2026 では、結果に month の値は入っていませんでした(groups.month を読むと undefined です)。+ を付けると、/ をまたいだ残りのパスをまとめて受け取れます。* も残りのパスを受け取りますが、名前がないので、キーは '0' になります。

大文字と小文字は区別されます。/items/:id は /Items/3 に合いませんでした。区別したくないときは、コンストラクターの ignoreCase オプションを使います。new URLPattern({ pathname: '/items/:id' }, { ignoreCase: true }) にすると、/Items/3 にも合いました。

クエリは URLSearchParams で読む

?q=cat のようなクエリも、URLPattern の search に書けます。ただし、{ pathname: '/search', search: 'q=:q' } で試したところ、次のようになりました。

照合した URL search.groups
https://example.com/search?q=cat { q: 'cat' }
https://example.com/search?q=cat&page=2 { q: 'cat&page=2' }
https://example.com/search?page=2&q=cat 合わない(null)

MDN にある、グループが合う文字の範囲の説明によると、グループが / 以外のすべての文字に合うのは pathname だけです。search では、グループはすべての文字に合います。そのため & から後ろまで q に入ってしまいます。クエリは書く順番が決まっていないので、search のパターンで照合するのにも向きません。

クエリの値は、new URL(href).searchParams.get('page') のように、URLSearchParams で読むのが確実です。順番に関係なく、page は '2'、q は 'cat' と取り出せました。

URL から画面と値を決める関数を作る

ここからは React で使う形にします。まず、URL の文字列を受け取って、「どの画面か」と「その画面で使う値」を返す関数 matchRoute を作ります。React に関係しない、ただの関数です。

URL のパスを URLPattern で、クエリを URLSearchParams で読み、tag は decodeURIComponent で「猫」に、page は Number で 2 にしてから、matchRoute の戻り値にまとめる流れの図
/tags/%E7%8C%AB?page=2 から、タグとページ番号を取り出す流れ
ts
// routes.ts
// URL から、どの画面か と その画面で使う値 を取り出す。
const itemPattern = new URLPattern({ pathname: '/items/:id(\\d+){/}?' });
const tagPattern = new URLPattern({ pathname: '/tags/:tag{/}?' });

export type Route =
  | { name: 'item'; id: number }
  | { name: 'tag'; tag: string; page: number }
  | { name: 'notFound' };

export function matchRoute(href: string): Route {
  const item = itemPattern.exec(href);
  if (item) {
    return { name: 'item', id: Number(item.pathname.groups.id) };
  }

  const tag = tagPattern.exec(href);
  if (tag) {
    const raw = tag.pathname.groups.tag ?? '';
    let decoded: string;
    try {
      decoded = decodeURIComponent(raw);
    } catch {
      return { name: 'notFound' }; // %E7%8C のような壊れた値
    }
    // クエリは URLPattern ではなく URLSearchParams で読む
    const page = Number(new URL(href).searchParams.get('page') ?? '1');
    return { name: 'tag', tag: decoded, page: Number.isInteger(page) && page > 0 ? page : 1 };
  }

  return { name: 'notFound' };
}

パターンは、ファイルの一番上で一度だけ作っています。コンポーネントの中で作ると、描画のたびに作り直すことになるためです。

exec() の結果の groups の型は、値が string | undefined のオブジェクトです。そのままでは、id があることを型で保証できません。そこで、画面ごとに必要な値を持つ型 Route を返すようにしました。呼び出し側は route.name で分岐すれば、route.id を number として使えます。

decodeURIComponent() は、%E7%8C のように途中で切れた値を渡すと例外を投げます。検証環境でも URIError: URI malformed になりました。描画の途中で例外が起きないよう、try で受け止めて「見つからない」扱いにしました。

React で今の URL を読み、表示を切り替える

今の URL は、useSyncExternalStore で React の値として読みます。ブラウザの「戻る」「進む」では popstate イベントが起きるので、それを購読します。

ts
// useLocationHref.ts
import { useSyncExternalStore } from 'react';

const NAVIGATE = 'app:navigate';

function subscribe(onChange: () => void) {
  window.addEventListener('popstate', onChange);
  window.addEventListener(NAVIGATE, onChange);
  return () => {
    window.removeEventListener('popstate', onChange);
    window.removeEventListener(NAVIGATE, onChange);
  };
}

// 今の URL(location.href)を React の値として読む
export function useLocationHref(): string {
  return useSyncExternalStore(subscribe, () => window.location.href);
}

export function navigate(to: string) {
  history.pushState(null, '', to);
  // pushState では popstate が起きないので、自分で知らせる
  window.dispatchEvent(new Event(NAVIGATE));
}

リンクを押したときは、history.pushState() で URL だけを変えます。MDN の popstate の説明にあるとおり、pushState() を呼んでも popstate は起きません。そこで、自分で決めた名前のイベント app:navigate を送っています。検証環境で、この dispatchEvent の行を消して「商品42」のリンクを押したところ、アドレスバーの URL は /items/42/ になったのに、画面は「商品 3 の詳細」のままでした。

コンポーネントでは、読んだ URL を matchRoute に渡して、表示を選びます。

tsx
// App.tsx
import type { MouseEvent, ReactNode } from 'react';
import { matchRoute } from './routes';
import { navigate, useLocationHref } from './useLocationHref';

function Link({ to, children }: { to: string; children: ReactNode }) {
  const onClick = (e: MouseEvent<HTMLAnchorElement>) => {
    if (e.button !== 0 || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return;
    e.preventDefault();
    navigate(to);
  };
  return <a href={to} onClick={onClick}>{children}</a>;
}

export function App() {
  const href = useLocationHref();
  const route = matchRoute(href);

  return (
    <main>
      <nav>
        <Link to="/items/3">商品3</Link> <Link to="/items/42/">商品42</Link>{' '}
        <Link to="/tags/%E7%8C%AB?page=2">タグ「猫」の2ページ目</Link>{' '}
        <Link to="/items/abc">商品abc</Link>
      </nav>
      <section>
        {route.name === 'item' && <h1>商品 {route.id} の詳細</h1>}
        {route.name === 'tag' && <h1>タグ「{route.tag}」の {route.page} ページ目</h1>}
        {route.name === 'notFound' && <h1>ページが見つかりません</h1>}
      </section>
    </main>
  );
}

Link は、左ボタン以外のクリックや、Ctrl キーなどを押しながらのクリックでは preventDefault() を呼ばず、ブラウザのふだんの動きに任せます。

検証用のサーバーは、どのパスを開かれても同じ HTML を返すようにしました。Playwright で URL を直接開いたときの表示は、次のとおりです(検証に使ったコードでは、確認のために id の型も表示しています)。

開いた URL 表示
/items/3 商品 3 の詳細(id は number)
/items/3/ 商品 3 の詳細
/items/abc ページが見つかりません
/tags/%E7%8C%AB?page=2 タグ「猫」の 2 ページ目
/tags/猫 タグ「猫」の 1 ページ目
/tags/%E7%8C%AB?page=abc タグ「猫」の 1 ページ目
/tags/%E7%8C ページが見つかりません
/Items/3 ページが見つかりません

/items/3 を開いてから、リンクで「タグ「猫」の2ページ目」「商品42」と移り、Playwright で履歴を2回戻り、1回進めました。どの時点でも、表示は URL と合っていました。この間、ページの読み込みは0回でした。

URLPattern がないブラウザでは、読み込む前に確かめる

対応していないブラウザでは、URLPattern という名前自体がありません。検証では、ページを開く前に window.URLPattern を消して、対応していないブラウザの代わりにしました。

最初は、main.tsx の先頭で App を import し、描画の前に 'URLPattern' in globalThis を確かめていました。この形では、画面に何も出ませんでした。ブラウザのコンソールには URLPattern is not defined というエラーが出ていました。routes.ts を読み込んだ時点で new URLPattern() が動くので、確かめる処理までたどり着かないためです。

そこで、確かめてから App を読み込むようにしました。

tsx
// main.tsx
import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';

const root = createRoot(document.getElementById('root')!);

if ('URLPattern' in globalThis) {
  // routes.ts は読み込んだ時点で new URLPattern() を呼ぶので、確かめてから読み込む
  import('./App').then(({ App }) => {
    root.render(<StrictMode><App /></StrictMode>);
  });
} else {
  root.render(<p>このブラウザは URLPattern に対応していません</p>);
}

この形では、URLPattern を消したページに「このブラウザは URLPattern に対応していません」と表示されました。MDN の URLPattern のページでは、URLPattern の polyfill も紹介されています。

Node.js 22 で matchRoute をテストする

matchRoute は React に関係しない関数なので、Node.js のテストランナーでも確かめられます。ただし、Node.js 22 には URLPattern がありません。検証環境では typeof URLPattern が 'undefined' で、routes.ts を読み込むと ReferenceError: URLPattern is not defined になりました。

テストでは、urlpattern-polyfill 10.1.0 を先に読み込みました。この polyfill は、import 'urlpattern-polyfill' と書くと URLPattern を使えるようにします。

ts
// routes.test.ts
import 'urlpattern-polyfill'; // Node.js 22 には URLPattern がない
import assert from 'node:assert/strict';
import { test } from 'node:test';
import { matchRoute } from '../src/routes';

test('商品の id を数値で取り出す', () => {
  assert.deepEqual(matchRoute('https://example.com/items/3/'), { name: 'item', id: 3 });
});

test('タグを日本語に戻し、ページ番号をクエリから読む', () => {
  assert.deepEqual(matchRoute('https://example.com/tags/%E7%8C%AB?page=2'), { name: 'tag', tag: '猫', page: 2 });
});

test('数字でない id は見つからない扱い', () => {
  assert.deepEqual(matchRoute('https://example.com/items/abc'), { name: 'notFound' });
});

esbuild で1つのファイルにまとめてから、node --test で動かしました。3件とも通りました。

text
$ npx esbuild test/routes.test.ts --bundle --platform=node --format=esm --outfile=dist/routes.test.mjs && node --test dist/routes.test.mjs
ok 1 - 商品の id を数値で取り出す
ok 2 - タグを日本語に戻し、ページ番号をクエリから読む
ok 3 - 数字でない id は見つからない扱い
# tests 3
# pass 3
# fail 0

型チェックでは1つ問題がありました。polyfill の型定義と TypeScript の DOM の型定義の両方に URLPattern があり、tsc が Duplicate identifier 'URLPattern' などのエラーを出しました。テスト用の tsconfig に "skipLibCheck": true を加えると、エラーは出なくなりました。

json
{ "extends": "./tsconfig.json", "compilerOptions": { "types": ["node"], "skipLibCheck": true }, "include": ["src", "test"] }

​Posted by 86