نحوه پرس و جو از داشبورد پلتفرم وب برای ابزارهای پایه

Jeremy Wagner

منتشر شده: ۴ مارس ۲۰۲۵

Baseline توسط تیم کروم ابداع شد و اکنون توسط گروه جامعه WebDX تعریف می‌شود. Baseline به ویژگی‌هایی که بین مرورگرها قابل تعامل هستند، وضوح می‌بخشد. این ابزار به گونه‌ای طراحی شده است که به شما کمک کند تا ویژگی‌هایی را که می‌توانید یا نمی‌توانید در تمام موتورهای مرورگر اصلی استفاده کنید، شناسایی کنید. با این حال، شما به روشی برای شناسایی این ویژگی‌ها نیاز دارید.

خوشبختانه، شما می‌توانید با استفاده از داشبورد پلتفرم وب - که توسط بسته‌ی web-features npm پشتیبانی می‌شود - بررسی کنید که کدام ویژگی‌ها به تازگی یا به طور گسترده در Baseline در دسترس هستند. همچنین می‌توانید با استفاده از HTTP API آن به این اطلاعات دسترسی پیدا کنید تا داده‌های Baseline را در گردش کار ابزار خود ادغام کنید و این راهنما نحوه‌ی این کار را توضیح می‌دهد.

دستور زبان پرس و جوی پایه مرتبط با داشبورد پلتفرم وب

داشبورد پلتفرم وب از یک دستور زبان پرس‌وجوی خاص برای کمک به شما در جستجوی پشتیبانی از ویژگی‌های وب استفاده می‌کند. می‌توانید از این دستور زبان پرس‌وجو مستقیماً در خود داشبورد استفاده کنید.

همانطور که در کادر جستجو در بالای صفحه تایپ می‌کنید، تعدادی پارامتر جستجو به شما ارائه می‌شود که می‌توانید از آنها برای فیلتر کردن ویژگی‌های وب استفاده کنید.

دستور زبان پرس‌وجو رسا است و به شما انعطاف‌پذیری زیادی در نحوه فیلتر کردن ویژگی‌های وب نمایش داده شده در داشبورد می‌دهد. تصویر زیر نشان می‌دهد که چگونه می‌توان از پارامتر پرس‌وجوی id برای محدود کردن به یک ویژگی خاص استفاده کرد:

دستور زبان پرس‌وجو مستند شده است - اما دانستن همه آن برای یافتن داده‌های پایه برای ویژگی‌ها لازم نیست . می‌توانید از هر یک از این گزینه‌ها در داشبورد استفاده کنید، اما در اینجا برخی از آنها که به طور ویژه مفید هستند، آورده شده است:

• baseline_status : از این پارامتر برای فیلتر کردن ویژگی‌ها بر اساس سه مقدار شمارشی استفاده کنید:
  • limited : ویژگی‌هایی را برمی‌گرداند که پشتیبانی مرورگر محدودی دارند. اگر بر اساس این مقدار فیلتر کنید، فقط ویژگی‌هایی را دریافت خواهید کرد که به هیچ وضعیت پایه‌ای نرسیده‌اند.
  • newly : ویژگی‌هایی را برمی‌گرداند که به تازگی در نسخه پایه (Baseline) در دسترس قرار گرفته‌اند.
  • widely : ویژگی‌هایی را برمی‌گرداند که به صورت پایه‌ای و گسترده در دسترس هستند، یعنی ویژگی‌هایی که حداقل 30 ماه است که به صورت پایه‌ای ارائه شده‌اند. اینها ویژگی‌هایی هستند که می‌توانید بدون نگرانی در مورد پشتیبانی مرورگر یا polyfillها، انتظار استفاده از آنها را داشته باشید.
• baseline_date : از قالب YYYY-MM-DD..YYYY-MM-DD برای تعیین حد بالا و پایین برای زمانی که ویژگی‌ها به Baseline می‌رسند استفاده می‌کند. به عنوان مثال، برای یافتن همه ویژگی‌ها در بازه زمانی یک سال، از مقداری مانند 2024-01-01..2025-01-01 استفاده کنید.
• id : شناسه‌ی یک ویژگی مشخص. این شناسه‌ها در بسته‌ی web-features تعریف شده‌اند. برای مثال، ورودی ویژگی برای Promise.try() به شناسه‌ی promise-try نگاشت می‌شود.
• group : یکی از نام‌های گروه‌های شمارشی متعدد برای ویژگی‌ها. این معیار مفیدی است اگر فقط می‌خواهید برای زیرمجموعه خاصی از ویژگی‌های پلتفرم وب پرس‌وجو کنید. برای مثال، می‌توانید لیستی از ویژگی‌های CSS را با مقدار css فیلتر کنید.

اگرچه ظاهر داشبورد قطعاً مفید است، اما بر روی یک HTTP API قرار دارد که می‌توانید مستقیماً از آن پرس‌وجو کنید. برای مثال، در اینجا یک نقطه پایانی وجود دارد که تمام ویژگی‌های پایه که به تازگی در دسترس قرار گرفته‌اند را دریافت می‌کند:

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

ساختار پاسخ JSON

پاسخ JSON که از HTTP API دریافت می‌کنید، برای هر ویژگی، شکل ثابتی دارد. پاسخ برگردانده شده شامل یک ویژگی data در سطح بالا است. این ویژگی شامل آرایه‌ای از تمام ویژگی‌های منطبق است. اگرچه این لیست کاملی از تمام فیلدهای موجود در پاسخ JSON نیست، اما در اینجا به برخی از موارد مفید در مورد Baseline اشاره می‌کنیم:

• baseline : شامل اطلاعات کلی در مورد وضعیت خط پایه یک عارضه مشخص، با زیرفیلدهای زیر است:
  • status : وضعیت پایه برای یک ویژگی. مقادیر می‌توانند limited ، newly یا widely باشند. توجه: اگر status دارای مقدار limited باشد، این تنها زیرفیلد خواهد بود.
  • low_date : این فیلد نشان می‌دهد که ویژگی مورد نظر در چه تاریخی به صورت پایه (Baseline) و جدید (Newly) در دسترس قرار گرفته است. این فیلد فقط در صورتی نمایش داده می‌شود که status newly یا widely باشد.
  • high_date : این فیلد نشان می‌دهد که ویژگی مورد نظر در چه تاریخی به صورت گسترده در دسترس قرار گرفته است. این فیلد فقط در صورتی در دسترس است که status widely باشد.
• feature_id : شناسه‌ی ویژگی. برای مثال، برای CSS grid، این مقدار "grid" خواهد بود.
• name : نام قالب‌بندی‌شده‌ی ویژگی. این می‌تواند در برخی موارد مشابه feature_id باشد، اما معمولاً متفاوت است. برای مثال، مقدار feature_id برای Promise.try() برابر با "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 grid را دریافت کنیم، که به صورت Baseline Widely در دسترس است. به عنوان مثال، می‌توانید از این اطلاعات برای تشخیص استفاده از ویژگی استفاده کنید و به کاربران اطلاع دهید که می‌توانند از آن در تمام موتورهای مرورگر مدرن بدون نگرانی در مورد پشتیبانی استفاده کنند.

با این حال، این فقط یک شروع است و HTTP API می‌تواند کارهای بسیار بیشتری از دریافت داده‌ها برای یک ویژگی واحد برای شما انجام دهد.

تمام ویژگی‌های جدید و گسترده Baseline را دریافت کنید

فرض کنید می‌خواهید اسکریپتی داشته باشید که تمام ویژگی‌هایی را که یا به صورت پایه (Baseline) و یا به صورت گسترده (Widely Available) در دسترس هستند، دریافت کند. این می‌تواند مفید باشد، برای مثال، اگر اسکریپتی دارید که در یک بازه زمانی اجرا می‌شود و می‌خواهید یک لیست به‌روز شده دریافت کنید که با تغییر ویژگی‌ها از وضعیت دسترسی محدود به وضعیت پایه (Baseline) تغییر می‌کند:

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 Newly و Widely available را دریافت نمی‌کند، بلکه فقط ۱۰۰ ویژگی اول را دریافت می‌کند. اگر تعداد ویژگی‌های بازیابی شده از این مقدار بیشتر شود، یک فیلد metadata در سطح بالای پاسخ JSON وجود دارد که می‌تواند شامل حداکثر دو زیرفیلد باشد:

• next_page_token : رشته‌ای حاوی یک توکن که می‌توانید به رشته‌ی پرس‌وجوی درخواست GET به backend اضافه کنید. وقتی از آن استفاده می‌کنید و داده‌ها را از webstatus.dev backend دوباره واکشی می‌کنید، دسته‌ی بعدی ویژگی‌های منطبق را برمی‌گرداند. توجه: اگر پرس‌وجوی فعلی کمتر از ۱۰۰ نتیجه برگرداند، یا اگر پرس‌وجوی فعلی در انتهای مجموعه نتایج باشد، این فیلد در دسترس نخواهد بود.
• 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');

تمام ویژگی‌های CSS جدید موجود در نسخه پایه را دریافت کنید

فرض کنید شما یک مهندس با تمرکز ویژه بر CSS هستید و علاقه‌مندید بدانید کدام ویژگی‌های CSS به ویژگی‌های جدید پایه تبدیل می‌شوند. این یک مورد استفاده عالی برای مقدار پرس‌وجوی group و همچنین نحوه استفاده از عملگر AND هنگام پرس‌وجو از 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);
}

هنگام تعیین مقدار css برای group ، می‌توانید برای تمام ویژگی‌های جدید موجود در Baseline پرس‌وجو کنید. اگر می‌خواهید دامنه را گسترش دهید تا ویژگی‌های CSS موجود در Baseline را نیز شامل شود، می‌توانید از رویکرد نمونه کد قبلی استفاده کنید و از عملگر نفی با پرس‌وجویی مانند -baseline_status:limited AND group:css' استفاده کنید.

فیلد دیگری که می‌توانید از آن کوئری بگیرید، فیلد snapshot است که برای یافتن ویژگی‌های جاوااسکریپتی که بخشی از یک مجموعه خاص از ویژگی‌های ECMAScript هستند، مفید است. کد زیر تمام ویژگی‌های Baseline Newly available که بخشی از snapshot 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);
}

دریافت تمام ویژگی‌های پایه در یک محدوده تاریخی

می‌توان از فیلد baseline_date برای یافتن تمام ویژگی‌هایی که در یک محدوده تاریخی خاص به Baseline تبدیل شده‌اند، استفاده کرد:

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

نمونه کد قبلی، ویژگی‌های CSS را که در هر زمانی در سال ۲۰۲۲ به صورت گسترده در دسترس قرار گرفته‌اند، جستجو می‌کند. سینتکس پرس‌وجو برای baseline_date به شما امکان می‌دهد تاریخ شروع و پایان را که با .. از هم جدا شده‌اند، مشخص کنید.

نتیجه‌گیری

کوئری‌های این راهنما به عنوان نقطه شروعی برای شما در نظر گرفته شده‌اند تا بتوانید نحوه کوئری زدن به بک‌اند webstatus.dev را آزمایش کنید. با هر تعداد پارامتر کوئری موجود، باید بتوانید نتایجی را دریافت کنید که مختص برنامه شما هستند.

دانستن نحوه پرس و جو از HTTP API داشبورد پلتفرم وب به شما این امکان را می‌دهد که ابزارهایی بسازید که ممکن است برای کار شما مفید باشند و شما را از اینکه آیا ویژگی‌هایی که می‌خواهید برای پروژه خود استفاده کنید، از پشتیبانی مرورگر کافی برخوردارند یا خیر، مطلع نگه می‌دارد. این بدان معناست که می‌توانید برنامه‌های وب را با استفاده از ویژگی‌های مرورگر مدرن بسازید که می‌توانید با خیال راحت از آنها استفاده کنید و تجربه توسعه‌دهنده بسیار لذت‌بخش‌تری را ارائه دهید.