import/export الوحدات والتصدير (مع التوافق مع CommonJS)
آخر تحديث: 2026-10-23
import/export الوحدات والتصدير (مع التوافق مع CommonJS)
وحدات ES Modules هي معيار JavaScript الرسمي للوحدات، ويستخدم TypeScript صياغتي export/import كما هما ويُدخل «الأنواع» في نظام الوحدات أيضًا: يمكن تصدير الأنواع واستيرادها، والصيغة import type تستورد الأنواع فقط وتزول كليًا بعد الترجمة. وملف البرميل (barrel، عادة index.ts) يعيد تصدير عدة وحدات مركزيًا حتى يحتاج المستهلكون إلى مدخل استيراد واحد فقط. أما التوافق مع CommonJS فيتحدد بخيارات الترجمة مثل module وesModuleInterop.
| المجموعة | الإعداد والتطبيق |
|---|---|
| النوع | بناء الجملة |
| الوضع الصارم | غير مطلوب |
ℹ️ معلومة يحوّل المحرر لغة TypeScript إلى JavaScript ثم يشغّلها (بدون فحص أنواع)؛ راجع ناتج كل مثال لنتيجة فحص الأنواع.
📝 الصيغة
// التصدير
export interface User { id: number; name: string } // تصدير نوع
export const add = (a: number, b: number) => a + b; // تصدير قيمة
export default function greet() {} // تصدير افتراضي
// الاستيراد
import greet, { add } from "./math"; // افتراضي + مسمّى
import type { User } from "./types"; // أنواع فقط، تُمحى بعد التجميع
export * from "./math"; // إعادة تصدير عبر البرميل⚙️ المعاملات
| export default | «المخرج الافتراضي» للوحدة، واحد على الأكثر لكل وحدة؛ ويُستورد بأي اسم ودون أقواس معقوفة |
|---|---|
| export * from / re-export | جوهر ملفات البرميل: يمرر كل المخرجات المسماة للوحدة الفرعية، وتُمرر المخرجات النوعية (import type) أيضًا |
| import type / inline type | الصيغتان import type { User } وimport { type User } (المُعدِّل المضمّن) متكافئتان، وكلتاهما تعلن «استيراد الأنواع فقط» فلا يبقى بعد الترجمة أي شيفرة تشغيل |
القيمة المُعادة：لا قيمة معادة للوحدات ذاتها؛ والقيم والأنواع المُصدَّرة تشكل معًا الواجهة العمومية للوحدة ليستوردها بقية الوحدات.
▶ مثال
عدّل الكود أدناه واضغط «جرّب» لرؤية نتيجة التحويل:
الناتج：
Hello, Ada!
add === add2: true
(مخرجات التشغيل بعد الترجمة؛ يعمل هذا المحرر كسكربت مضمّن داخل المتصفح ولا يستطيع الاستيراد من ملفات أخرى فعليًا، لذا يحدّد الكود أعلاه حدود الوحدات في التعليقات ويعرض صيغة مكافئة قابلة للتنفيذ — أما في مشروع حقيقي فتبقى(types.ts / math.ts / utils.ts / main.ts)أربعة ملفات منفصلة، والـ User نوع خالص والصيغة import type لا تترك أثرًا بعد الترجمة)💡 نقاط مهمة
ℹ️ معلومة استيراد الأنواع عبر import type يعطي الأثر نفسه كما في import عادي، لكنه أوضح دلاليًا وآمن للاستخدام مع isolatedModules؛ ويزول جزء الأنواع من كليهما بعد الترجمة.
💡 تلميح ضع ملف البرميل في جذر دليل src (index.ts) ومحتواه أسطر export * from / export { x } from فقط؛ والفائدة أن يستورد المستدعون من @/utils بدلًا من مسارات عميقة مثل @/utils/math، وإعادة هيكلة الأدلة تلمس البرميل وحده.
⚠️ تنبيه التوافق مع CommonJS منطقة أخطاء بارزة: فالعلاقة بين import default وmodule.exports في الـ CJS المترجم سهلة الخلط؛ ولا يتوافق السلوك مع مواصفة ES إلا بتفعيل esModuleInterop (مع module: commonjs)؛ وعند ضبط module إلى node16/nodenext يُشترط أيضًا كتابة الامتدادات كاملة في الاستيرادات النسبية.
🏷️ الإعداد والتطبيق ذو صلة
💡 حالات ذات صلة
المزيد من الحالات قادم قريبًا.
📚 دروس ذات صلة
❓ أسئلة شائعة
س ما الفرق بين import type و import العادي؟
ج قد تُترجم محتويات import العادي إلى استدعاء require (وإن كنت استخدمت أنواعه فقط)؛ أما import type فيضمن استيراد الأنواع فقط دون أي شيفرة تشغيل. وفي سيناريو isolatedModules أو tree-shaking لدى المُجمِّع يجنّبك الاحتفاظ بحزمة كاملة من أجل أنواعها فقط.
س متى يستحق بناء ملف برميل؟
ج عندما يكشف دليلٌ ما للمستهلكين أكثر من ثلاث أو أربع وحدات، ويستورد المستدعون عادة أكثر من واحدة معًا. لكن انتبه: يجذب البرميل كل الوحدات الفرعية إلى الرسم البياني للتبعيات نفسه وقد يضر بـ tree-shaking؛ فهو مناسب للمكتبات الأدواتية الخالصة، ويلزم التقدير في مجموعات مكونات كبيرة حساسة للحجم.
س أظهر التشغيل "Cannot use import statement outside a module" — ما السبب؟
ج لا يفهم بيئة التشغيل صياغة ESM: إما أن import في الناتج لم يُحوَّل (target حديث جدًا أو إعداد module خاطئ)، أو أن Node يتعامل مع .js بوصفها CJS. الحل: اضبط module إلى commonjs (أو دع المُجمِّع يعالج ESM)، واستخدم .mjs لملفات ESM أو أعلن "type": "module" في package.json.
