دموهای آماده 10

مرکز اعلان‌ها

همه اعلان‌ها خوانده شد
مشاهده تمام اعلان‌ها

رفع اشکال

این بخش بر پایه مشکلاتی نوشته شده که واقعاً در پروژه‌های HTML/Vite رخ می‌دهد. هر مورد شامل نشانه، علت و راه‌حل است.

صفحه بدون استایل باز می‌شود

نشانه: متن‌ها بدون رنگ و فاصله نمایش داده می‌شوند؛ در کنسول شبکه، فایل SCSS با Content-Type: application/javascript بارگذاری شده است.

علت: Vite فایل‌های .scss را در حالت توسعه به‌عنوان ماژول JS سرو می‌کند و مرورگر آن را به‌عنوان استایل اجرا نمی‌کند.

راه‌حل: لینک استایل باید با پارامتر ?direct باشد (در src/partials/head.html):

<link rel="stylesheet" href="/src/scss/main.scss?direct">

در خروجی نهایی (npm run build) این لینک با یک فایل CSS هش‌دار جایگزین می‌شود.

لینک‌ها از صفحه‌های تودرتو خطای ۴۰۴ می‌دهند

علت: هر صفحه یک پوشه عمیق‌تر است، پس users/list.html از داخل crm/contacts.html باید ../users/list.html باشد.

راه‌حل: لینک‌های تولیدشده در زمان اجرا با src/js/core/links.js خودکار اصلاح می‌شوند (fixLinks + observeLinks). اگر خودتان لینک ثابت می‌نویسید:

<a href="../users/list.html">کاربران</a>

یا در جاوااسکریپت از NOVA.url('users/list.html') استفاده کنید.

صفحه‌ها بعد از ساخت در dist/src/pages ظاهر می‌شوند

علت: کلیدهای ورودی Vite باید پسوند .html داشته باشند.

راه‌حل: مطمئن شوید tools/build-pages.mjs و tools/flatten-dist.mjs در زنجیره npm run build هستند و مرحله flatten-dist آخرین گام است.

کلاس‌هایی که در JS نوشته‌ام استایل ندارند

راه‌حل: npm run qa:links را اجرا کنید؛ این ابزار همه کلاس‌های استفاده‌شده در HTML و در تمپلیت‌های JS را با استایل‌های موجود مقایسه می‌کند و لیست کمبودها را می‌دهد.

توکن‌های {{...}} در HTML خروجی مانده‌اند

علت: توکن جدیدی اضافه کرده‌اید که در نقشه توکن‌های tools/nova-plugin.mjs نیست.

راه‌حل: آن را به TOKENS اضافه کنید و دوباره npm run build بگیرید. برای بررسی:

grep -ro "{{[A-Z_]*}}" dist --include=*.html | sort -u

داده جدول نمی‌آید و «موردی یافت نشد» نمایش داده می‌شود

علت‌های ممکن:

  1. نام منبع در data-resource با کلید رجیستری src/services/index.js یکی نیست.
  2. فیلتر پیش‌فرض سخت‌گیرانه است؛ دکمه «پاک‌کردن فیلترها» را بزنید.
  3. نام فیلد در searchFields سرویس وجود ندارد؛ ابزار جستجو کار می‌کند اما نتیجه نمی‌دهد.

تغییرات من در ساخت بعدی از بین می‌رود

علت: فایل‌های src/pages/** در هر ساخت بازنویسی می‌شوند.

راه‌حل: تغییر را در src/partials/pages/&lt;مسیر&gt;.html یا در کنترل‌کننده مربوطه در src/js/pages/** انجام دهید.

فونت فارسی لود نمی‌شود

علت: فونت از node_modules/vazirmatn خوانده می‌شود. اگر node_modules ناقص باشد، فایل woff2 پیدا نمی‌شود.

راه‌حل: npm install را کامل اجرا کنید. در خروجی نهایی، فونت در dist/assets/fonts/ است؛ وجود آن را بررسی کنید:

ls dist/assets/fonts/

نمودار خالی می‌ماند

علت‌های ممکن: ظرف نمودار وجود ندارد، data-chart-key تکراری است، یا initCharts قبل از رندر شدن DOM صدا زده شده است.

راه‌حل: پس از رندر، initCharts(scope) را صدا بزنید. ابزار npm run qa:smoke همین رفتار را در یک DOM شبیه‌سازی‌شده آزمایش می‌کند و صفحه معیوب را نشان می‌دهد.

در RTL چیزی از لبه صفحه بیرون می‌زند

علت: استفاده از left/right به‌جای ویژگی‌های منطقی.

راه‌حل: left → inset-inline-start، right → inset-inline-end، margin-left → margin-inline-start، border-left → border-inline-start. سپس صفحه را در هر دو جهت بیازمایید.

صفحه در موبایل نوار افقی اضافه دارد

علت‌های رایج: جدول بدون .table-responsive، عرض ثابت پیکسلی، یا white-space: nowrap روی متن بلند.

راه‌حل: جدول‌ها را در .table-responsive بگذارید، عرض‌ها را با min(100%, …) بنویسید و متن‌های بلند را با text-wrap: pretty یا شکست کلمه مدیریت کنید. عرض‌های ۳۲۰/۳۷۵/۴۱۴ را بیازمایید.

ساختار پرتکرار: چگونه خطا را پیدا کنم؟

npm run qa:links     # خطاهای خروجی (لینک، دارایی، کلاس، دسترس‌پذیری)
npm run qa:smoke     # خطاهای زمان اجرای کنترل‌کننده‌ها

هر دو ابزار با کد خروج غیرصفر شکست را گزارش می‌کنند و همین‌ها را می‌توانید در CI هم اجرا کنید.

نکته: اگر خطای کنسول می‌بینید، پیام‌ها با پیشوند [NOVAADMIN] چاپ می‌شوند؛ متن خطا و نام فایل را در گزارش بگذارید

Troubleshooting

This section is based on problems that genuinely occur in HTML/Vite projects. Each entry contains the symptom, the cause and the fix.

The page opens without styles

Symptom: text is shown without colour or spacing; in the network panel, the SCSS file was loaded with Content-Type: application/javascript.

Cause: in development Vite serves .scss files as JS modules and the browser does not apply them as a stylesheet.

Fix: the stylesheet link must carry the ?direct parameter (in src/partials/head.html):

<link rel="stylesheet" href="/src/scss/main.scss?direct">

In the final output (npm run build) this link is replaced with a hashed CSS file.

Links from nested pages return 404

Cause: every page sits one folder deeper, so users/list.html from inside crm/contacts.html must be ../users/list.html.

Fix: links generated at runtime are fixed automatically by src/js/core/links.js (fixLinks + observeLinks). If you write a fixed link yourself:

<a href="../users/list.html">Users</a>

Or use NOVA.url('users/list.html') in JavaScript.

Pages end up in dist/src/pages after building

Cause: Vite input keys must have the .html extension.

Fix: make sure tools/build-pages.mjs and tools/flatten-dist.mjs are in the npm run build chain and that the flatten-dist step is the last one.

Classes I wrote in JS have no styles

Fix: run npm run qa:links; this tool compares every class used in HTML and in JS templates with the existing styles and lists what is missing.

{{...}} tokens are left in the output HTML

Cause: you added a new token that is not in the token map in tools/nova-plugin.mjs.

Fix: add it to TOKENS and run npm run build again. To check:

grep -ro "{{[A-Z_]*}}" dist --include=*.html | sort -u

Table data does not load and "No items found" is shown

Possible causes:

  1. The resource name in data-resource does not match the registry key in src/services/index.js.
  2. The default filter is too strict; press the "Clear filters" button.
  3. The field name does not exist in the service's searchFields; the search box works but returns nothing.

My changes are lost on the next build

Cause: the src/pages/** files are rewritten on every build.

Fix: make the change in src/partials/pages/&lt;path&gt;.html or in the relevant controller in src/js/pages/**.

The Persian font does not load

Cause: the font is read from node_modules/vazirmatn. If node_modules is incomplete, the woff2 file cannot be found.

Fix: run npm install to completion. In the final output the font is in dist/assets/fonts/; check that it is there:

ls dist/assets/fonts/

A chart stays empty

Possible causes: the chart container does not exist, data-chart-key is duplicated, or initCharts was called before the DOM was rendered.

Fix: call initCharts(scope) after rendering. npm run qa:smoke tests this very behaviour in a simulated DOM and points out the faulty page.

Something sticks out past the page edge in RTL

Cause: using left/right instead of logical properties.

Fix: left → inset-inline-start, right → inset-inline-end, margin-left → margin-inline-start, border-left → border-inline-start. Then test the page in both directions.

The page has an extra horizontal scrollbar on mobile

Common causes: a table without .table-responsive, a fixed pixel width, or white-space: nowrap on long text.

Fix: wrap tables in .table-responsive, write widths as min(100%, …) and handle long text with text-wrap: pretty or word breaking. Test widths 320/375/414.

Routine: how do I find the error?

npm run qa:links     # output errors (links, assets, classes, accessibility)
npm run qa:smoke     # controller runtime errors

Both tools report failure with a non-zero exit code, and you can run the same commands in CI.

Tip: if you see a console error, messages are printed with the [NOVAADMIN] prefix; include the error text and file name in your report

استكشاف الأخطاء

كُتب هذا القسم بناءً على مشكلات تحدث فعلاً في مشاريع HTML/Vite. ويتضمن كل بند العَرَض والسبب والحل.

تُفتح الصفحة بلا أنماط

العَرَض: تظهر النصوص بلا ألوان أو مسافات؛ وفي لوحة الشبكة حُمّل ملف SCSS بـ Content-Type: application/javascript.

السبب: يقدّم Vite ملفات .scss في وضع التطوير كوحدات JS ولا يطبّقها المتصفح كأنماط.

الحل: يجب أن يحمل رابط الأنماط المعامل ?direct (في src/partials/head.html):

<link rel="stylesheet" href="/src/scss/main.scss?direct">

وفي المخرجات النهائية (npm run build) يُستبدل هذا الرابط بملف CSS مجزّأ الاسم.

تعطي الروابط من الصفحات المتداخلة خطأ ٤٠٤

السبب: كل صفحة تقع في مجلد أعمق بمستوى؛ لذا يجب أن يكون users/list.html من داخل crm/contacts.html هو ../users/list.html.

الحل: تُصحَّح الروابط المولّدة وقت التشغيل تلقائياً بـ src/js/core/links.js (fixLinks + observeLinks). وإذا كتبت رابطاً ثابتاً بنفسك:

<a href="../users/list.html">المستخدمون</a>

أو استخدم NOVA.url('users/list.html') في جافاسكريبت.

تظهر الصفحات بعد البناء في dist/src/pages

السبب: يجب أن تحمل مفاتيح إدخال Vite الامتداد .html.

الحل: تأكد من وجود tools/build-pages.mjs وtools/flatten-dist.mjs في سلسلة npm run build وأن مرحلة flatten-dist هي الأخيرة.

الفئات التي كتبتها في JS بلا أنماط

الحل: نفّذ npm run qa:links؛ تقارن هذه الأداة جميع الفئات المستخدمة في HTML وفي قوالب JS بالأنماط الموجودة وتعطي قائمة النواقص.

بقيت رموز {{...}} في HTML المخرجات

السبب: أضفت رمزاً جديداً غير موجود في خريطة الرموز في tools/nova-plugin.mjs.

الحل: أضفه إلى TOKENS ونفّذ npm run build مجدداً. وللتحقق:

grep -ro "{{[A-Z_]*}}" dist --include=*.html | sort -u

لا تظهر بيانات الجدول وتُعرض «لم يُعثر على عناصر»

الأسباب المحتملة:

  1. اسم المورد في data-resource لا يطابق مفتاح السجل في src/services/index.js.
  2. الفلتر الافتراضي صارم؛ اضغط زر «مسح الفلاتر».
  3. اسم الحقل غير موجود في searchFields للخدمة؛ فأداة البحث تعمل لكنها لا تعيد نتائج.

تضيع تغييراتي في البناء التالي

السبب: تُعاد كتابة ملفات src/pages/** في كل بناء.

الحل: أجرِ التغيير في src/partials/pages/&lt;المسار&gt;.html أو في المتحكم المعني في src/js/pages/**.

لا يُحمَّل الخط الفارسي

السبب: يُقرأ الخط من node_modules/vazirmatn. وإذا كان node_modules ناقصاً، فلن يُعثر على ملف woff2.

الحل: نفّذ npm install بالكامل. في المخرجات النهائية يوجد الخط في dist/assets/fonts/؛ تحقّق من وجوده:

ls dist/assets/fonts/

يبقى المخطط فارغاً

الأسباب المحتملة: حاوية المخطط غير موجودة، أو data-chart-key مكرر، أو استُدعي initCharts قبل عرض DOM.

الحل: استدعِ initCharts(scope) بعد العرض. تختبر الأداة npm run qa:smoke هذا السلوك نفسه في DOM محاكى وتُظهر الصفحة المعيبة.

في RTL يخرج شيء عن حافة الصفحة

السبب: استخدام left/right بدلاً من الخصائص المنطقية.

الحل: left ← inset-inline-start، وright ← inset-inline-end، وmargin-left ← margin-inline-start، وborder-left ← border-inline-start. ثم اختبر الصفحة في الاتجاهين.

للصفحة شريط أفقي إضافي على الجوال

الأسباب الشائعة: جدول بلا .table-responsive، أو عرض ثابت بالبكسل، أو white-space: nowrap على نص طويل.

الحل: ضع الجداول داخل .table-responsive، واكتب العروض بـ min(100%, …)، وتعامل مع النصوص الطويلة بـ text-wrap: pretty أو بكسر الكلمات. اختبر العروض ٣٢٠/٣٧٥/٤١٤.

الروتين المتكرر: كيف أجد الخطأ؟

npm run qa:links     # أخطاء المخرجات (الروابط، الأصول، الفئات، إمكانية الوصول)
npm run qa:smoke     # أخطاء وقت تشغيل المتحكمات

تُبلغ الأداتان عن الفشل برمز خروج غير صفري، ويمكنك تشغيلهما في CI أيضاً.

ملاحظة: إذا رأيت خطأ في وحدة التحكم، فالرسائل تُطبع بالبادئة [NOVAADMIN]؛ ضع نص الخطأ واسم الملف في تقريرك