HTML Academy · درس

الكائن dataTransfer

نقل البيانات بين مصدر السحب وهدف الإسقاط

الكائن dataTransfer درس مجاني في HTML Academy على CoddyKit. هذا هو الدرس 3 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في HTML Academy، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة HTML Academy 4 دروس في المجموع.

ما الذي يحتفظ به dataTransfer

يُرفق كائن dataTransfer بكل حدث سحب، وهو قناة الاتصال الوحيدة بين المصدر والهدف. ويحمل بيانات الحمولة وقوائم الملفات والتأثيرات المسموح بها وتأثير الإفلات المختار.

setData و getData

يكتب المصدر الحمولات ذات الأنواع باستخدام e.dataTransfer.setData(format, value). ويقرأها الهدف باستخدام e.dataTransfer.getData(format). كلا الوسيطين سلسلتان نصيتان، وتُحوّل القيم إلى سلاسل نصية قبل تخزينها.

src.addEventListener("dragstart", (e) => {
  e.dataTransfer.setData("text/plain", "hello");
  e.dataTransfer.setData("application/json", JSON.stringify({ id: 42 }));
});

أنواع MIME متعددة

يجعل تخزين الحمولة نفسها تحت عدة أنواع عملية السحب قابلة للتشغيل البيني: يعمل "text/plain" في أي محرر نصوص، ويتعرف المتصفح على "text/uri-list" باعتباره عنوان URL، ويحافظ "text/html" على التنسيق في معالجات النصوص. ويختار الهدف النوع الذي يفهمه.

قيود القراءة خارج drop

حفاظًا على الخصوصية، يعرض المتصفح قائمة الأنواع فقط، وليس القيم، لمعالجات dragenter وdragover عبر e.dataTransfer.types. ولا يمكن قراءة البيانات الفعلية إلا داخل حدث drop لهدف يقبل الإفلات.

قائمة files

عندما يسحب المستخدم من سطح المكتب، تكون e.dataTransfer.files عبارة عن FileList من كائنات File. وتكون فارغة عند السحب الذي يبدأ من داخل الصفحة. تعامل معها باعتبارها الطريقة المعتمدة لاكتشاف إفلات ملف خارجي والوصول إلى حجمه واسمه ونوعه.

مجموعة items

تكشف e.dataTransfer.items السلاسل النصية والملفات معًا باعتبارها كائنات DataTransferItem. ويحتوي كل عنصر على kind، وقيمته "string" أو "file"، وعلى type، وهو نوع MIME، وعلى getAsString(cb) وgetAsFile(). وتُعد items البديل الحديث الواعي بالأنواع عن files وgetData.

for (const item of e.dataTransfer.items) {
  if (item.kind === "file") {
    const file = item.getAsFile();
    console.log(file.name);
  } else {
    item.getAsString((s) => console.log(item.type, s));
  }
}

effectAllowed مقابل dropEffect

يضبط المصدر effectAllowed في dragstart، ويسرد العمليات التي يدعمها المصدر. ويضبط الهدف dropEffect في dragover، ويختار إحدى تلك العمليات. ويلغي المتصفح الإفلات إذا اختلفت القيمتان.

صورة سحب مخصصة

تستبدل e.dataTransfer.setDragImage(node, x, y) الصورة الشبحية الافتراضية. مرّر عنصر DOM خارج الشاشة منسقًا كما تريد، بالإضافة إلى إزاحة المؤشر بالنسبة إلى ذلك العنصر. ويسري التغيير على عملية السحب الحالية فقط.

clearData

تمسح e.dataTransfer.clearData() جميع التنسيقات، بينما تزيل clearData("text/plain") تنسيقًا واحدًا. ونادرًا ما تكون هذه العملية مطلوبة لأن dataTransfer يُنشأ من جديد لكل عملية سحب، لكنها مفيدة عندما تبدأ بملء البيانات ثم تقرر الإلغاء.

السلوك عبر الأصول

تُسلّم الملفات المسحوبة من صفحة على الأصل A إلى صفحة على الأصل B رغم ذلك، إذ تعمل الواجهة البرمجية عبر الأصول. ومع ذلك، لا ترى الصفحة المستقبِلة سوى ما وضعه المصدر صراحةً في dataTransfer، ولا يُمنح لها وصول عشوائي إلى DOM.

السحب من المتصفح إلى سطح المكتب

من خلال كتابة النوع "DownloadURL" (setData("DownloadURL", "image/png:filename.png:https://..."))، يمكن للصفحة أن تتيح للمستخدم سحب ملف من المتصفح إلى سطح المكتب. ودعم المتصفحات محدود، إذ يقتصر على المتصفحات المبنية على Chromium، لذا تحقّق من الدعم ووفّر بديلًا مناسبًا.

اختبار المعرفة

لماذا لا يُسمح لـ dataTransfer.getData() بإرجاع القيمة المخزّنة فعليًا أثناء حدث dragover؟

الخلاصة

يمثّل dataTransfer جسرًا بين مصدر السحب وهدف الإسقاط. استخدم setData/getData للحمولات النصية محددة النوع، وitems لعرض موحّد للملفات والسلاسل النصية، وfiles للإسقاطات من سطح المكتب، وsetDragImage لمعاينات مخصصة، وeffectAllowed/dropEffect للتفاوض على العملية.

الأسئلة الشائعة

هل درس «الكائن dataTransfer» مجاني؟

نعم — نص درس «الكائن dataTransfer» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة HTML Academy، انتقل إلى CoddyKit PRO. تتضمن دورة HTML Academy 4 دروس في المجموع.

ماذا ستتعلم في «الكائن dataTransfer»؟

نقل البيانات بين مصدر السحب وهدف الإسقاط تتمرن على HTML Academy مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.

هل أحتاج إلى خبرة سابقة لأبدأ HTML Academy؟

لا تُشترط خبرة سابقة. HTML Academy على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 3 من أصل 4.

كم من الوقت يستغرق درس «الكائن dataTransfer»؟

معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.

هل يمكنني كتابة وتشغيل أكواد في درس HTML Academy هذا؟

نعم. كل درس في HTML Academy يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.

جميع الدروس في هذه الدورة

← العودة إلى HTML Academy