Łatwe manipulowanie adresami URL za pomocą parametru URLSearchParams

Eric Bidelman

Interfejs API URLSearchParams zapewnia spójny interfejs fragmentów adresu URL i umożliwia łatwe wprowadzanie zmian w ciągu zapytania (te po ?).

Deweloperzy tradycyjnie używają wyrażeń regularnych i dzielenia ciągu znaków, aby wyodrębniać parametry zapytania z adresu URL. Jeśli jesteśmy szczerzy, to nie jest to przyjemne. Może to być uciążliwe i podatne na błędy. Jednym z moich mrocznych sekretów jest to, że w kilku dużych aplikacjach na Google.com, w tym w Świątecznym Śledźcie Świętego Mikołaja Google i w witrynie internetowej Google I/O 2015, używam tych samych get|set|removeURLParameter metod pomocniczych.

Nadszedł czas na odpowiedni interfejs API, który zrobi to za nas.

Interfejs URLSearchParams API

Wypróbuj wersję demonstracyjną

Chrome 49 wdraża interfejs API URLSearchParams z specyfikacji adresów URL. Jest to interfejs API przydatny do manipulowania parametrami zapytania adresu URL. Uważam, że URLSearchParams jest taką samą wygodą dla adresów URL jak FormData dla formularzy.

Co można z nim zrobić? Mając adres URL, możesz łatwo wyodrębnić wartości parametrów:

// 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

Uwaga: jeśli parametr ma kilka wartości, get zwraca pierwszą wartość. Wykonaj iterację na podstawie parametrów:

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

ustaw wartość parametru:

params.set('version', 2);

Uwaga: jeśli istnieje kilka wartości, funkcja set usuwa wszystkie pozostałe parametry o tej samej nazwie.

dodać inną wartość do istniejącego parametru:

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

usunąć parametry:

params.delete('person');

Uwaga: w tym przykładzie z adresu URL zostaną usunięte wszystkie parametry zapytania person, a nie tylko pierwsze wystąpienie.

Praca z adresami URL

W większości przypadków będziesz prawdopodobnie pracować z pełnymi adresami URL lub modyfikować adres URL aplikacji. Konstruktor URL może być szczególnie przydatny w tych przypadkach:

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'

Aby wprowadzić zmiany w adresie URL, możesz pobrać parametry, zaktualizować ich wartości, a następnie użyć history.replaceState, aby zaktualizować adres 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

W tym przykładzie użyłem ciągów szablonu ES6, aby odtworzyć zaktualizowany adres URL z dotychczasowej ścieżki adresu URL aplikacji i zmodyfikowanych parametrów.

Integracja z innymi adresami URL miejsc

Domyślnie wysłanie FormData w żądaniu interfejsu API fetch() powoduje utworzenie treści wieloczęściowej. W razie potrzeby funkcja URLSearchParams udostępnia mechanizm alternatywny dla danych POST, który jest zakodowany w adresie URL zamiast wieloczęściowego MIME.

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

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

Chociaż nie jest jeszcze implementowany w Chrome, URLSearchParams integruje się też z konstruktorem URL i tagami a. Oba te rozwiązania obsługują naszego nowego kumpla, udostępniając właściwości tylko do odczytu .searchParams do uzyskiwania dostępu do parametrów zapytania:

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

Linki mają też właściwość .searchParams:

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

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

Wykrywanie funkcji i obsługa przeglądarek

Obecnie URLSearchParams jest obsługiwana w Chrome 49, Firefox 44 i Opera 36.

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

W przypadku polyfill zaleca się użycie tego na stronie github.com/WebReflection/url-search-params.

Prezentacja

Wypróbuj przykładowy dokument.

Aby zobaczyć URLSearchParams w aplikacji, skorzystaj z Generatora zestawów ikon z użyciem języka Material Design firmy Polymer. Użyłem go do skonfigurowania początkowego stanu aplikacji z precyzyjnego linku. Przydatne :)