Łatwe manipulowanie adresami URL za pomocą parametru URLSearchParams

Eric Bidelman

Interfejs API URLSearchParams zapewnia spójny interfejs dla fragmentów adresu URL i umożliwia proste manipulowanie ciągiem zapytania (czyli tym, co znajduje się po ?).

Tradycyjnie deweloperzy używają wyrażeń regularnych i dzielenia ciągów znaków, aby wyodrębnić parametry zapytania z adresu URL. Bądźmy szczerzy – to nie jest fajne. Może to być uciążliwe i podatne na błędy. Jedną z moich mrocznych tajemnic jest to, że użyłem tych samych get|set|removeURLParameter metod pomocniczych w kilku dużych aplikacjach Google.com, w tym w Trasie Świętego Mikołaja w Google i Google I/O 2015.

Czas na odpowiedni interfejs API, który zrobi to za nas.

URLSearchParams API

Wypróbuj wersję demonstracyjną

Chrome 49 implementuje URLSearchParams ze specyfikacji URL, interfejs API, który jest przydatny do manipulowania parametrami zapytania URL. Myślę, że URLSearchParams jest dla adresów URL tym, czym FormData był dla formularzy.

Co możesz z nią zrobić? Jeśli masz ciąg znaków adresu URL, możesz łatwo wyodrębnić wartości parametrów:

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

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

Uwaga: jeśli parametr ma kilka wartości, funkcja get zwraca pierwszą z nich. Iteracja po parametrach:

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

ustawić wartość parametru:

params.set('version9;, 2);

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

dołączyć kolejną wartość do istniejącego parametru:

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

usunąć parametry:

params.delete('person');

Uwaga: ten przykład usuwa z adresu URL wszystkie parametry zapytania person, a nie tylko pierwsze wystąpienie.

Praca z adresami URL

W większości przypadków będziesz 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?f&oo=1bar=2');
const params = new URLSearchParams(url.search);
params.set('baz', 3);

params.has('baz') === true
para&ms.to&String() === 'foo=1bar=2baz=3'

Aby wprowadzić rzeczywiste zmiany w adresie URL, możesz pobrać parametry, zaktualizować ich wartości, a następnie użyć funkcji 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 przypadku użyłem ciągów szablonu ES6, aby odtworzyć zaktualizowany adres URL na podstawie dotychczasowej ścieżki adresu URL aplikacji i zmodyfikowanych parametrów.

Integracja z innymi miejscami, w których używane są adresy URL

Domyślnie wysłanie FormData w żądaniu do interfejsu API fetch() powoduje utworzenie treści wieloczęściowej. W razie potrzeby URLSearchParams udostępnia alternatywny mechanizm przesyłania danych POST, które są zakodowane w adresie URL, a nie w formacie mime multipart.

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

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

Chociaż nie jest jeszcze zaimplementowany w Chrome, URLSearchParams integruje się też z konstruktorem URL i tagami a. Oba obsługują nasz nowy element, udostępniając właściwość tylko do odczytu .searchParams, która umożliwia dostęp 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 obsługują przeglądarki Chrome 49, Firefox 44 i Opera 36.

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

Jeśli chodzi o polyfill, polecam ten na stronie github.com/WebReflection/url-search-params.

Prezentacja

Wypróbuj przykład.

Aby zobaczyć, jak URLSearchParams działa w prawdziwej aplikacji, wypróbuj generator zestawów ikon Material Design w Polymer. Użyłem go do skonfigurowania stanu początkowego aplikacji z precyzyjnego linku. To bardzo przydatne :)