URLSearchParams による簡単な URL 操作

URLSearchParams API は URL の一部と部分に対して一貫したインターフェースを提供し、クエリ文字列（? の後の部分）を簡単に操作できます。

従来、デベロッパーは正規表現と文字列分割を使用して URL からクエリ パラメータを取り出していました。皆が自分自身に正直に思うなら、楽しくはありません。手間がかかり、正しく設定するのが難しい場合があります。私のダークな秘密の一つは、Google Santa Tracker や Google I/O 2015 ウェブなど、いくつかの大規模な Google.com アプリで同じ get|set|removeURLParameter ヘルパー メソッドを再利用していることです。

このような処理を自動で行う適切な API が登場しました。

URLSearchParams API

デモを試す

Chrome 49 では、URL 仕様の URLSearchParams を実装しています。これは、URL クエリ パラメータを操作するのに便利な API です。URLSearchParams は、FormData がフォームに対して行っていたように、URL に対して行っていた便利な機能と同等のものと考えられます。

では、この機能を使って何ができるでしょうか。URL 文字列からパラメータ値を簡単に抽出できます。

// Can also constructor from another URLSearchParams
const params = new URLSearchParams('q=search+string&version=1&person=Eric');

params.get('q') === "search string"
params.get('version') === "1"
Array.from(params).length === 3

for (let p of params) {
    console.log(p);
}

パラメータ値を設定します。

params.set('version', 2);

既存のパラメータに別の値を追加します。

params.append('person', 'Tim');
params.getAll('person') === ['Eric', 'Tim']

パラメータを削除します。

params.delete('person');

URL の操作

ほとんどの場合、完全な URL を操作するか、アプリの URL を変更することになります。URL コンストラクタは、次のような場合に特に便利です。

const url = new URL('https://example.com?foo=1&bar=2');
const params = new URLSearchParams(url.search);
params.set('baz', 3);

params.has('baz') === true
params.toString() === 'foo=1&bar=2&baz=3'

URL を実際に変更するには、パラメータを取得して値を更新し、history.replaceState を使用して URL を更新します。

// URL: https://example.com?version=1.0
const params = new URLSearchParams(location.search);
params.set('version', 2.0);

window.history.replaceState({}, '', `${location.pathname}?${params}`);
// URL: https://example.com?version=2.0

ここでは、ES6 のテンプレート文字列を使用して、アプリの既存の URL パスと変更されたパラメータから更新された URL を再構成しています。

他の場所の URL との統合が使用されている

デフォルトでは、fetch() API リクエストで FormData を送信するとマルチパート ボディが作成されます。必要な場合は、MIME マルチパートではなく、URL エンコードされたデータを POST する代替メカニズムとして URLSearchParams を使用できます。

const params = new URLSearchParams();
params.append('api_key', '1234567890');

fetch('https://example.com/api', {
    method: 'POST',
    body: params
}).then(...)

URLSearchParams は Chrome にはまだ実装されていませんが、URL コンストラクタと a タグにも統合されています。どちらも、クエリ パラメータにアクセスするための読み取り専用プロパティ .searchParams を提供することで、新しいバディをサポートしています。

const url = new URL(location);
const foo = url.searchParams.get('foo') || 'somedefault';

リンクにも .searchParams プロパティが設定されます。

const a = document.createElement('a');
a.href = 'https://example.com?filter=api';

// a.searchParams.get('filter') === 'api';

機能の検出とブラウザのサポート

現在、URLSearchParams は Chrome 49、Firefox 44、Opera 36 でサポートされています。

if ('URLSearchParams' in window) {
    // Browser supports URLSearchParams
}

ポリフィルについては、github.com/WebReflection/url-search-params のポリフィルをおすすめします。

デモ

サンプルを試す

実際のアプリで URLSearchParams を確認するには、Polymer のマテリアル デザイン アイコンセット ジェネレータをご覧ください。これを使用することで、ディープリンクからアプリの初期状態を設定しました。とても便利です。