إنشاء أدوات Baseline باستخدام حزمة web-features

Jeremy Wagner
Rick Viscomi

تاريخ النشر: 12 سبتمبر 2025

تساعدك الأدوات الجديدة لمبادرة Baseline في تحديد ميزات الويب الآمنة للاستخدام في تطبيقات الويب اليوم. تستخدم هذه الأدوات، مثل أدوات التدقيق اللغوي وميزات بيئة التطوير المتكاملة، مصدر بيانات لميزات منصة الويب يحتوي على بيانات حول إمكانية استخدامها في المتصفحات الحديثة.

لوحة بيانات حالة "منصة الويب" هي أحد مصادر البيانات لهذه الميزات، وتوفّر واجهة برمجة تطبيقات HTTP قابلة للاستعلام. إنّ طلب البحث عن مصدر البيانات هذا عند الحاجة ليس عمليًا لجميع الأدوات. في العديد من حالات استخدام الأدوات، تكون حزمة 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 وJavaScript والمجموعات الأكثر تحديدًا.
  • ‫snapshots: يحتوي على إصدارات ECMAScript من ميزات JavaScript ذات الصلة، مثل ES2023 وES2022 وإصدارات ECMAScript الأخرى.

توفّر ميزة تصدير الميزات الخصائص التالية لإنشاء أدوات Baseline:

  • id: المعرّف الفريد للعنصر. على سبيل المثال، معرّف شبكة CSS هو "grid". ملاحظة: هذه ليست سمة ضمن عنصر البيانات. وهو مفتاح العنصر.
  • compat_features: مصفوفة من مفاتيح BCD الفردية المضمّنة في الميزة.
  • name: السلسلة القابلة للقراءة الخاصة باسم الميزة، مثل "Container Queries"
  • description: وصف موجز للميزة
  • ‫group: المجموعة التي تنتمي إليها الميزة. يتطابق ذلك مع بيانات المجموعة التي تم العثور عليها في عملية تصدير groups.
  • baseline: حالة "المقياس الأساسي" للميزة يمكن أن تكون إحدى القيم الثلاث التالية:
    1. ‫false: حالة الميزة هي "توفّر محدود".
    2. "low": تشير إلى أنّ الميزة متوفّرة حديثًا في الإصدار الأساسي.
    3. "high": تشير إلى أنّ الميزة متوفّرة على نطاق واسع.
    4. baseline_high_date: التاريخ الذي أصبحت فيه الميزة متاحة على نطاق واسع في Baseline ملاحظة: لا يتوفّر هذا الخيار إذا لم تكن الميزة متوفّرة على نطاق واسع في Baseline.
    5. baseline_low_date: يشير إلى تاريخ توفّر ميزة "الخط الأساسي الجديد". ملاحظة: لا تتوفّر هذه الميزة لميزات "التوفّر المحدود".

في ما يلي مثال على كائن البيانات الكامل لميزة الشبكة الفرعية في CSS:

"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". ملاحظة: هذا ليس سمة ضمن عنصر المجموعات. وهو مفتاح الكائن نفسه.
  • name: الاسم المعروض للمجموعة والذي يمكن للمستخدمين قراءته.
  • ‫parent: معرّف المجموعة الرئيسية للمجموعة. لا يتوفّر هذا الخيار إذا لم يكن للمجموعة مجموعة رئيسية.

أمثلة

توضّح الأمثلة التالية كيفية استخدام web-features package للحصول على البيانات التي تحتاج إليها لإنشاء أدوات Baseline.

البحث عن حالة 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 وكنت بحاجة إلى معرفة ما إذا كان زوج القيمة والخاصية متوافقًا مع المتصفحات الرئيسية، ستكون البيانات على مستوى الميزة غير دقيقة. يحدث ذلك لأنّ الحزمة تجمع كل ميزة على مستوى جميع مفاتيح 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"
  }
}

ترتيب الميزات حسب حالة "الخط الأساس"

يتكرّر هذا المثال خلال كل ميزة في عنصر الميزات ويصنّف كل ميزة في مصفوفة حسب حالة "الخط الأساس".

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.

العثور على جميع الميزات ضمن مجموعة

حتى الآن، تستخدم جميع الأمثلة المعروضة عملية التصدير features، ولكن عملية التصدير 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 القواعد التي تبدأ بعلامة @ والعناصر الزائفة والخصائص وأزواج الخصائص والقيم. بالنسبة إلى أداة Baseline linter، ابحث عن حالة كل رمز مميز باستخدام مفتاح BCD الخاص به، وليس باستخدام الميزة الرئيسية.

يحلّل محلّل لغوي مثل CSSTree رموز CSS، ويقسّم ورقة الأنماط إلى شجرة بنية مجردة (AST). يعرض المثال التالي قاعدة CSS تستخدم أداة اختيار فئة عامة وتعريف نمط:

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

سيبدو شجرة بناء الجملة المجردة على النحو التالي:

{
  "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"
                }
              ]
            }
          }
        ]
      }
    }
  ]
}

عند العثور على تعريف للسمة أثناء استعراض شجرة بنية التجريد، اربط اسم السمة بمفتاح 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" الحالة الأساسية إلى أنّ السمة متاحة على نطاق واسع، لذا لا يحتاج المدقّق اللغوي إلى إصدار تحذير. بعد ذلك، افحص قيمة السمة.

تعرض شجرة بنية التجريد أنّ قيمة هذه السمة هي auto-phrase. للحصول على مفتاح BCD المقابل، أضِف القيمة إلى مفتاح BCD الخاص بالعنصر الأصل: css.properties.word-break.auto-phrase.

في هذه الحالة، يشير web-features إلى أنّ حالة زوج القيمة والسمة word-break: auto-phrase ليست Baseline:

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

استخدِم المعلومات الواردة في مثال أداة التدقيق هذه لتنبيه المطوّر إلى أنّ زوج السمة والقيمة هذا ليس من سمات Baseline. يضمن هذا التحذير أن يعرف المطوّر أنّ هذه الميزة لن تعمل على النحو المتوقّع على مستوى محركات المتصفحات الرئيسية.

أمثلة من العالم الواقعي

تعرض الأمثلة السابقة الاستخدامات الأساسية لحزمة web-features. هناك عدد من الأدوات التي تستفيد من هذه البيانات. على سبيل المثال:

هناك المزيد من الأمثلة على كيفية استخدام مصدر البيانات هذا لإنشاء أدوات Baseline، ونأمل أن يصبح مشروعك أحدها.