این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

ابزارهای Baseline را با بسته ویژگی های وب ایجاد کنید

Jeremy Wagner

Rick Viscomi

منتشر شده: ۱۲ سپتامبر ۲۰۲۵

ابزارهای نوظهور برای Baseline به شما کمک می‌کند تا تعیین کنید کدام ویژگی‌های وب برای استفاده در برنامه‌های وب امروزی شما ایمن هستند. این ابزارها، مانند linterها و ویژگی‌های IDE، از یک منبع داده از ویژگی‌های پلتفرم وب استفاده می‌کنند که حاوی داده‌هایی در مورد پشتیبانی آنها در مرورگرهای مدرن است.

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

با بسته `web-features` شروع کنید

ابتدا، بسته را به عنوان یک وابستگی در پروژه خود نصب کنید:

npm install web-features

پس از نصب، یک یا چند اکسپورت نامگذاری شده را از بسته web-features به پروژه خود وارد کنید:

import { features, groups, browsers, snapshots } from 'web-features';

بسته به اهداف شما، ممکن است به همه این خروجی‌ها نیاز نداشته باشید. این خروجی‌ها اطلاعات زیر را ارائه می‌دهند:

features : آرایه‌ای از اشیاء که هر شیء نشان‌دهنده‌ی یک ویژگی وب است. این همان خروجی‌ای است که اغلب از آن استفاده خواهید کرد.
browsers : آرایه‌ای از اشیاء که مرورگرها را توصیف می‌کنند.
groups : آرایه‌ای از اشیاء که یک گروه‌بندی منطقی از ویژگی‌ها را تعریف می‌کند. این موارد در صورتی مفید هستند که هدف شما هدف قرار دادن زیرمجموعه‌ای از ویژگی‌های پلتفرم وب، مانند ویژگی‌های CSS، جاوا اسکریپت و گروه‌بندی‌های خاص‌تر باشد.
snapshots : شامل نسخه‌های ECMAScript از ویژگی‌های جاوا اسکریپت مربوطه، مانند ES2023، ES2022 و سایر نسخه‌های ECMAScript است.

اکسپورت ویژگی‌ها، ویژگی‌های زیر را برای ساخت ابزار Baseline فراهم می‌کند:

id : شناسه منحصر به فرد برای ویژگی. برای مثال، شناسه CSS Grid "grid" است. توجه : این یک ویژگی درون شیء داده نیست. بلکه کلید شیء است.
compat_features : آرایه‌ای از کلیدهای BCD مجزا که در این ویژگی گنجانده شده‌اند.
name : رشته‌ی قابل خواندن توسط انسان از نام ویژگی، مانند "Container Queries" .
description : شرح مختصری از ویژگی.
group : گروهی که ویژگی به آن تعلق دارد. این مربوط به داده‌های گروهی است که در خروجی groups یافت می‌شود.
baseline : وضعیت پایه ویژگی. این می‌تواند یکی از سه مقدار زیر باشد:
1. false : وضعیت این ویژگی «در دسترس بودن محدود» است.
2. "low »: این ویژگی در حالت پایه قرار دارد و به تازگی در دسترس قرار گرفته است.
3. "high »: این ویژگی در حالت پایه و به طور گسترده در دسترس است.
4. baseline_high_date : تاریخی که ویژگی به صورت گسترده در دسترس قرار گرفت. توجه : اگر ویژگی به صورت گسترده در دسترس نباشد، این تاریخ در دسترس نخواهد بود.
5. baseline_low_date : تاریخی که ویژگی به تازگی در دسترس قرار گرفته است. توجه : این برای ویژگی‌های با دسترسی محدود در دسترس نیست.

مثال زیر شیء داده کامل برای ویژگی CSS subgrid است:

"subgrid": {
  "caniuse": "css-subgrid",
  "compat_features": [
    "css.properties.grid-template-columns.subgrid",
    "css.properties.grid-template-rows.subgrid"
  ],
  "description": "The subgrid value for the grid-template-columns and grid-template-rows properties allows a grid item to inherit the grid definition of its parent grid container.",
  "description_html": "The <code>subgrid</code> value for the <code>grid-template-columns</code> and <code>grid-template-rows</code> properties allows a grid item to inherit the grid definition of its parent grid container.",
  "group": "grid",
  "name": "Subgrid",
  "spec": "https://drafts.csswg.org/css-grid-2/#subgrids",
  "status": {
    "baseline": "low",
    "baseline_low_date": "2023-09-15",
    "support": {
      "chrome": "117",
      "chrome_android": "117",
      "edge": "117",
      "firefox": "71",
      "firefox_android": "79",
      "safari": "16",
      "safari_ios": "16"
    }
  }
}

خروجی groups ، داده‌هایی در مورد گروه‌بندی ویژگی‌ها با ساختار زیر ارائه می‌دهد:

id : شناسه منحصر به فرد برای گروه. برای مثال، ویژگی‌های CSS دارای شناسه "css" هستند. توجه: این یک ویژگی درون شیء groups نیست. بلکه خود کلید شیء است.
name : نام گروه که برای انسان قابل خواندن است.
parent : شناسه گروه والد گروه. اگر گروه والد نداشته باشد، این شناسه در دسترس نیست.

مثال‌ها

مثال‌های زیر نحوه استفاده از web-features package برای دریافت داده‌های مورد نیاز برای ساخت ابزار Baseline نشان می‌دهند.

وضعیت پایه یک ویژگی خاص را جستجو کنید

import { features } from 'web-features';

function getBaselineStatus (featureId) {
  return features[featureId]?.status.baseline;
}

این مثال، مستقیم‌ترین مورد استفاده برای بسته‌ی web-features را نشان می‌دهد، که در آن شما شناسه‌ی یک ویژگی را برای دسترسی به داده‌های پایه‌ی آن در ویژگی status.baseline مشخص می‌کنید. این ویژگی به شما می‌گوید که آیا یک ویژگی در دسترس‌پذیری محدود، تازه در دسترس یا به‌طور گسترده در دسترس است. در دو مورد اخیر، شما همچنین به تاریخ‌هایی دسترسی دارید که نشان می‌دهند چه زمانی ویژگی به یک آستانه‌ی پایه‌ی خاص رسیده است.

وضعیت پایه را برای یک کلید BCD خاص جستجو کنید

BCD مخفف browser-compat-data است، پروژه‌ای که توسط MDN برای فهرست‌بندی پشتیبانی از ویژگی‌ها در مرورگرها نگهداری می‌شود. یک کلید BCD مربوط به یک ویژگی جزئی است، مانند یک مقدار خاص از ویژگی CSS یا یک زیرویژگی رفتاری که توسط مشخصات تعریف شده است.

پروژه web-features کلیدهای BCD مرتبط را برای هر ویژگی در آرایه compat_features گروه‌بندی می‌کند. گاهی اوقات به وضعیت پایه یک کلید BCD نیاز دارید، نه وضعیت پایه کلی برای کل ویژگی. به عنوان مثال، اگر یک CSS linter ایجاد کنید و نیاز داشته باشید بدانید که آیا یک جفت ویژگی-مقدار در مرورگرهای اصلی سازگار است یا خیر، داده‌های سطح ویژگی بسیار نامفهوم هستند. این اتفاق می‌افتد زیرا این بسته هر ویژگی را روی تمام کلیدهای BCD تشکیل‌دهنده آن جمع می‌کند و برخی از کلیدها پشتیبانی مرورگر بهتری نسبت به سایرین دارند.

برای جستجوی وضعیت پایه یک کلید BCD، ویژگی status.by_compat_key از شیء ویژگی (موجود در web-features 3.6.0 و بالاتر) را بررسی کنید:

import { features } from 'web-features';

function getBaselineStatus (featureId, bcdKey) {
  return features[featureId]?.status.by_compat_key[bcdKey];
}

برای مثال، خروجی تابع getBaselineStatus('outline', 'css.properties.outline') به صورت زیر است:

{
  "baseline": "low",
  "baseline_low_date": "2023-03-27",
  "support": {
    "chrome": "94",
    "chrome_android": "94",
    "edge": "94",
    "firefox": "88",
    "firefox_android": "88",
    "safari": "16.4",
    "safari_ios": "16.4"
  }
}

مرتب‌سازی ویژگی‌ها بر اساس وضعیت پایه

این مثال روی تک تک ویژگی‌های موجود در شیء features تکرار می‌کند و هر یک را بر اساس وضعیت پایه (Baseline) آن در یک آرایه مرتب می‌کند.

import { features } from "web-features";

const webFeatures = Object.values(features);

const widelyAvailable = webFeatures.filter(feature => {
  return feature.status.baseline === 'high';
});

const newlyAvailable = webFeatures.filter(feature => {
  return feature.status.baseline === 'low';
});

const limitedAvailability = webFeatures.filter(feature => {
  return feature.status.baseline === false;
});

این مثال نحوه کار با ویژگی status.baseline را در ابزار شما نشان می‌دهد. برای مثال، می‌توانید از این رویکرد در یک برنامه وب برای نمایش لیستی از تمام ویژگی‌های وب بر اساس وضعیت Baseline آنها استفاده کنید.

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

تاکنون، تمام مثال‌های نشان داده شده از export features استفاده می‌کنند، اما export groups تمام ویژگی‌ها را به صورت منطقی درون گروه‌ها سازماندهی می‌کند. این بدان معناست که برای مثال می‌توانید تمام ویژگی‌هایی را که بخشی از View Transitions هستند، پیدا کنید:

import { features, groups } from 'web-features';

const groupKeys = Object.keys(groups);
const featuresData = Object.values(features);

const viewTransitionsGroup = groupKeys.find(groupKey => {
  return groupKey === 'view-transitions';
});

const viewTransitionsFeatures = featuresData.filter(feature => {
  return feature.group === viewTransitionsGroup;
});

اشتراک بین features و خروجی‌های group به شما امکان می‌دهد جستجوی خود را برای ویژگی‌های وب بر اساس گروهی که به آن تعلق دارند، محدود کنید.

همه چیز را کنار هم قرار دادن

شما می‌توانید از جستجوها برای ساخت ابزارهای مفید، مثلاً برای ایجاد یک خط‌کش CSS، استفاده کنید.

لینترهای CSS جفت‌های at-rules، pseudo-elements، propertyها و property-value را ارزیابی می‌کنند. برای لینتر Baseline خود، وضعیت هر توکن را با کلید BCD آن جستجو کنید، نه با ویژگی والد آن.

یک تجزیه‌گر مانند CSSTree، CSS را توکنیزه می‌کند و یک stylesheet را به یک درخت نحوی انتزاعی (AST) می‌شکند. مثال زیر یک قانون CSS را نشان می‌دهد که از یک انتخابگر کلاس عمومی و یک اعلان سبک استفاده می‌کند:

.foo {
  word-break: auto-phrase;
}

AST چیزی شبیه به این خواهد بود:

{
  "type": "StyleSheet",
  "children": [
    {
      "type": "Rule",
      "prelude": {
        "type": "SelectorList",
        "children": [
          {
            "type": "Selector",
            "children": [
              {
                "type": "ClassSelector",
                "name": "foo"
              }
            ]
          }
        ]
      },
      "block": {
        "type": "Block",
        "children": [
          {
            "type": "Declaration",
            "important": false,
            "property": "word-break",
            "value": {
              "type": "Value",
              "children": [
                {
                  "type": "Identifier",
                  "name": "auto-phrase"
                }
              ]
            }
          }
        ]
      }
    }
  ]
}

وقتی هنگام پیمایش AST، یک اعلان ویژگی پیدا می‌کنید، نام آن ویژگی را به کلید BCD مربوطه‌اش نگاشت کنید تا وضعیت Baseline آن بررسی شود. BCD ویژگی‌های CSS را تحت شیء css.properties دسته‌بندی می‌کند، بنابراین کلید BCD مربوطه css.properties.word-break است.

سپس، ویژگی مرتبط با آن کلید BCD را پیدا کنید و وضعیت آن را بررسی کنید.

// Assuming we only know the BCD key and not the feature ID.
const bcdKey = 'css.properties.word-break';
const [featureId, feature] = Object.entries(features).find(([id, feature]) =>
  feature.compat_features?.includes(bcdKey)
) || [];
const status = feature?.status.by_compat_key[bcdKey];

وضعیت پایه برای ویژگی word-break به شرح زیر است:

{
  "baseline": "high",
  "baseline_high_date": "2018-03-30",
  "baseline_low_date": "2015-09-30",
  "support": {
    "chrome": "44",
    "chrome_android": "44",
    "edge": "12",
    "firefox": "15",
    "firefox_android": "15",
    "safari": "9",
    "safari_ios": "9"
  }
}

وضعیت خط پایه "high" نشان می‌دهد که ملک به طور گسترده در دسترس است، بنابراین نیازی نیست که خط‌کش شما هشداری صادر کند. در مرحله بعد، ارزش ملک را بررسی کنید.

AST نشان می‌دهد که مقدار این ویژگی auto-phrase است. برای دریافت کلید BCD مربوطه، مقدار را به کلید BCD ویژگی والد اضافه کنید: css.properties.word-break.auto-phrase .

نکته: این روش فقط برای مقادیری که مشخصات ویژگی آنها را نامگذاری می‌کند، کار می‌کند. انواع مقادیر عمومی مانند اعداد یا نام رنگ‌ها، کلیدهای BCD مخصوص به خود را ندارند. اگر web-features داده‌ای برای یک کلید BCD مشخص برنمی‌گرداند، چیزی برای اعتبارسنجی وجود ندارد، بنابراین آن را نادیده بگیرید.

در این حالت، web-features نشان می‌دهد که وضعیت جفت ویژگی-مقدار word-break: auto-phrase برابر با Baseline نیست:

{
  "baseline": false,
  "support": {
    "chrome": "119",
    "chrome_android": "119",
    "edge": "119"
  }
}

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

مثال‌های دنیای واقعی

مثال‌های قبلی کاربردهای اولیه‌ی بسته‌ی web-features را نشان می‌دهند. در حال حاضر تعدادی ابزار وجود دارند که از این داده‌ها بهره می‌برند. به عنوان مثال:

eslint-css از بسته web-features در قانون use-baseline خود برای lint کردن ویژگی‌های خاص استفاده می‌کند.
کارت‌های شناور در ویژوال استودیو کد از بسته‌ی web-features برای نمایش اطلاعات پایه برای ویژگی‌های CSS و ویژگی‌های HTML استفاده می‌کنند.
MDN از داده‌های web-features موجود در بنرهای اکثر صفحات ویژگی (برای مثال، abs() ) برای اطلاع‌رسانی وضعیت پایه آنها استفاده می‌کند.

مثال‌های بیشتری وجود دارد که نشان می‌دهد چگونه می‌توان از این منبع داده برای ساخت ابزارهای Baseline استفاده کرد - و ما امیدواریم که پروژه شما یکی از آنها باشد!