التابع .submit() في jQuery
.submit( handler )
القيم المعادة
يعيد كائنًا من النوع jQuery.
الوصف
يربط هذا التابع معالج حدث معيَّن مع الحدث submit في JavaScript، أو يستدعي ذلك الحدث لتطبيقه على عنصر.
.submit( handler )
أُضيف مع الإصدار: 1.0.
handler
دالة من الشكل Function( Event eventObject )، وتُمثِّل الدالة التي ستُنفَّذ في كل مرة يُستدعى فيها الحدث.
.submit( [eventData ], handler )
أُضيف مع الإصدار: 1.4.3.
eventData
أي شيء (وهو نوع افتراضي مُستخدَم في jQuery للإشارة إلى إمكانيَّة استخدام أي نوع)، ويُمثِّل كائنًا يحتوي على البيانات التي ستُمرَّر إلى مُعالِج الأحداث.
handler
دالة من الشكل Function( Event eventObject )، وتُمثِّل الدالة التي ستُنفَّذ في كل مرة يُستدعى فيها الحدث.
.submit()
أُضيف مع الإصدار: 1.0، ولا يقبل هذا الشكل من التابع أي معلامات.
هذا التابع هو اختصار للتابع .on( "submit", handler ) في شكله الأول والثاني، واختصار للتابع .trigger( "submit" ) في شكله الثالث.
يُرسل الحدث submit إلى عنصر عندما يحاول المستخدم أن يرسل نموذجًا، ويمكن ربطه بالعناصر <form> فقط. يمكن إرسال الحدث إمَّا بالضغط الصريح على العنصر <input type="submit"> أو العنصر <input type="image"> أو العنصر <button type="submit">، أو بالضغط على المفتاح Enter عند التركيز على عنصر نموذج محدَّد.
ملاحظة: اعتمادًا على المتصفح المستعمل، قد يعمل المفتاح Enter على إرسال النموذج إن كان هذا النموذج يملك حقل نصي وحيد بالتحديد، أو عندما يوجد زر إرسال فقط. لا يجب أن تعتمد الواجهة على سلوك معيَّن من أجل هذا المفتاح إلا في حال الاضطرار لهذا الأمر، إذ يراقب حينها ضغط المفتاح Enter باستعمال الحدث keypress.
بفرض أن لدينا مثلًا شيفرة HTML التالية:
<form id="target" action="destination.html">
<input type="text" value="مرحبًا يا صديق">
<input type="submit" value="أرسل">
</form>
<div id="other">
استدعِ معالج الحدث
</div>
يمكن ربط معالج الحدث بالنموذج بالشكل:
$( "#target" ).submit(function( event ) {
alert( "استُدعي معالج الحدث بنجاح" );
event.preventDefault();
});
عندما يرسل النموذج، ستظهر الرسالة "استُدعي معالج الحدث بنجاح"، وهذا يحدث قبل بدء عمليَّة الإرسال الفعلي، لذا يمكن إلغاء سلوك الإرسال باستدعاء .preventDefault() في معالج الحدث أو بإعادة القيمة false من معالج الحدث. يمكن استدعاء الحدث عند الضغط على أي عنصر آخر:
$( "#other" ).click(function() {
$( "#target" ).submit();
});
بعد تنفيذ هذه الشيفرة، سيؤدي الضغط على "استدعِ معالج الحدث" إلى إظهار الرسالة أيضًا. أضف إلى ذلك أنه سينفَّذ السلوك الافتراضي للحدث submit، لذا سيرسل الحدث آنذاك.
لا ينتشر (bubble) الحدث submit في المتصفح Internet Explorer. على أي حال، ستعمل السكربتات التي تعتمد على تفويض الحدث مع الحدث submit بانتظام عبر جميع المتصفحات بدءًا من الإصدار jQuery 1.4 بعد أن وحَّدت jQuery سلوك الحدث.
ملاحظات إضافية
لما كان التابع .submit() اختزالٌ للتابع .on( "submit", handler )، فمن الممكن استعمال .off( "submit" ) لإزالة الحدث submit أي عملية معاكسة لما سبق.
يجب ألا تُستعمَل الخاصِّيَّة name والخاصِّيَّة id مع العناصر <input> ضمن عناصر النماذج والعناصر الأبناء لها، إذ سيؤدي ذلك إلى حدوث تعارض مع خاصِّيَّات النموذج مثل الخاصِّيَّات submit، أو length، أو method. يمكن أن يسبب تعارض الأسماء فشلًا يدعى بفشل الارتباك (confusing failure). إن أردت الحصول على قائمة القواعد والتحقُّق من العناصر التي تحتوي على هذه المشكلات، فارجع إلى DOMLint.
أمثلة
مثال يوضِّح كيفيَّة منع إرسال النماذج ما لم يُدخِل المستخدم قيمة محدَّدة لضبط قيمة متغير:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>submit مثالٌ عن استعمال</title>
<style>
p {
margin: 0;
color: blue;
}
div,p {
margin-left: 10px;
}
span {
color: red;
}
</style>
<script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
<p>اكتب “أرسل” للتحقق من هويتك وإرسال النموذج</p>
<form action="javascript:alert( تمت العملية بنجاح!' );">
<div>
<input type="text">
<input type="submit">
</div>
</form>
<span></span>
<script>
$( "form" ).submit(function( event ) {
if ( $( "input:first" ).val() === "أرسل" ) {
$( "span" ).text( "بإمكانك الإرسال..." ).show();
return;
}
$( "span" ).text( "لن تتمكن من الإرسال!" ).show().fadeOut( 1000 );
event.preventDefault();
});
</script>
</body>
</html>
يمكن أيضًا تجريب الشيفرة التالية مع المثال السابق لأداء الغرض نفسه:
$( "form" ).submit(function() {
return this.some_flag_variable;
});
إن أردت استدعاء الحدث submit في بداية النموذج في الصفحة، فاستعمل السطر التالي مع المثال السابق:
$( "form:first" ).submit();