実行できるJavaScriptドキュメント: URLとクエリ文字列

Q: JavaScriptでURLをパースするには？

文字列をURLコンストラクタに渡すだけです。const u = new URL('https://example.com/path?x=1')のように書くと、protocol、host、pathname、search、hash、そしてsearchParamsといったプロパティにアクセスできます。不正なURLを渡すと例外を投げるので、外部から受け取った文字列をパースする場合はtry/catchで囲んでおくと安心です。

Q: クエリ文字列のパラメータを取得するには？

url.searchParams.get('name')を使います。デコード済みの値が返ってきて、該当するパラメータが無ければnullになります。?tag=a&tag=bのように同じキーが複数回出てくるケースでは、searchParams.getAll('tag')で配列としてまとめて取得できます。

Q: URLとURLSearchParamsの違いは？

URLはプロトコル、ホスト、パス、クエリ、ハッシュといったURL全体を扱うオブジェクトです。一方、URLSearchParamsはクエリ文字列の部分だけを担当し、a=1&b=2のような文字列を単独で組み立てたり解析したりできます。URLインスタンスには.searchParamsプロパティが用意されていて、これがそのURLに紐づくURLSearchParamsとして機能します。

Q: クエリパラメータを自分でエンコードする必要はある？

基本的には不要です。URLSearchParamsでset、appendを呼んだり、文字列として取り出したりするときに、キーと値は自動でエンコードされます。スペース、&、=、Unicode文字もきちんと処理してくれます。encodeURIComponentを自分で呼ぶのは、どうしても文字列を手組みする場合だけで、普段はそもそも手組みしないのが正解です。

URLを文字列操作でパースするのはもうやめよう

URL APIが登場する前は、みんなsplit('?')や正規表現、そして祈りを駆使してURLを切り刻んでいました。値に&や=、スペース、非ASCII文字が混ざらない限りは、それでもなんとか動いていたんです。でも一度そういう文字が入れば、途端に壊れる。ブラウザにもNode.jsにも、ちゃんとしたパーサーが最初から用意されています。素直にそれを使いましょう。

const u = new URL("https://shop.example.com/products?id=42&color=red#reviews");

console.log(u.protocol);   // "https:"
console.log(u.host);       // "shop.example.com"
console.log(u.pathname);   // "/products"
console.log(u.search);     // "?id=42&color=red"
console.log(u.hash);       // "#reviews"

呼び出し一発で、URL の各パーツがすでにバラされて、しかもデコードまで済んだ状態で手に入ります。不正な URL を渡すとコンストラクタは TypeError を投げますが、これはむしろ望ましい挙動です。おかしな URL は黙って通すよりも、その場で派手に落ちてくれたほうが、後続の処理でゴミを垂れ流すより安全ですよね。

クエリパラメータを取得する

URL オブジェクトには必ず .searchParams プロパティがあり、これが URLSearchParams オブジェクトです。クエリ文字列の読み書きはすべてこいつに任せられます。

const u = new URL("https://example.com/search?q=javascript&page=2&tag=web&tag=beginner");

console.log(u.searchParams.get("q"));        // "javascript"
console.log(u.searchParams.get("page"));     // "2"
console.log(u.searchParams.getAll("tag"));   // ["web", "beginner"]
console.log(u.searchParams.has("sort"));     // false
console.log(u.searchParams.get("sort"));     // null

押さえておきたいポイントがいくつかあります。

値はデコード済みで返ってきます。?name=Ada%20Lovelace なら "Ada Lovelace" が取得できます。
すべて文字列として扱われます。"2" は 2 ではありません。数値として使いたい場合は Number() で変換しましょう。
同じキーが複数あっても問題ありません。get は最初にマッチしたものだけを返し、getAll はすべての値を配列で返します。
存在しないキーは undefined ではなく null を返します。なので ?? "default" との組み合わせが便利です。

クエリ文字列を組み立てる

URLSearchParams を使えば、クエリ文字列をゼロから組み立てられます。エスケープを手動でやる必要も、& で自分でつなぐ必要もありません。

const params = new URLSearchParams();
params.set("q", "hello world");
params.set("page", "2");
params.append("tag", "js");
params.append("tag", "beginner");

console.log(params.toString());
// "q=hello+world&page=2&tag=js&tag=beginner"

オブジェクトから生成することもできます。[キー, 値] のペアを返すイテラブルならなんでも使えますし、普通のオブジェクトでもOKです。

const params = new URLSearchParams({
    q: "café",
    page: "1",
    sort: "new",
});

console.log(params.toString());
// "q=caf%C3%A9&page=1&sort=new"

set と append の違い: set は既存の値を上書きします。append は別の値を追加します。同じキーが複数回登場し得る場合(タグやフィルタなど)は append、単一の値しか持たないパラメータには set を使い分けましょう。

URL を書き換える

URL はライブオブジェクトなので、searchParams をいじれば .search や .href も自動的に更新されます。

const u = new URL("https://example.com/search?q=js");

u.searchParams.set("page", "2");
u.searchParams.set("q", "typescript");     // 上書きする
u.searchParams.delete("utm_source");       // 存在しない場合は何もしない

console.log(u.href);
// "https://example.com/search?q=typescript&page=2"

既存のURLにクエリパラメータを追加するなら、これが一番スマートな書き方です。「URLにすでに?が付いてるかな?」とチェックしたり、区切り文字として&と?のどちらを使うか悩む必要もありません。

URLの他の部分も、同じ要領で書き換えられます。

const u = new URL("https://example.com/old");

u.pathname = "/new";
u.hash = "top";

console.log(u.href);
// "https://example.com/new#top"

パラメータをループで取り出す

URLSearchParams はイテラブルなので、for...of で回すと [キー, 値] のペアが順番に取れます。配列などと同じように keys()、values()、entries() といったヘルパーも用意されています。

const u = new URL("https://example.com/?q=js&page=2&tag=web&tag=beginner");

for (const [key, value] of u.searchParams) {
    console.log(key, "=", value);
}

キーの重複はそのまま保持される点に注目してください。tag = web の次に tag = beginner が別エントリとして出てきます。これはクエリ文字列の実際の中身に忠実な挙動です。

デバッグ用にサクッとプレーンなオブジェクトで中身を確認したいときは Object.fromEntries が便利です。ただし重複キーは潰れてしまい、最後の値だけが残る点には注意してください。

const u = new URL("https://example.com/?q=js&tag=web&tag=beginner");

const obj = Object.fromEntries(u.searchParams);
console.log(obj);   // { q: "js", tag: "beginner" }

デバッグ目的なら問題ありませんが、同じキーが複数回登場しうる場合は正しく動作しません。

相対URLにはベースが必要

new URL("/search?q=js") を単独で呼ぶとエラーになります。相対パスだけでは有効なURLにならないからです。第2引数にベースURLを渡しましょう。

const base = "https://example.com/app/";

const u1 = new URL("/search?q=js", base);
const u2 = new URL("profile", base);
const u3 = new URL("../about", base);

console.log(u1.href);   // "https://example.com/search?q=js"
console.log(u2.href);   // "https://example.com/app/profile"
console.log(u3.href);   // "https://example.com/about"

この解決ルールは、ブラウザが <a href> を解釈するときとまったく同じです。先頭が / ならホストからの絶対パス、スラッシュなしなら現在のパスからの相対、.. は 1 階層上に上がります。設定値のベース URL から API の URL を組み立てるときにかなり重宝します。

ブラウザ上では、window.location.href がそのまま現在ページの URL を解析するためのベースとして使えます。

const u = new URL(window.location.href);
const page = u.searchParams.get("page") ?? "1";

不正な URL を扱う

URL コンストラクタは、フォーマットが崩れた入力を渡すと例外を投げます。これ自体はありがたい仕様なのですが、ユーザーが入力した文字列や外部システムから受け取った値をパースするときは、try/catch で囲む必要があります。

function safeParse(input) {
    try {
        return new URL(input);
    } catch {
        return null;
    }
}

console.log(safeParse("https://example.com/ok"));   // URL オブジェクト
console.log(safeParse("not a url"));                // null
console.log(safeParse(""));                         // null

モダンな実行環境では URL.canParse(input) も使えます。これは真偽値を返すチェック用のメソッドで、URL が有効かどうか確かめたいだけなら try/catch でわざわざ囲む必要がありません。

console.log(URL.canParse("https://example.com"));   // true
console.log(URL.canParse("nope"));                  // false

ちょっとした実用サンプル

ここまでの内容をまとめて、URL から現在のフィルタを読み取り、値を書き換えて、遷移先となる新しい URL を組み立ててみましょう。

function updateFilters(href, changes) {
    const u = new URL(href);

    for (const [key, value] of Object.entries(changes)) {
        if (value === null) {
            u.searchParams.delete(key);
        } else {
            u.searchParams.set(key, value);
        }
    }
    return u.href;
}

const current = "https://shop.example.com/products?category=shoes&page=3&sort=price";

console.log(updateFilters(current, { page: "1", sort: null, color: "red" }));
// "https://shop.example.com/products?category=shoes&page=1&color=red"

null を渡すとそのパラメータが削除されます。それ以外の値を渡すと、設定もしくは上書きになります。フィルター UI やページネーション、ディープリンクを作るときには、形は違えど結局このパターンを書くことになります。

まとめ

new URL(string) は URL を意味のあるパーツに分解してくれます。不正な文字列を渡すと例外になります。
url.searchParams は URLSearchParams なので、get、getAll、set、append、delete、has をそのまま使えます。
エンコードは自動で処理されます。自分で文字列を組み立てているとき以外、encodeURIComponent の出番はありません。
相対パスを解決したいときは、第2引数にベース URL を渡しましょう。
信頼できない入力のバリデーションには URL.canParse(または try/catch)が便利です。

.split('?') で URL を分割したくなったときや、正規表現でクエリパラメータを抜き出したくなったときは、代わりにこれらの API を使ってください。コードは短く、挙動は正確で、しかもランタイムに最初から入っています。

よくある質問

JavaScriptでURLをパースするには？

文字列をURLコンストラクタに渡すだけです。const u = new URL('https://example.com/path?x=1')のように書くと、protocol、host、pathname、search、hash、そしてsearchParamsといったプロパティにアクセスできます。不正なURLを渡すと例外を投げるので、外部から受け取った文字列をパースする場合はtry/catchで囲んでおくと安心です。

クエリ文字列のパラメータを取得するには？

url.searchParams.get('name')を使います。デコード済みの値が返ってきて、該当するパラメータが無ければnullになります。?tag=a&tag=bのように同じキーが複数回出てくるケースでは、searchParams.getAll('tag')で配列としてまとめて取得できます。

URLとURLSearchParamsの違いは？

URLはプロトコル、ホスト、パス、クエリ、ハッシュといったURL全体を扱うオブジェクトです。一方、URLSearchParamsはクエリ文字列の部分だけを担当し、a=1&b=2のような文字列を単独で組み立てたり解析したりできます。URLインスタンスには.searchParamsプロパティが用意されていて、これがそのURLに紐づくURLSearchParamsとして機能します。

クエリパラメータを自分でエンコードする必要はある？

基本的には不要です。URLSearchParamsでset、appendを呼んだり、文字列として取り出したりするときに、キーと値は自動でエンコードされます。スペース、&、=、Unicode文字もきちんと処理してくれます。encodeURIComponentを自分で呼ぶのは、どうしても文字列を手組みする場合だけで、普段はそもそも手組みしないのが正解です。