Jak wysyłać zapytania do panelu Web Platform na potrzeby narzędzia Baseline

Jeremy Wagner

Opublikowano: 4 marca 2025 r.

Wartość bazowa została opracowana przez zespół Chrome i jest obecnie definiowana przez grupę społecznościową WebDX. Wartość bazowa ułatwia zrozumienie funkcji, które są interoperacyjne w różnych przeglądarkach. Pomaga określić, z których funkcji możesz korzystać, a z których nie, we wszystkich głównych silnikach przeglądarek. Musisz jednak wiedzieć, jakie to funkcje.

Na szczęście możesz sprawdzić, które funkcje są nowo lub powszechnie dostępne w wartości bazowej, korzystając z panelu platformy internetowej, który jest oparty na pakiecie npm web-features. Możesz też uzyskać te informacje za pomocą interfejsu HTTP API, aby zintegrować dane wartości bazowej z przepływem pracy narzędzi. Ten przewodnik wyjaśnia, jak to zrobić.

Odpowiednia gramatyka zapytań wartości bazowej w panelu platformy internetowej

Panel platformy internetowej używa określonej gramatyki zapytań, która pomaga wyszukiwać obsługę funkcji internetowych. Możesz używać tej gramatyki zapytań bezpośrednio w panelu.

Podczas wpisywania tekstu w polu wyszukiwania u góry strony wyświetli się kilka parametrów zapytania, których możesz użyć do filtrowania funkcji internetowych.

Gramatyka zapytań jest rozbudowana, co daje dużą elastyczność w filtrowaniu funkcji internetowych wyświetlanych w panelu. Poniższy zrzut ekranu pokazuje, jak za pomocą parametru zapytania id można zawęzić wyniki do konkretnej funkcji:

Gramatyka zapytań jest udokumentowana, ale znajomość jej całości nie jest wymagana do znalezienia danych wartości bazowej dotyczących funkcji. W panelu możesz użyć dowolnej z tych opcji, ale oto kilka szczególnie przydatnych:

• baseline_status: użyj tego parametru, aby filtrować funkcje według 3 wyliczonych wartości:
  • limited: zwraca funkcje, które mają ograniczoną obsługę w przeglądarkach. Jeśli zastosujesz filtr według tej wartości, otrzymasz tylko funkcje, które nie osiągnęły żadnego stanu wartości bazowej.
  • newly: zwraca funkcje, które są nowo dostępne w wartości bazowej.
  • widely: zwraca funkcje, które są powszechnie dostępne w wartości bazowej, czyli funkcje, które są w wartości bazowej od co najmniej 30 miesięcy. Są to funkcje, których możesz używać bez obaw o obsługę w przeglądarce lub polyfille.
• baseline_date: używa formatu YYYY-MM-DD..YYYY-MM-DD, aby określić górną i dolną granicę daty, kiedy funkcje osiągnęły wartość bazową. Aby na przykład znaleźć wszystkie funkcje w ciągu roku, użyj wartości takiej jak 2024-01-01..2025-01-01.
• id: identyfikator danej funkcji. Te identyfikatory są zdefiniowane w pakiecie web-features. Na przykład wpis funkcji Promise.try() jest mapowany na identyfikator promise-try.
• group: jedna z wielu wyliczonych nazw grup funkcji. Jest to przydatne kryterium, jeśli chcesz wysyłać zapytania tylko o określony podzbiór funkcji platformy internetowej. Możesz na przykład zastosować filtr do listy funkcji CSS z wartością css.

Interfejs panelu jest oczywiście przydatny, ale opiera się na interfejsie HTTP API, o który możesz wysyłać zapytania bezpośrednio. Oto na przykład punkt końcowy, który pobiera wszystkie funkcje wartości bazowej, które są nowo dostępne:

https://api.webstatus.dev/v1/features?q=baseline_status:newly

Struktura odpowiedzi JSON

Odpowiedź JSON otrzymywana z interfejsu HTTP API ma spójną strukturę dla każdej funkcji. Odpowiedź zawiera właściwość data na najwyższym poziomie. Ta właściwość zawiera tablicę wszystkich pasujących funkcji. Nie jest to wyczerpująca lista wszystkich pól dostępnych w odpowiedzi JSON, ale oto kilka przydatnych w przypadku wartości bazowej:

• baseline: zawiera ogólne informacje o stanie wartości bazowej danej funkcji, z tymi polami:
  • status: stan wartości bazowej funkcji. Wartości mogą być limited, newly lub widely. Uwaga: jeśli status ma wartość limited, będzie to jedyne pole.
  • low_date: data, w której dana funkcja stała się nowo dostępna w wartości bazowej. To pole pojawia się tylko wtedy, gdy status ma wartość newly lub widely.
  • high_date: data, w której dana funkcja stała się powszechnie dostępna w wartości bazowej. To pole jest dostępne tylko wtedy, gdy status ma wartość widely.
• feature_id: identyfikator funkcji. Na przykład w przypadku siatki CSS będzie to wartość "grid".
• name: sformatowana nazwa funkcji. W niektórych przypadkach może być podobna do feature_id, ale zwykle jest inna. Na przykład wartość feature_id dla Promise.try() to "promise-try", a pole name dla tej samej funkcji to "Promise.try()".
• spec: to pole zawiera pole links, które jest tablicą linków do specyfikacji i innych zasobów.

Dostępne są też inne pola, które często zawierają informacje o tym, kiedy konkretne obsługiwane przeglądarki zaimplementowały funkcję w danej wersji, dane o testach platformy internetowej i inne informacje, które mogą Cię interesować lub nie.

Przykładowe zapytania

Teraz, gdy masz już krótkie wyjaśnienie niektórych dostępnych parametrów zapytania, zapoznaj się z kilkoma przykładowymi zapytaniami, których możesz użyć w swoich narzędziach i skryptach, aby wybrać funkcje stanu internetowego, które mogą być przydatne w Twoim przepływie pracy.

Pobieranie danych pojedynczej funkcji

Dobrym sposobem na zapoznanie się z interfejsem API jest rozpoczęcie od podstawowego przykładu, który pobiera dane pojedynczej funkcji internetowej.

// Specify and encode the query for a query string:
const query = encodeURIComponent('id:grid');

// Construct the URL:
let url = `https://api.webstatus.dev/v1/features?q=${query}`;

// Fetch the resource:
const response = await fetch(url);

if (response.ok) {
  // Convert the response to JSON:
  const { data } = await response.json();

  // Log data for each feature to the:
  console.log(data);
}

W tym przypadku określamy parametr id z wartością grid, aby uzyskać informacje o obsłudze funkcji siatki CSS, która jest powszechnie dostępna w wartości bazowej. Możesz użyć tych informacji np. do wykrywania użycia funkcji i informowania użytkowników, że mogą jej używać we wszystkich nowoczesnych silnikach przeglądarek bez obaw o obsługę.

To jednak dopiero początek, a interfejs HTTP API może zrobić dla Ciebie znacznie więcej niż tylko pobrać dane pojedynczej funkcji.

Pobieranie wszystkich funkcji nowo i powszechnie dostępnych w wartości bazowej

Załóżmy, że chcesz mieć skrypt, który pobiera wszystkie funkcje, które są nowo lub powszechnie dostępne w wartości bazowej. Może to być przydatne np. jeśli masz skrypt, który jest uruchamiany w określonych odstępach czasu, i chcesz otrzymywać zaktualizowaną listę, która zmienia się, gdy funkcje przechodzą z ograniczonej dostępności do stanu wartości bazowej:

const query = encodeURIComponent('-baseline_status:limited');
let url = `https://api.webstatus.dev/v1/features?q=${query}`;
const response = await fetch(url);

if (response.ok) {
  const { data } = await response.json();

  console.log(data);
}

To zapytanie nie pobiera wszystkich funkcji nowo i powszechnie dostępnych w wartości bazowej, ale tylko pierwsze 100. Jeśli liczba pobranych funkcji przekracza tę wartość, na najwyższym poziomie odpowiedzi JSON znajduje się pole metadata, które może zawierać maksymalnie 2 pola:

• next_page_token: ciąg znaków zawierający token, który możesz dodać do ciągu zapytania żądania GET do backendu. Gdy go użyjesz i ponownie pobierzesz dane z backendu webstatus.dev, zwróci on następną partię pasujących funkcji. Uwaga: to pole będzie niedostępne, jeśli bieżące zapytanie zwróci mniej niż 100 wyników lub jeśli bieżące zapytanie znajduje się na końcu zbioru wyników.
• total: liczba całkowita wskazująca łączną liczbę funkcji dostępnych dla bieżącego zapytania.

Te pola są przydatne do podziału na strony. Dzięki nim możemy spróbować użyć tego kodu, aby uzyskać wszystkie wyniki zapytania, które zwraca dużą ilość danych:

async function queryWebStatusDashboard (query, token) {
  const urlBase = 'https://api.webstatus.dev/v1/features?q=';
  let queryUrl = `${urlBase}${encodeURIComponent(query)}`;

  if (token) {
    queryUrl += `&page_token=${encodeURIComponent(token)}`;
  }

  const response = await fetch(queryUrl);

  if (response.ok) {
    const { data, metadata } = await response.json();

    console.log(data);

    // See if there's a page token in this query:
    if ('next_page_token' in metadata) {
      const { next_page_token } = metadata;
      queryWebStatusDashboard(query, next_page_token);
    } else {
      console.log('All results collected');
    }
  }
}

// Make the first query, and if there are more
// than 100 entries, the function will run
// recursively until all features are fetched
queryWebStatusDashboard('-baseline_status:limited');

Pobieranie wszystkich funkcji CSS nowo dostępnych w wartości bazowej

Załóżmy, że jesteś inżynierem, który specjalizuje się w CSS, i chcesz wiedzieć, które funkcje CSS stają się nowo dostępne w wartości bazowej. Jest to idealny przypadek użycia wartości zapytania group, a także sposobu użycia operatora AND podczas wysyłania zapytań do webstatus.dev:

const query = encodeURIComponent('baseline_status:newly AND group:css');
let url = `https://api.webstatus.dev/v1/features?q=${query}`;
const response = await fetch(url);

if (response.ok) {
  const { data } = await response.json();

  console.log(data);
}

Jeśli określisz wartość css dla group, możesz wysłać zapytanie o wszystkie funkcje nowo dostępne w wartości bazowej. Jeśli chcesz rozszerzyć zakres, aby uwzględnić też funkcje CSS powszechnie dostępne w wartości bazowej, możesz użyć podejścia z ostatniego przykładu kodu i użyć operatora negacji z zapytaniem takim jak -baseline_status:limited AND group:css'.

Innym polem, o które możesz wysyłać zapytania, jest pole snapshot, które jest przydatne do znajdowania funkcji JavaScript, które są częścią określonego zestawu funkcji ECMAScript. Ten kod sprawdza wszystkie funkcje nowo dostępne w wartości bazowej, które są częścią migawki ecmascript-2023:

const query = encodeURIComponent('baseline_status:newly AND snapshot:ecmascript-2023');
let url = `https://api.webstatus.dev/v1/features?q=${query}`;
const response = await fetch(url);

if (response.ok) {
  const { data } = await response.json();

  console.log(data);
}

Pobieranie wszystkich funkcji wartości bazowej w zakresie dat

Możesz wysyłać zapytania o pole baseline_date, aby znaleźć wszystkie funkcje, które stały się wartością bazową w określonym zakresie dat:

const query = encodeURIComponent('baseline_status:widely AND baseline_date:2022-01-01..2022-12-31 AND group:css');
let url = `https://api.webstatus.dev/v1/features?q=${query}`;
const response = await fetch(url);

if (response.ok) {
  const { data } = await response.json();

  console.log(data);
}

Poprzedni przykład kodu wysyła zapytanie o funkcje CSS, które stały się powszechnie dostępne w wartości bazowej w dowolnym momencie 2022 roku. Składnia zapytania dla baseline_date umożliwia określenie daty początkowej i końcowej oddzielonych znakiem ...

Podsumowanie

Zapytania w tym przewodniku mają być punktem początkowym do eksperymentowania z wysyłaniem zapytań do backendu webstatus.dev. Dzięki dowolnej liczbie dostępnych parametrów zapytania powinny być możliwe uzyskanie wyników, które są specyficzne dla Twojej aplikacji.

Wiedza o tym, jak wysyłać zapytania do interfejsu HTTP API panelu platformy internetowej, umożliwia tworzenie narzędzi, które mogą być przydatne w Twojej pracy, oraz informowanie o tym, czy funkcje, których chcesz używać w projekcie, są wystarczająco obsługiwane przez przeglądarki. Oznacza to, że możesz tworzyć aplikacje internetowe za pomocą nowoczesnych funkcji przeglądarki, których możesz bezpiecznie używać, co zapewnia znacznie lepsze wrażenia programistyczne.