كيفية تحديث قاعدة الرموز البرمجية باستخدام "إرشادات الويب الحديث" وأهمية ذلك

لا يتم تطوير معظم الويب من الصفر. ويحدث ذلك في قواعد الرموز البرمجية الحالية التي تراكمت فيها سنوات من الحلول البديلة القديمة وpolyfills وأدوات JavaScript المساعدة (الحجم التلقائي، وحيل تصميم مربّعات الاختيار المخصّصة، ومستمعي scrollHeight) للأمور التي يتعامل معها المتصفّح الآن بشكلٍ أصلي. لكن المشكلة هي: الرمز القديم لا ينكسر. إنّه يعمل، لذا لا يقدّم أحد تقريرًا عن خطأ. ويتطلب الأمر أيضًا الثقة لإعادة صياغة الرموز البرمجية العاملة، حتى لو كانت قديمة، لذا من المفهوم أن يتردد المطوّرون في ذلك.

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

عند إنشاء تطبيق جديد، يوجّه "إرشادات الويب الحديث" الوكيل نحو ميزات Baseline الحديثة. بالنسبة إلى الرموز البرمجية الحالية، يضيف الإصدار 1.0 من "إرشادات الويب الحديث" سير عمل للتحديث يفحص مشروعك بحثًا عن الأنماط القديمة ويساعد وكيلك في ترقيتها.

ما يفعله سير عمل التحديث

عندما تطلب من وكيلك تحديث مشروع (أو من خلال تشغيل الأمر legacy-scan مباشرةً)، إليك طريقة عمله:

  • الفحص المحلي الحتمي: يتم فحص ملفات HTML وCSS وJavaScript/TypeScript والمكوّنات الخاصة بإطار العمل وملفات package.json بسرعة باستخدام أدوات تحليل Abstract Syntax Tree (AST) وDOM وCSS محليًا بدون أي طلبات من نموذج لغوي كبير أو تكلفة الرموز المميّزة.
  • قائمة القواعد القديمة: يتم تجاهل الماسح الضوئي الذي يضع علامة على عدد كبير جدًا من العناصر في كل عملية تشغيل. اختبرنا القواعد المرشحة على حوالي 45,000 مستودع مفتوح المصدر مقسم إلى نصفين: تمت كتابة القواعد وضبطها على النصف المخصص لكتابة القواعد، وتم تقييمها على النصف الآخر الذي لم يسبق رؤيته. لقد استبعدنا قواعد أكثر مما احتفظنا به، وتجاوزنا الميزات التي ليس لها مكافئ في الرموز البرمجية القديمة، وألغينا عمليات الاستبدال التي تقتصر على البنية النحوية بدون فائدة حقيقية (مثل إعادة كتابة محددات العناصر الشقيقة + أو ~ التي تعمل بشكل صحيح إلى :has()). لكي يتم تفعيل القاعدة تلقائيًا، يجب أن تحقّق دقة مطابقة ثابتة بنسبة %80 على الأقل ودقة بنسبة %90 بعد التحقّق من الرموز البرمجية غير المرئية.
  • فلترة النتائج الموجبة الخاطئة المستندة إلى السياق: يتضمّن كل تطابق للقواعد قواعد تقييم واضحة لـ keepWhen/dropWhen. يؤدي ذلك إلى توجيه الوكيل لتقييم الرموز البرمجية المحيطة، واستبعاد الرموز الاحتياطية المقصودة أو حواجز CSS @supports أو الرموز المتشابهة قبل عرض النتائج.
  • التركيز على الأنماط القديمة عالية الثقة (والتوسّع): legacy-scan يتحقّق من المجموعة الفرعية من أدلتنا التي يبلغ عددها 200 تقريبًا (حوالي %20) حيث يمكن رصد الرموز البرمجية القديمة بشكل حتمي بدون نتائج موجبة خاطئة، ونحن نعمل على توسيع نطاق هذه التغطية بمرور الوقت. بالنسبة إلى بقية الكتالوج، يبحث الوكيل عن الأدلة ويستردّها أثناء عملية الإنشاء.

كيفية استدعاء سير عمل التحديث

يتطلّب تحديث الرموز البرمجية باستخدام إرشادات الويب الحديث الإصدار 1.0 أو إصدار أحدث. يمكنك تثبيته أو تحديثه باستخدام npm أو سوق المكوّنات الإضافية للوكيل:

# Install Modern Web Guidance 1.0 in your project
npx modern-web-guidance@latest install

# Or update an existing installation
npx modern-web-guidance@latest update

بما أنّ سير عمل التحديث هو جزء من تعريف المهارة الأساسية، يمكنك تفعيل الماسح الضوئي باستخدام لغة طبيعية من خلال الطلب من الوكيل البحث عن "الأنماط القديمة" أو "التحديث" في مستودع أو مجلد.

ملاحظة: ستؤدي تسمية مكوّن واحد إلى إجراء بحث عادي في الدليل بدلاً من ذلك.

للتوضيح، إليك مثال على طلب لفحص مستودع كامل:

Modernize this repository using Modern Web Guidance. Scan our frontend files for legacy patterns, verify the findings, and propose a modernization plan before making any code edits.

يمكنك أيضًا توجيهه إلى مجلد معيّن:

Check src/components/forms for legacy web patterns that can be refactored to modern Baseline features.

على الرغم من أنّه يمكنك حاليًا تشغيل legacy-scan يدويًا في الوحدة الطرفية، فإنّ عمليات الدمج الآلية في مسار CI/CD قيد التطوير حاليًا.

أمثلة على الأنماط التي يرصدها ويصلحها

تستهدف القواعد المؤهَّلة الأنماط القديمة الشائعة في أربعة مجالات: النماذج وواجهة المستخدم ومربّعات الحوار وعناصر التحكّم وتنسيق CSS والخطوط والتصميم المرئي والأمان. في ما يلي جدول يتضمّن أمثلة على الأنماط القديمة والبدائل الحديثة لها:

النطاق تم رصد نمط قديم بديل حديث
النماذج وواجهة المستخدم أدوات الربط لتغيير حجم textarea في JS scrollHeight تلقائيًا ‫CSS field-sizing: content (form-fields-automatically-fit-contents)
النماذج وواجهة المستخدم أدخِل معالِجات الإرسال keydown التي لا تتضمّن حماية من أساليب الإدخال if (e.isComposing || e.keyCode === 229) return; (ime-safe-enter-submit)
النماذج وواجهة المستخدم تطبيق نمط CSS على حقول الإدخال غير المعدَّلة في وقت مبكر من خلال السمة :invalid عند التحميل الفئتان الصوريتان :user-invalid و:user-valid (validate-input-after-interaction)
النماذج وواجهة المستخدم عدم توفّر رموز autocomplete المميّزة في نماذج المصادقة والدفع قيم autocomplete الموحّدة (autofill-sign-in-form وautofill-payment-form)
مربّعات الحوار وعناصر التحكّم ‫e.target === dialog متتبِّع نقرات يمنع تحديد النص من خلال السحب ‫<dialog closedby="any"> مع التحسين التدريجي (مربّع حوار)
مربّعات الحوار وعناصر التحكّم متتبِّعات النقرات الإلزامية لـ addEventListener على الإعلانات التي تظهر على سطح الفيديو السمتان التعريفيّتان popover وpopovertarget (declarative-dialog-popover-control)
تخطيط CSS وأسلوب الخط والتصميم المرئي ‫max-height: 9999px حيل لتعديل الصور المتحركة في قائمة الأكورديون ‫interpolate-size: allow-keywords وcalc-size() (animate-to-intrinsic-sizes)
تخطيط CSS وأسلوب الخط والتصميم المرئي تبديل الفئة الرئيسية في JS استنادًا إلى حالة الفئة الفرعية أدوات الاختيار العلائقية :has(:checked) / :has(:focus-visible) (child-state-based-styling)
تخطيط CSS وأسلوب الخط والتصميم المرئي تم تكرار @media (prefers-color-scheme: dark) مجموعة دالة CSS light-dark() (dark-mode وdark-mode-toggle)
الأمان علامات النصوص البرمجية لشبكة توصيل المحتوى (CDN) الخارجية لا تتضمّن ميزة "سلامة الموارد الفرعية" السمتان integrity وcrossorigin="anonymous" (secure-external-subresources)

أمثلة على تحويل الرموز البرمجية

عند الطلب، يمكن لوكيل الترميز تحويل الأنماط القديمة غير الفعّالة إلى أنماط حديثة باستخدام سير عمل التحديث. وفي ما يلي بعض الأمثلة على ذلك:

عناصر <textarea> تتوسّع تلقائيًا

يؤدي استخدام JavaScript القديمة لقياس scrollHeight في كل حدث input إلى حدوث تكرار في عرض التنسيق. وقد يؤدي ذلك إلى حدوث مشاكل في الأداء، خاصةً في ما يتعلق بمدى استجابة الصفحة لتفاعلات المستخدم (INP). باستخدام سير عمل التحديث، يمكن للوكيل إصلاحها:

// Before: Imperative layout recalculation on every keystroke
textarea.addEventListener('input', () => {
  textarea.style.height = 'auto';
  textarea.style.height = `${textarea.scrollHeight}px`;
});

لا تحتاج إلى JavaScript لإجراء ذلك اليوم. يوجّه سير عمل التحديث الوكيل لاستبدالها بـ CSS:

/* After: Native declarative field sizing */
textarea {
  field-sizing: content;
  min-block-size: 3lh;
  max-block-size: 15lh;
}

النوافذ المنبثقة التعريفية

يمكن استبدال منطق النوافذ المشروطة والنوافذ المنبثقة المخصّصة التي تستخدم متتبِّعات أحداث JavaScript بسمات HTML العادية:

<!-- Before: a click listener that only calls showPopover() -->
<button id="openBtn">Open Menu</button>
<div id="menu" popover>Menu Content</div>
<script>
  openBtn.addEventListener('click', () => menu.showPopover());
</script>

<!-- After: declarative control, no JavaScript -->
<button popovertarget="menu">Open Menu</button>
<div id="menu" popover>Menu Content</div>

إرسال آمن لمحرر أسلوب الإدخال (IME)

تؤدي أدوات الاستماع إلى مفتاح Enter غير المحمية إلى إرسال الرسائل قبل الأوان عندما يكتب المستخدمون في محرّرات أسلوب الإدخال (IME) باللغة اليابانية أو الصينية أو الكورية.

يضيف الوكيل حواجز حالة الإنشاء:

// Before: Fires mid-composition when confirming kanji/hanzi characters
textarea.addEventListener('keydown', (e) => {
  if (e.key === 'Enter' && !e.shiftKey) {
    e.preventDefault();
    sendMessage();
  }
});


// After: Accurately checks IME composition state
textarea.addEventListener('keydown', (e) => {
  if (e.key === 'Enter' && !e.shiftKey) {
    e.preventDefault();
    if (e.isComposing || e.keyCode === 229) return;
    sendMessage();
  }
});

طريقة العمل: سير عمل التحديث المكوّن من أربع خطوات

تتطلب إعادة هيكلة الرموز البرمجية في تطبيق حالي ثقة كبيرة، لأنّ لا أحد يريد مواجهة مشاكل في الأداء أو تراجعات طفيفة. ولهذا السبب أيضًا، لا تتوفّر علامة --fix: فحتى عمليات التحديث التي تبدو بسيطة غالبًا ما تتبيّن أنّها عمليات إعادة هيكلة على مستوى الطبقات، مثل حذف مستمع JS إلزامي أو حزمة npm ونقل السلوك إلى HTML وCSS، مع تحديات دقيقة في السلوك ودعم المتصفّح.

بدلاً من ذلك، يشغّل سير عمل التحديث حلقة من أربع خطوات مع وكيل الترميز:

  1. الفحص (legacy-scan): يشغّل الوكيل npx modern-web-guidance legacy-scan <path> --json، الذي يفحص الملفات مسبقًا بحثًا عن سلاسل فرعية ذات صلة، بحيث لا يشغّل سوى المحللات اللغوية لـ AST وCSS وHTML على الملفات والقواعد المرشحة. إذا وصل الاكتشاف إلى هذه المرحلة، فهناك احتمال كبير (حوالي %92) بأنّه ليس موجبًا خاطئًا. تتضمن كل مباراة قائمة تحقق للتحقق من الوكيل.
  2. التحقّق من السياق (keepWhen/dropWhen): بما أنّ وكيل الترميز لديه المستودع مفتوحًا، يفحص الرمز المحيط بكل مطابقة وفقًا لقاعدة التحقّق من الصحة. إذا كانت قراءة scrollHeight جزءًا من التمرير الافتراضي بدلاً من اختراق <textarea>، أو إذا كان فحص @supports يحمي السمة، يتم تجاهل النتيجة بدون إشعار.
  3. التقرير: يلخّص الوكيل النتائج التي تم التحقّق منها (مع الإشارة إلى أنّ legacy-scan يغطي المجموعة الفرعية من الأدلة التي تتضمّن قواعد حتمية، بالإضافة إلى خطة التحديث إذا طلبت مراجعة خطة قبل إجراء التعديلات).
  4. استرداد الدليل وإعادة التصميم والتحقّق من الاختبار: عندما يُطلب من الوكيل تحديث الرمز، يشغّل npx modern-web-guidance retrieve <guide-id> لجلب الدليل المناسب. ينفّذ الأداة إعادة تصميم الرمز البرمجي وفقًا لأنماط التوافق مع Baseline في الدليل، ويعيد تشغيل legacy-scan <path> على الملفات المعدَّلة إلى جانب الحزمة الاختبارية للمشروع للتأكّد من حلّ المشكلة.

للتجربة:

سواء كنت تشغّل legacy-scan لمرة واحدة في الوحدة الطرفية أو تطلب من وكيل الترميز تحديث وحدة قديمة، يساعدك سير عمل التحديث في سداد ديون منصة الويب القديمة بدون ضوضاء أدوات التحقّق من الأخطاء التقليدية.

يمكنك استخدام &quot;إرشادات الويب الحديث&quot; مع &quot;أدوات مطوّري البرامج في Chrome المخصّصة للوكلاء&quot; للانتقال من تحديث الرموز البرمجية الثابتة إلى التحقّق من المتصفّح المباشر وقياس الأداء وتصحيح الأخطاء.

الخطوات التالية والموارد