بیشتر توسعه‌های وب از ابتدا انجام نمی‌شود. این اتفاق در پایگاه‌های کد موجود رخ می‌دهد که سال‌ها راه‌حل‌های موقت قدیمی، شبیه‌سازهای مرورگر، و ابزارهای جاوا اسکریپت (اندازه خودکار، ترفندهای سفارشی سبک‌بندی چارگوش انتخاب، شنوندگان scrollHeight) را برای مواردی که مرورگر اکنون به‌طور بومی مدیریت می‌کند، جمع‌آوری کرده‌اند. اما مشکل اینجاست:
کد قدیمی خراب نمی‌شود. کار می‌کند، بنابراین هیچ‌کس گزارش اشکالی ثبت نمی‌کند. همچنین برای بازسازی کد فعال (حتی اگر قدیمی باشد) به اعتماد نیاز است، بنابراین توسعه‌دهندگان به‌طور قابل‌درکی تمایلی به این کار ندارند.
ازسوی دیگر، بازسازی نکردن کد قدیمی برای استفاده از ویژگی‌های وب مدرن به‌طور نامحسوس ازنظر اندازه بسته، پاسخ‌گویی صفحه، و دسترس‌پذیری برایتان هزینه خواهد داشت. بدتر اینکه وقتی از عامل‌های کدنویسی در این پروژه‌ها استفاده می‌کنید، آن‌ها قراردادهای سال ۲۰۱۵ را به‌همراه الگوهای قدیمی از داده‌های آموزشی‌شان کپی می‌کنند.
وقتی چیز جدیدی می‌سازید، «راهنمای وب نوین» نماینده شما را به‌سمت ویژگی‌های نوین Baseline هدایت می‌کند. برای کدهای موجود، Modern Web Guidance 1.0 گردش کار نوسازی را اضافه می‌کند که پروژه شما را برای الگوهای قدیمی اسکن می‌کند و به کارگزار شما کمک می‌کند آن‌ها را ارتقا دهد.
گردش کار نوسازی چه کاری انجام می‌دهد
وقتی از عاملتان می‌خواهید پروژه‌ای را مدرن‌سازی کند (یا با اجرای مستقیم فرمان legacy-scan
)، نحوه عملکرد آن به این صورت است:
- اسکن محلی قطعی: HTML، CSS، JavaScript/TypeScript، مؤلفه‌های مختص چارچوب، و فایل‌های
package.jsonبه‌سرعت با تجزیه‌کننده‌های «درخت نحو انتزاعی» (AST)، DOM، و CSS به‌صورت محلی و بدون هیچ‌گونه فراخوانی LLM یا هزینه ژتون اسکن می‌شوند. - کاتالوگ قانون قدیمی: اسکنری که در هر اجرا موارد زیادی را پرچم‌گذاری می‌کند
نادیده گرفته می‌شود. قوانین نامزد را در حدود ۴۵٬۰۰۰ مخزن متن‌باز که به دو نیم تقسیم شده بودند آزمایش کردیم: قوانین در نیمه قانون‌نویسی نوشته و تنظیم شدند و در نیمه نگهداشته‌شده نادیده نمره‌گذاری شدند. ما بیشتر از اینکه قوانین نامزد را نگه داریم، آن‌ها را کنار گذاشتیم و از ویژگی‌هایی که معادل کد قدیمی ندارند صرف‌نظر کردیم و جابه‌جایی‌های صرفاً نحوی را که هیچ بازده واقعی ندارند (مانند بازنویسی انتخابگرهای خواهر و برادر فعال
+یا~به:has()) کنار گذاشتیم. برای ارسال به‌صورت پیش‌فرض، یک قانون باید حداقل به ۸۰٪ دقت تطبیق‌دهنده ایستا و ۹۰٪ دقت پس‌از تأیید در کد دیده‌نشده برسد. - فیلتر کردن مثبت کاذب با تشخیص بافت: هر تطابق قانون با دستورالعمل‌های صریح
keepWhen/dropWhenهمراه است. این به نماینده می‌گوید که کد اطراف را ارزیابی کند و قبل‌از ارائه یافته‌هایش، از بازگشت‌های عمدی، محافظ‌های CSS@supports، یا موارد مشابه صرف‌نظر کند. - محدود به الگوهای قدیمی با اطمینان بالا (و درحال رشد):
legacy-scanزیرمجموعه حدود ۲۰۰ راهنمای ما (تقریباً ۲۰٪) را بررسی می‌کند که در آن کد قدیمی می‌تواند به‌طور قطعی و بدون موارد مثبت کاذب شناسایی شود، و ما درحال گسترش این پوشش درطول زمان هستیم. برای بقیه کاتالوگ، عامل شما راهنماها را هنگام ساختن جستجو و بازیابی می‌کند.
نحوه فراخوانی گردش کار مدرن‌سازی
نوسازی کد با «راهنمای وب نوین» به نسخه ۱.۰ یا بالاتر نیاز دارد. آن را با 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> با رشد خودکار
جاوا اسکریپت قدیمی که scrollHeight را در هر رویداد input اندازه‌گیری می‌کند، باعث خرابی چیدمان می‌شود. این امر می‌تواند باعث مشکلات عملکردی شود—به‌ویژه با تعامل تا ترسیم بعدی (INP). بااستفاده از گردش کار مدرن‌سازی،
نماینده شما می‌تواند آن را برطرف کند:
// Before: Imperative layout recalculation on every keystroke
textarea.addEventListener('input', () => {
textarea.style.height = 'auto';
textarea.style.height = `${textarea.scrollHeight}px`;
});
امروز برای این کار به جاوا اسکریپت نیاز ندارید. گردش کار نوسازی، نماینده شما را راهنمایی می‌کند تا آن را با CSS جایگزین کند:
/* After: Native declarative field sizing */
textarea {
field-sizing: content;
min-block-size: 3lh;
max-block-size: 15lh;
}
بالاپرهای اظهاری
منطق پنجره بازشو و مدال سفارشی بااستفاده از شنوندگان رویداد جاوا اسکریپت را می‌توان با مشخصه‌های 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
وقتی کاربران در «ویرایشگرهای روش ورودی» (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—با چالش‌های رفتار ظریف و
پشتیبانی مرورگر.
درعوض، گردش کار نوسازی یک حلقه چهارمرحله‌ای را با عامل کدنویسی شما اجرا می‌کند:
- اسکن (
legacy-scan): عاملnpx modern-web-guidance legacy-scan <path> --jsonرا اجرا می‌کند که فایل‌ها را برای رشته‌های فرعی مرتبط پیش‌غربالگری می‌کند تا فقط تجزیه‌کننده‌های AST، CSS، و HTML را روی فایل‌ها و قوانین نامزد اجرا کند. اگر یافته‌ای به این مرحله برسد، احتمال زیادی وجود دارد (حدود ۹۲٪) که مثبت کاذب نباشد. هر مطابقت شامل یک بازبینه درستی‌سنجی برای نماینده است. - درستی‌سنجی زمینه‌ای (
keepWhen/dropWhen): چون عامل کدنویسی مخزن را باز کرده است، کد اطراف هر تطابق را براساس معیار درستی‌سنجی آن قانون بررسی می‌کند. اگر خواندنscrollHeightبخشی از پیمایش مجازی‌شده باشد و نه رخنه‌گری<textarea>، یا اگر بررسی@supportsازقبل از ویژگی محافظت کند، یافته بدون اطلاع‌رسانی حذف می‌شود. - گزارش: نماینده یافته‌های درستی‌سنجی‌شده را خلاصه می‌کند (با ذکر اینکه
legacy-scanزیرمجموعه راهنماها را با قوانین قطعی پوشش می‌دهد، به‌علاوه طرح نوسازی اگر قبل‌از ویرایش کردن درخواست بازبینی طرح را داده باشید). - بازیابی راهنما، بازسازی کد، و درستی‌سنجی آزمایش: وقتی از نماینده خواسته می‌شود که مدرن‌سازی کند، نماینده
npx modern-web-guidance retrieve <guide-id>را اجرا می‌کند تا راهنمای مناسب را واکشی کند. این ابزار بازسازی کد را طبق الگوهای سازگاری Baseline راهنما اجرا می‌کند وlegacy-scan <path>را روی فایل‌های اصلاح‌شده در کنار مجموعه آزمون پروژه دوباره اجرا می‌کند تا رفع مشکل را تأیید کند.
امتحان کنید
چه درحال اجرای یک legacy-scan یک‌باره در پایانه باشید، چه از عامل کدنویسی‌تان بخواهید یک واحد قدیمی‌تر را مدرن‌سازی کند، گردش کار مدرن‌سازی به شما کمک می‌کند بدهی پلاتفرم وب قدیمی را بدون سروصدای خطایاب‌های نحوی سنتی پرداخت کنید.
وقتی می‌خواهید از نوسازی کد ایستا به درستی‌سنجی، محک‌زنی، و اشکال‌زدایی مرورگر زنده بروید، «راهنمای وب نوین» را با Chrome DevTools برای عامل‌ها جفت کنید.