如何查詢 Web Platform Dashboard 的基準工具

Jeremy Wagner

發布日期：2025 年 3 月 4 日

基準最初是由 Chrome 團隊提出，現在則由 WebDX 社群群組定義。Baseline 可清楚說明瀏覽器之間可互通的功能。這項工具旨在協助您瞭解所有主要瀏覽器引擎支援或不支援哪些功能。不過，您需要找出這些特徵。

幸好，您可以使用 Web Platform Dashboard 查詢哪些功能是 Baseline Newly 或 Widely 可用，這個工具是由 web-features npm 套件提供技術支援。您也可以使用 HTTP API 存取這項資訊，將基準資料整合到工具工作流程中，本指南將說明具體做法。

Web Platform 資訊主頁的相關 Baseline 查詢文法

Web Platform 資訊主頁使用特定查詢文法，協助您搜尋網頁功能支援。您可以在資訊主頁上直接使用這項查詢文法。

在頁面頂端的搜尋框中輸入內容時，系統會顯示多個查詢參數，供您用來篩選網路功能。

查詢文法富有表現力，可讓您彈性篩選要在資訊主頁上顯示的網路功能。以下螢幕截圖顯示如何使用 id 查詢參數，縮小範圍至特定功能：

查詢文法已記錄在文件中，但您不需要瞭解所有文法，即可找出功能基準資料。您可以在資訊主頁上使用上述任一選項，但以下列出幾個特別實用的選項：

• baseline_status：使用這個參數，依據下列三個列舉值篩選功能：
  • limited：傳回瀏覽器支援有限的功能。如果依這個值篩選，您只會收到尚未達到任何基準狀態的功能。
  • newly：傳回 Baseline Newly available 的功能。
  • widely：傳回「基準廣泛適用」功能，也就是已推出至少 30 個月的功能。這些功能可供您放心使用，不必擔心瀏覽器支援或 Polyfill 問題。
• baseline_date：使用 YYYY-MM-DD..YYYY-MM-DD 格式，指定功能達到基準的上下限。舉例來說，如要尋找一年內的時距中的所有功能，請使用 2024-01-01..2025-01-01 等值。
• id：指定功能的 ID。這些 ID 定義在 web-features 套件中。舉例來說，Promise.try() 的功能項目會對應至 promise-try 的 ID。
• group：功能的列舉群組名稱之一。如果您只想查詢特定子集的網路平台功能，這項條件就非常實用。舉例來說，您可以篩選出值為 css 的 CSS 功能清單。

雖然資訊主頁前端相當實用，但它位於 HTTP API 的頂端，您可以直接查詢。舉例來說，以下是端點，可取得所有新推出的 Baseline 功能：

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

JSON 回應結構

您從 HTTP API 收到的 JSON 回應，每個功能都有一致的形狀。傳回的回應會在頂層包含 data 屬性。這個屬性包含所有相符特徵的陣列。雖然這份清單並未列出 JSON 回應中的所有欄位，但其中包含一些與 Baseline 相關的實用欄位：

• baseline：包含特定功能的基準狀態一般資訊，以及下列子欄位：
  • status：功能的 Baseline 狀態。值可以是 limited、newly 或 widely。注意：如果 status 的值為 limited，則只有這個子欄位。
  • low_date：這表示指定功能成為「基準」新功能的日期。只有在 status 為 newly 或 widely 時，才會顯示這個欄位。
  • high_date：這表示指定功能開始廣泛支援的日期。只有在 status 為 widely 時，才能使用這個欄位。
• feature_id：功能的 ID。舉例來說，如果是 CSS 格線，這個值會是 "grid"。
• name：功能的格式化名稱。有時可能與 feature_id 類似，但通常不同。舉例來說，Promise.try() 的 feature_id 值為 "promise-try"，而同一項特徵的 name 欄位為 "Promise.try()"。
• spec：這個欄位包含名為 links 的子欄位，這是規格和其他資源的連結陣列。

還有其他欄位，通常包含特定支援瀏覽器在哪個版本實作這項功能的資訊、網頁平台測試的資料，以及您可能或可能不在意的其他事項。

查詢範例

現在您已快速瞭解部分可用的查詢參數，請參閱一些查詢範例，這些範例可在工具和指令碼中使用，選取對工作流程有用的網站狀態功能。

取得單一地圖項目的資料

如要熟悉 API，不妨從基本範例著手，取得單一網頁功能的資料。

// 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);
}

在本例中，我們指定 id 參數，並將值設為 grid，以取得 CSS 格線的功能支援資訊，這是 Baseline 廣泛支援的功能。舉例來說，您可以運用這項資訊偵測功能的使用情況，並讓使用者瞭解他們可以在所有新式瀏覽器引擎中使用這項功能，不必擔心支援問題。

不過，這只是起步，HTTP API 能為您做的遠不只取得單一功能的資料。

取得所有「基準」新功能和廣泛可用的功能

假設您想使用指令碼，擷取所有「基準新推出」或「廣泛推出」的功能。舉例來說，如果您有定期執行的指令碼，且想取得更新後的清單，當中列出從有限供應狀態變更為「基準」狀態的功能，這項功能就非常實用：

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);
}

這項查詢「不會」取得所有 Baseline 新推出及廣泛支援的功能，只會取得前 100 項。如果擷取的特徵數量超過此值，JSON 回應的頂層會有 metadata 欄位，最多可包含兩個子欄位：

• next_page_token：這個字串包含權杖，可新增至後端 GET 要求的查詢字串。使用這個函式並從 webstatus.dev 後端重新擷取資料時，系統會傳回下一批相符的功能。注意：如果目前的查詢傳回少於 100 個結果，或目前的查詢位於結果集的結尾，則這個欄位將無法使用。
• total：整數，指出目前查詢可用的特徵總數。

這些欄位有助於分頁。有了這些函式，我們就能嘗試下列程式碼，取得查詢傳回的大量資料的所有結果：

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');

取得所有 Baseline 新推出的 CSS 功能

假設您是專注於 CSS 的工程師，想瞭解哪些 CSS 功能會成為 Baseline 新推出的功能。這是 group 查詢值的絕佳用途，以及查詢 webstatus.dev 時如何使用 AND 運算子：

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);
}

指定 group 的 group 值時，您可以查詢所有 Baseline Newly available features。css如果想擴大範圍，也納入 Baseline 廣泛提供的 CSS 功能，可以採用上一個程式碼範例的方法，並搭配否定運算子和 -baseline_status:limited AND group:css' 等查詢。

您也可以查詢 snapshot 欄位，找出屬於特定 ECMAScript 功能集的 JavaScript 功能。下列程式碼會檢查 ecmascript-2023 快照中所有 Baseline 新推出的功能：

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);
}

取得指定日期範圍內的所有基準功能

您可以查詢 baseline_date 欄位，找出特定日期範圍內成為基準的所有功能：

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);
}

上述程式碼範例會查詢 2022 年任何時間點成為 Baseline 廣泛支援的 CSS 功能。baseline_date 的查詢語法可讓您指定開始和結束日期，並以 .. 分隔。

結論

本指南中的查詢僅供參考，您可以從中著手，開始實驗如何查詢 webstatus.dev 後端。您可以使用任意數量的可用查詢參數，取得應用程式專屬的結果。

瞭解如何查詢 Web Platform Dashboard 的 HTTP API，有助於您建構實用的工作工具，並隨時掌握專案要使用的功能是否獲得廣泛的瀏覽器支援。也就是說，您可以使用現代瀏覽器功能建構網頁應用程式，提供更愉快的開發人員體驗。