خرائط الاستيراد importmap
تعيين محددات الوحدات غير المؤهلة إلى عناوين URL باستخدام importmap
خرائط الاستيراد importmap درس مجاني في HTML Academy على CoddyKit. هذا هو الدرس 2 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في HTML Academy، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة HTML Academy 4 دروس في المجموع.
مشكلة المحدد العاري
في Node، يعمل import "lodash" لأن محلل الوحدات يعثر على node_modules/lodash. لا تحتوي المتصفحات على node_modules، بل تحتاج إلى عنوان URL حقيقي. ومن دون مساعدة، يطلق import "lodash" الخطأ "Failed to resolve module specifier".
وظيفة خرائط الاستيراد
تعرّف خريطة الاستيراد قاموسًا بتنسيق JSON يربط المحددات العارية (وبادئات عناوين URL) بعناوين URL حقيقية. ويراجع المتصفح الخريطة أثناء حل الوحدات، فيحوّل import "lodash" إلى جلب من عنوان URL الذي ضبطتموه.
<script type="importmap">
{
"imports": {
"lodash": "https://esm.sh/lodash@4.17.21",
"preact": "https://esm.sh/preact"
}
}
</script>ترتيب التصريحات مهم
يجب أن تظهر خريطة الاستيراد قبل أي <script type="module"> يستخدم محددات عارية؛ فبمجرد أن تبدأ وحدة في حل عمليات الاستيراد، تُثبَّت الخريطة. ضعوا <script type="importmap"> بالقرب من أعلى <head>.
تعيينات البادئات
تطابق الإدخالات التي تنتهي بشرطة مائلة بادئات عناوين URL: إذ يربط "@/": "/src/" أي import "@/utils/sum.js" بالمسار /src/utils/sum.js. وهكذا يمكنكم محاكاة صيغة "alias" التي تدعمها أدوات التجميع عادةً.
إدارة الإصدارات عبر الخريطة
تركّز خريطة الاستيراد اختيارات الإصدارات في مكان واحد: غيّروا "react" من esm.sh/react@18 إلى esm.sh/react@19 في مكان واحد، وستستخدم كل وحدة مستورِدة عنوان URL الجديد. ومن دون خريطة استيراد، يحتوي كل موضع استيراد على إصداره المضمّن بصورة مستقلة.
النطاقات
يتيح المفتاح scopes تعيينات مختلفة لأجزاء مختلفة من موقعكم. فقد تحتاجون داخل /admin/ إلى إصدار أحدث من تبعية مقارنةً بما تحتاجونه داخل /public/؛ وتتيح لكم النطاقات الاستهداف حسب المسار.
{
"imports": { "lodash": "https://esm.sh/lodash@4" },
"scopes": {
"/admin/": { "lodash": "https://esm.sh/lodash@5" }
}
}خريطة واحدة لكل مستند
يمكن أن يحتوي كل مستند على <script type="importmap"> واحد فقط كحد أقصى. ويُعد وضع خريطتين في الصفحة نفسها غير صالح؛ ادمجوا محتواهما في كتلة واحدة للجمع بين الإدخالات.
خرائط الاستيراد الخارجية
يمكنكم استضافة الخريطة على عنوان URL خارجي باستخدام <script type="importmap" src="map.json">. دعم المتصفحات لها أحدث من دعم الخرائط المضمّنة، لكنه أصبح واسع الانتشار الآن؛ وهي مفيدة عندما تريدون تخزين خريطة كبيرة مؤقتًا بصورة منفصلة عن المستند.
إنشاء خرائط الاستيراد
تُنشئ أدوات مثل JSPM Generator ووضع --servedir في esbuild خرائط استيراد تلقائيًا من package.json. وتتضمن الخرائط المُنشأة كل تبعية غير مباشرة، مع ربط كل منها بعنوان URL على CDN، مما يتيح سير عمل من دون node_modules.
دعم المتصفحات
تتوفر خرائط الاستيراد في Chrome وEdge وSafari وFirefox. وتتجاهل المتصفحات القديمة وسم <script type="importmap">، مما يعني فشل المحددات العارية. ولتوفير دعم واسع للمتصفحات القديمة، ابنوا التطبيق باستخدام أداة تجميع تحل المحددات وقت البناء، وقدّموا عناوين URL عادية.
خيار polyfill
يضيف polyfill ES Module Shims (es-module-shims.js) دعم خرائط الاستيراد، إلى جانب عدة ميزات أحدث، إلى المتصفحات القديمة. أدرجوه قبل نص importmap. وتتجاوز معظم المشاريع الحديثة استخدام polyfill وتعتمد على الدعم الأصلي.
اختبار المعرفة
لماذا يجب أن يظهر <script type="importmap"> قبل أي نص وحدة يستخدم محددات عارية؟
الخلاصة
تربط خرائط الاستيراد المحددات العارية وبادئات عناوين URL بعناوين URL حقيقية، مما يعيد أسلوب "import lodash" الشبيه بـ Node إلى المتصفح. عرّفوها مرة واحدة لكل مستند قبل أي نص وحدة، ويمكنكم اختياريًا تعريفها خارجيًا عبر src، مع استخدام النطاقات لتجاوز التعيينات حسب المسار. ادمجوها مع CDN مثل esm.sh وjsdelivr للحصول على سير عمل من دون node_modules.
الأسئلة الشائعة
هل درس «خرائط الاستيراد importmap» مجاني؟
نعم — نص درس «خرائط الاستيراد importmap» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة HTML Academy، انتقل إلى CoddyKit PRO. تتضمن دورة HTML Academy 4 دروس في المجموع.
ماذا ستتعلم في «خرائط الاستيراد importmap»؟
تعيين محددات الوحدات غير المؤهلة إلى عناوين URL باستخدام importmap تتمرن على HTML Academy مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.
هل أحتاج إلى خبرة سابقة لأبدأ HTML Academy؟
لا تُشترط خبرة سابقة. HTML Academy على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 2 من أصل 4.
كم من الوقت يستغرق درس «خرائط الاستيراد importmap»؟
معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.
هل يمكنني كتابة وتشغيل أكواد في درس HTML Academy هذا؟
نعم. كل درس في HTML Academy يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.
جميع الدروس في هذه الدورة
- نصوص وحدات ES من النوع type=module
- خرائط الاستيراد importmap
- الاستيراد الديناميكي import() في الوحدات
- أساسيات Module Federation