التابع .val() في jQuery
إعادة القيمة الحالية للعنصر الأول في مجموعة العناصر المُطابقة أو تعيين قيمة (value) كل عنصر مُطابق.
.val()
القيمة المعادة
يُعيد كائنًا من النوع String أو Number أو Array.
الوصف
إعادة القيمة الحالية للعنصر الأول في مجموعة العناصر المُطابقة.
.val()
أُضيف مع الإصدار: 1.0.
لا يقبل هذا الشكل أي وسائط.
يستخدم التابع .val() في المقام الأول للحصول على قيم عناصر النماذج مثل <input> و <select> و <textarea>. عند استدعائها على مجموعة فارغة، فإنها تُعيد undefined.
عندما يكون العنصر الأول في المجموعة هو select-multiple (أي عنصر <select> مع ضبط الخاصية multiple عليه)، سيُعيد .val() مصفوفة تحتوي على قيمة كل خيار محدد. بدءًا من jQuery 3.0، إذا لم يُحدد أي خيارات، فسوف يعيد هذا التابع مصفوفة فارغة؛ وكان يُعيد null قبل jQuery 3.0.
بالنسبة للتحديدات، وخانات التأشير وأزرار الإنتقاء، يمكنك استخدام المُحدد :checked لتحديد العناصر الصحيحة. فمثلًا:
// إعادة القيمة من الخيار المحدد في قائمة منسدلة
$( "select#foo option:checked" ).val();
// إعادة القيمة من تحديد قائمة منسدلة مباشرةً
$( "select#foo" ).val();
// إعادة القيمة من خانات التأشير
$( "input[type=checkbox][name=bar]:checked" ).val();
// إعادة القيمة من مجموعة أزرار انتقاء
$( "input[type=radio][name=baz]:checked" ).val();
ملاحظة: في الوقت الحالي، يُجرِّد استخدام .val() على عناصر <textarea> محرف العودة إلى بداية السطر (\r) من القيمة التي أعادها المتصفح. عند إرسال هذه القيمة إلى الخادم عبر XHR، ومع ذلك، يُحتفظ بمحرف العودة إلى بداية السطر (أو تضيفه المتصفحات التي لا تتضمنها في القيمة الأولية). يمكن استخدام حل بديل لهذه المشكلة باستخدام valHook على النحو التالي:
$.valHooks.textarea = {
get: function( elem ) {
return elem.value.replace( /\r?\n/g, "\r\n" );
}
};
أمثلة
إعادة القيمة المفردة من عنصر <select> مفرد، وإعادة مصفوفة من القيم من عنصر <select> متعدد الاختيارات وعرض قيمها:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>val مثال على التابع</title>
<style>
p {
color: red;
margin: 4px;
}
b {
color: blue;
}
</style>
<script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
<p></p>
<select id="single">
<option>مفرد</option>
<option>مفرد2</option>
</select>
<select id="multiple" multiple="multiple">
<option selected="selected">متعدد</option>
<option>متعدد2</option>
<option selected="selected">متعدد3</option>
</select>
<script>
function displayVals() {
var singleValues = $( "#single" ).val();
var multipleValues = $( "#multiple" ).val() || [];
// When using jQuery 3:
// var multipleValues = $( "#multiple" ).val();
$( "p" ).html( "<b>Single:</b> " + singleValues +
" <b>Multiple:</b> " + multipleValues.join( ", " ) );
}
$( "select" ).change( displayVals );
displayVals();
</script>
</body>
</html>
البحث عن قيمة مربع الإدخال <input>:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>val مثال على التابع</title>
<style>
p {
color: blue;
margin: 8px;
}
</style>
<script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
<input type="text" value="بعض النصوص">
<p></p>
<script>
$( "input" )
.keyup(function() {
var value = $( this ).val();
$( "p" ).text( value );
})
.keyup();
</script>
</body>
</html>
.val( value )
القيمة المعادة
يُعيد كائنًا من النوع jQuery.
الوصف
تعيين قيمة كل عنصر في مجموعة العناصر المُطابقة.
.val( value )
أُضيف مع الإصدار: 1.0.
value
قيمة من النوع String أو Number أو Array من السلاسل المقابلة لقيمة كل عنصر مُطابق لتعيينه كما هو مُحدد أو مُؤشر.
.val( function )
أُضيف مع الإصدار: 1.4.
function
دالة على الشكل Function( Integer index, String value ) => String.
وهي تعيد القيمة المراد تعيينها. this هو العنصر الحالي. وهي تستقبل موضع فهرس العنصر في المجموعة والقيمة القديمة كوسائط.
يستخدم هذا التابع عادة لتعيين قيم حقول النموذج.
يسمح val() بتمرير مصفوفة من قيم العناصر. يفيد ذلك عند العمل على كائن jQuery يحتوي على عناصر مثل <input type="checkbox"> و <input type="radio"> و <option> داخل <select>. في هذه الحالة، سيُختار أو يُؤشَّر input و options إذا كان لها قيمة value تتطابق مع أحد عناصر المصفوفة، بينما لا يُختار أو يُؤشَّر على الذين لم يتحدد لهم قيمة value لا تطابق أيًا من عناصر المصفوفة أو لم تُحدد، اعتمادًا على النوع. في حالة <input type="radio"> التي تعد جزءًا من مجموعة أزرار الانتقاء (radio) و <select>، فسيلغى تحديد أي عنصر مُحدد مسبقًا.
لا يؤدي تعيين القيم باستخدام هذا التابع (أو باستخدام خاصية value الأصلية) إلى إرسال الحدث change. لهذا السبب، لن تُنفَّذ معالجات الأحداث ذات الصلة. ويجب استدعاء .trigger( "change" ) بعد تعيين القيمة لتنفيذها.
يسمح التابع .val() بضبط القيمة عن طريق تمريرها في دالة. بدءًا من jQuery 1.4، يُمرر وسيطان للدالة، فهرس العنصر الحالي وقيمته الحالية:
$( "input[type=text].tags" ).val(function( index, value ) {
return value.trim();
});
يزيل هذا المثال المسافات البيضاء السابقة واللاحقة من قيم مدخلات النص من الصنف tags.
أمثلة
ضبط قيمة مربع الإدخال <input>:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>val مثال على التابع</title>
<style>
button {
margin: 4px;
cursor: pointer;
}
input {
margin: 4px;
color: blue;
}
</style>
<script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
<div>
<button>أدخل</button>
<button>شيئًا</button>
<button>هنا</button>
</div>
<input type="text" value="اضغط أخد الأزرار">
<script>
$( "button" ).click(function() {
var text = $( this ).text();
$( "input" ).val( text );
});
</script>
</body>
</html>
استخدم وسيط الدالة لتعديل قيمة مربع الإدخال <input>:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>val مثال على التابع</title>
<script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
<p>اكتب شيئًا، ثم انقر على اضغط زر علامة التبويب للخروج من خانة الإدخال.</p>
<input type="text" value="اكتب شيئًا">
<script>
$( "input" ).on( "blur", function() {
$( this ).val(function( i, val ) {
return val.toUpperCase();
});
});
</script>
</body>
</html>
ضبط خيار واحد وخيارات متعددة <select>، وخانات التأشير (checkbox)، وزر الانتقاء (radio):
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>val مثال على التابع</title>
<style>
body {
color: blue;
}
</style>
<script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
<select id="single">
<option>مفرد</option>
<option>مفرد2</option>
</select>
<select id="multiple" multiple="multiple">
<option selected="selected">متعدد</option>
<option>متعدد2</option>
<option selected="selected">متعدد3</option>
</select>
<br>
<input type="checkbox" name="checkboxname" value="check1"> علامة1
<input type="checkbox" name="checkboxname" value="check2"> علامة2
<input type="radio" name="r" value="radio1"> راديو1
<input type="radio" name="r" value="radio2"> راديو2
<script>
$( "#single" ).val( "Single2" );
$( "#multiple" ).val([ "متعدد2", "متعدد3" ]);
$( "input").val([ "علامة1", "علامة2", "راديو1" ]);
</script>
</body>
</html>