{"id":"l-js-5-1","courseId":"javascript-fundamentals","lang":"ar","kind":"lesson","summary":"تقسّم برنامجًا متناميًا إلى وحدات (modules) باستخدام export وimport، وتحمّلها في المتصفّح بـ type=“module” من خادم تطوير، وتنظّم Pocket في ملفات لكل منها مهمة واضحة.","html":"

صار لدى Pocket دوال مساعدة للمال، وتحقّق من المدخلات، وتخزين، وعرض، ومعالجات أحداث، وكود شبكة. وفي ملف واحد يعني هذا مئات الأسطر، تستطيع فيها كل دالة رؤية كل متغيّر، وتغيير جزء واحد يعني التمرير متجاوزًا كل الأجزاء الأخرى. البرامج الحقيقية تُقسَّم إلى ملفات، لكل منها مهمة واحدة، وطريقة JavaScript في ذلك هي الوحدات (modules).

\n

الوحدة ملف له نطاقه الخاص

\n

في الوحدة، تكون المتغيّرات والدوال في المستوى الأعلى خاصة بذلك الملف. ولتشارك شيئًا، تُصدّره بـ export. ولتستخدم شيئًا من وحدة أخرى، تستورده بـ import:

\n
src/money.js
export function toCents(dollars) {\n  return Math.round(dollars * 100);\n}\n\nexport function formatMoney(cents, symbol = \"$\") {\n  return `${symbol}${(cents / 100).toFixed(2)}`;\n}\n\nconst SECRET_ROUNDING_NOTE = \"not exported, so only this file can see it\";
\n
src/main.js
import { toCents, formatMoney } from \"./money.js\";\n\nconsole.log(formatMoney(toCents(12.2)));
\n

الأقواس المعقوفة تسرد التصديرات المسمّاة (named exports) التي تريدها. والمسار يبدأ بـ ./، ومعناه “نسبةً إلى هذا الملف”، وفي المتصفّح يتضمّن الامتداد .js. أما SECRET_ROUNDING_NOTE فلا يمكن استيرادها أصلًا؛ وهذا هو المقصود. كل وحدة تقرّر ما تقدّمه، وكل ما عدا ذلك مخفي، مثل الـ closures في القسم 2 تمامًا، لكن على مستوى الملف.

\n

صيغ أخرى ستراها:

\n
src/main.js
import { formatMoney as fmt } from \"./money.js\";   // rename on import\nimport * as money from \"./money.js\";                // everything, as money.toCents etc.
\n

وهناك أيضًا التصدير الافتراضي (default export)، واحد لكل ملف، يُستورد دون أقواس معقوفة وبأي اسم تحبّه: export default function renderApp() {} ثم import renderApp from "./ui.js". كثير من الفرق تفضّل التصديرات المسمّاة، وكذلك هذه الدورة: فالتصدير المسمّى يحمل الاسم نفسه في كل ملف يستخدمه، لذلك يعمل البحث وإعادة التسمية التلقائية في محرّرك بشكل موثوق.

\n

تحميل الوحدات في المتصفّح

\n

يُحمَّل ملف الدخول بـ type="module"، وهو يستورد كل ما عداه:

\n
index.html
<script type=\"module\" src=\"./src/main.js\"></script>
\n

تتصرّف سكربتات الوحدات بشكل مختلف قليلًا عن السكربتات الكلاسيكية التي استخدمتها حتى الآن. فهي مؤجَّلة تلقائيًا، فيكون الـ DOM جاهزًا حين تُنفَّذ. وتعمل في الوضع الصارم (strict mode)، الذي يحوّل بعض الأخطاء الصامتة إلى أخطاء ظاهرة. وكل وحدة تُنفَّذ مرة واحدة، مهما كان عدد الملفات التي تستوردها، لذلك يكون المتغيّر على مستوى الوحدة مشتركًا بين كل من يستوردها.

\n\n

عمليًا، تستخدم معظم المشاريع أداة بناء مثل Vite. إنها تقدّم وحداتك أثناء التطوير، وتتيح لك استيراد الحزم من npm بأسمائها (import { something } from "some-package")، وعند البناء تحزم كل شيء في ملفات قليلة محسّنة. وصياغة import وexport التي تكتبها هي نفسها تمامًا.

\n

الوحدات في Node.js

\n

يدعم Node.js الصياغة نفسها. يُعامَل الملف على أنه وحدة ES حين يحتوي أقرب package.json على "type": "module"، أو حين ينتهي اسم الملف بـ .mjs. (والإصدارات الحديثة من Node.js تكتشف أيضًا صياغة import في ملف .js عادي، لكن ضبط "type" صراحةً أوضح.) وستصادف أيضًا نظام Node.js الأقدم، CommonJS، الذي يستخدم require() وmodule.exports؛ وما زال شائعًا في المشاريع القائمة، لكن الكود الجديد يستخدم import وexport.

\n

تنظيم Pocket

\n

التقسيم الجيد يتبع المهام، ويُبقي الأجزاء التي تتعامل مع العالم الخارجي منفصلة عن المنطق النقي:

\n
\n يستورد main.js من ui.js وstorage.js وexpenses.js. ويستورد ui.js من money.js. أما expenses.js وmoney.js فمنطق نقي لا يمسّ الصفحة ولا التخزين أبدًا.\n \n main.js\n \n ui.js\n \n storage.js\n \n expenses.js\n \n money.js\n \n \n \n \n الأخضر: منطق نقي، بلا DOM ولا تخزين\n
وحدات Pocket ومن يستورد ماذا
\n\n

والقاعدة وراء هذا التقسيم: الاعتماديات تتّجه من الخارج إلى الداخل. main.js يعرف كل شيء؛ وexpenses.js لا يعرف شيئًا سوى البيانات. وهذا يعني أنك تستطيع اختبار المنطق الأساسي، أو إعادة استخدامه في Node.js، دون متصفّح، وتستطيع لاحقًا استبدال localStorage بخادم بتغيير ملف واحد.

\n\n

بيئة التجربة في هذه الدورة تشغّل ملفًا واحدًا في كل مرة، لذلك يدور التمرين أدناه حول قراءة كود الوحدات. وفي الدرس التالي ستتعرّف إلى طريقة أخرى لتنظيم الكود، هي الأصناف (classes)، التي تجمع البيانات مع الدوال التي تعمل عليها.

\n","toc":[{"id":"sec-1","text":"الوحدة ملف له نطاقه الخاص","level":2},{"id":"sec-2","text":"تحميل الوحدات في المتصفّح","level":2},{"id":"sec-3","text":"الوحدات في Node.js","level":2},{"id":"sec-4","text":"تنظيم Pocket","level":2}],"takeaways":["الوحدة (module) ملف له نطاقه الخاص؛ ولا شيء فيه مرئي للملفات الأخرى ما لم يُصدَّر.","فضّل التصدير المسمّى (export function formatMoney)، فهو يحتفظ بالاسم نفسه في كل مكان ويسهل البحث عنه.","في المتصفّح، حمّل ملف الدخول بـ <script type="module">، واستخدم مسارات نسبية مع الامتداد .js، وقدّم الملفات عبر http.","في Node.js، تكون الملفات وحدات ES حين يحتوي أقرب package.json على "type": "module" أو حين ينتهي اسم الملف بـ .mjs.","نظّم حسب المهمة: المنطق النقي في وحدات لا تمسّ الصفحة أبدًا، وملف دخول رفيع يربط المنطق والتخزين والـ DOM معًا."],"further":[{"title":"JavaScript modules (MDN)","url":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules"},{"title":"export (MDN)","url":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/export"},{"title":"Modules: ECMAScript modules (Node.js)","url":"https://nodejs.org/api/esm.html"}],"quiz":[{"q":"

يقول console المتصفّح: Uncaught SyntaxError: Cannot use import statement outside a module. ما الحل؟

","options":[{"text":"غيّر اسم الملف من .js إلى .mjs.","why":"المتصفّح لا يقرّر بحسب امتداد الملف. بل بحسب الطريقة التي يحمّل بها وسم السكربت الملف."},{"text":"انقل أسطر import إلى أسفل الملف.","why":"الاستيراد مسموح فقط داخل الوحدات، أينما ظهر. ونقله لا يجعل الملف وحدة."},{"text":"غلّف تعليمات الاستيراد بدالة.","why":"تعليمات import الثابتة يجب أن تكون في المستوى الأعلى من الوحدة؛ وداخل دالة تكون خطأً في الصياغة."},{"text":"حمّل ملف الدخول بـ <script type="module" src="./main.js">.","why":"صحيح. دون type="module"، يشغّل المتصفّح الملف على أنه سكربت كلاسيكي، حيث import غير مسموحة."}],"answer":3},{"q":"

يصرّح money.js بـ function toCents(d) { … } دون export. ماذا يحدث حين ينفّذ main.js السطر import { toCents } from "./money.js";؟

","options":[{"text":"يعمل، لأن كل الدوال في المستوى الأعلى مشتركة بين الوحدات.","why":"لكل وحدة نطاقها الخاص. ولا يمكن استيراد إلا الأسماء المُصدَّرة."},{"text":"يفشل التحميل بخطأ SyntaxError يقول إن money.js لا يوفّر تصديرًا اسمه toCents.","why":"صحيح. تُفحص تعليمات الاستيراد قبل تنفيذ أي كود، لذلك يُبلَّغ عن الخطأ فورًا."},{"text":"يُستورد toCents على أنه undefined ويظهر الخطأ حين تستدعيه.","why":"الاستيرادات المسمّاة تُربط قبل تنفيذ الكود؛ والتصدير المفقود يمنع شبكة الوحدات من التحميل أصلًا."}],"answer":1},{"q":"

تفتح index.html بالنقر المزدوج عليه، فيفشل سكربت الوحدة في التحميل بخطأ CORS. لماذا؟

","options":[{"text":"سكربتات الوحدات ممنوعة في صفحات file://، لذلك يجب تقديم الملفات عبر http، مثلًا عبر خادم تطوير.","why":"صحيح. تطبّق المتصفّحات قواعد تحميل أكثر صرامة على الوحدات. وأي خادم محلي، مثل الذي يشغّله Vite، يحلّ المشكلة."},{"text":"لا تعمل الوحدات إلا بعد نشر الموقع على الإنترنت.","why":"خادم محلي على حاسوبك يكفي. لا حاجة إلى النشر."},{"text":"المتصفّح أقدم من أن يدعم الوحدات.","why":"كل المتصفّحات الحالية تدعم الوحدات منذ سنوات. المشكلة في المصدر file://، لا في المتصفّح."}],"answer":0}],"exercise":{"kind":"spot-bug","language":"js","code":"// src/money.js\nexport function formatMoney(cents) {\n return `$${(cents / 100).toFixed(2)}`;\n}\nfunction toCents(dollars) {\n return Math.round(dollars * 100);\n}\n\n// src/main.js (loaded with