الفرق بين المراجعتين لصفحة: «jQuery/val»

مرئينص الويكي

المراجعة الحالية بتاريخ 12:44، 25 يونيو 2018

إعادة القيمة الحالية للعنصر الأول في مجموعة العناصر المُطابقة أو تعيين قيمة (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>

مصادر

صفحة التابع ‎ ‎.val()‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎في توثيق jQuery الرسمي.

@@ سطر 1: / سطر 1: @@
 <noinclude>{{DISPLAYTITLE:التابع <code>‎.val()‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎</code>‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎ في jQuery}}</noinclude>
-إعادة القيمة الحالية للعنصر الأول في مجموعة العناصر المُطابقة أو تعيين قيمة كل عنصر مُطابق.
+إعادة القيمة الحالية للعنصر الأول في مجموعة العناصر المُطابقة أو تعيين قيمة (value) كل عنصر مُطابق.
 == <code>‎.val()‎</code> ==
 === القيمة المعادة ===
-يُعيد كائنًا من النوع [[JavaScript/String|String]] أو [[JavaScript/Number|Number]] أو [[JavaScript/Array|Array]]
+يُعيد كائنًا من النوع [[JavaScript/String|<code>String</code>]] أو [[JavaScript/Number|<code>Number</code>]] أو [[JavaScript/Array|<code>Array</code>]].
 === الوصف ===
 إعادة القيمة الحالية للعنصر الأول في مجموعة العناصر المُطابقة.
-=== <code>.val()‎</code> ===
+=== ‎<code>.val()‎</code> ===
 أُضيف مع الإصدار: [http://api.jquery.com/category/version/1.0 1.0].
 لا يقبل هذا الشكل أي وسائط.
-يستخدم التابع ‎<code>.val()</code>‎ في المقام الأول للحصول على قيم عناصر النماذج مثل <code>[[HTML/input|input]]</code> و <code>[[HTML/select|select]]</code> و <code>[[HTML/textarea|textarea]]</code>. عند استدعائها على مجموعة فارغة، فإنها تُعيد <code>[[JavaScript/undefined|undefined]]</code>.
+يستخدم التابع ‎<code>.val()</code>‎ في المقام الأول للحصول على قيم عناصر النماذج مثل <code>[[HTML/input|<input>]]</code> و <code>[[HTML/select|<select>]]</code> و <code>[[HTML/textarea|<textarea>]]</code>. عند استدعائها على مجموعة فارغة، فإنها تُعيد <code>[[JavaScript/undefined|undefined]]</code>.
-عندما يكون العنصر الأول في المجموعة هو <code>select-multiple</code> (أي، عنصر <code>[[HTML/select|select]]</code> مع مجموعة <code>multiple</code> خاصيات)، يُعيد <code>‎.val()</code>‎ مصفوفة تحتوي على قيمة كل خيار محدد. بدءًا من jQuery [http://api.jquery.com/category/version/3.0 3.0]، إذا لم يُحدد أي خيارات، فسوف يعيد هذا التابع مصفوفة فارغة؛ وكان يُعيد <code>null</code> قبل jQuery [http://api.jquery.com/category/version/3.0 3.0].
+عندما يكون العنصر الأول في المجموعة هو <code>select-multiple</code> (أي عنصر <code>[[HTML/select|<select>]]</code> مع ضبط الخاصية <code>multiple</code> عليه)، سيُعيد <code>‎.val()</code>‎ مصفوفة تحتوي على قيمة كل خيار محدد. بدءًا من jQuery [http://api.jquery.com/category/version/3.0 3.0]، إذا لم يُحدد أي خيارات، فسوف يعيد هذا التابع مصفوفة فارغة؛ وكان يُعيد <code>null</code> قبل jQuery [http://api.jquery.com/category/version/3.0 3.0].
-بالنسبة للتحديدات، وخانات التأشير وأزرار الإنتقاء، يمكنك استخدام المُحدد <code>[[jQuery/checked selector|‎:checked]]</code> لتحديد العناصر الصحيحة. فمثلا:<syntaxhighlight lang="jquery">
+بالنسبة للتحديدات، وخانات التأشير وأزرار الإنتقاء، يمكنك استخدام المُحدد <code>[[jQuery/checked selector|‎:checked]]</code> لتحديد العناصر الصحيحة. فمثلًا:<syntaxhighlight lang="jquery">
 // إعادة القيمة من الخيار المحدد في قائمة منسدلة
 $( "select#foo option:checked" ).val();
-/ إعادة القيمة من تحديد قائمة منسدلة مباشرةً
+// إعادة القيمة من تحديد قائمة منسدلة مباشرةً
 $( "select#foo" ).val();
@@ سطر 31: / سطر 31: @@
 // إعادة القيمة من مجموعة أزرار انتقاء
 $( "input[type=radio][name=baz]:checked" ).val();
-</syntaxhighlight>ملاحظة: في الوقت الحالي، يُجرِّد استخدام <code>‎.val()‎</code> على عناصر <code>[[HTML/textarea|<textarea>]]</code> محرف الإرجاع من القيمة التي أعادها المستعرض. عند إرسال هذه القيمة إلى الخادم عبر XHR، ومع ذلك، يُحتفظ بمحرف الإرجاع (أو تضيفه المتصفحات التي لا تتضمنها في القيمة الأولية). يمكن استخدام حل بديل لهذه المشكلة باستخدام <code>valHook</code> على النحو التالي:<syntaxhighlight lang="jquery">
+</syntaxhighlight>ملاحظة: في الوقت الحالي، يُجرِّد استخدام <code>‎.val()‎</code> على عناصر <code>[[HTML/textarea|<textarea>]]</code> محرف العودة إلى بداية السطر (‎<code>\r</code>) من القيمة التي أعادها المتصفح. عند إرسال هذه القيمة إلى الخادم عبر XHR، ومع ذلك، يُحتفظ بمحرف العودة إلى بداية السطر (أو تضيفه المتصفحات التي لا تتضمنها في القيمة الأولية). يمكن استخدام حل بديل لهذه المشكلة باستخدام <code>valHook</code> على النحو التالي:<syntaxhighlight lang="jquery">
 $.valHooks.textarea = {
    get: function( elem ) {
@@ سطر 40: / سطر 40: @@
 === أمثلة ===
-إعادة القيمة المفردة من تحديد مفرد، وإعادة مصفوفة من القيم من تحديد متعدد وعرض قيمها.<syntaxhighlight lang="html">
+إعادة القيمة المفردة من عنصر <code>[[HTML/select|<select>]]</code> مفرد، وإعادة مصفوفة من القيم من عنصر <code>[[HTML/select|<select>]]</code> متعدد الاختيارات وعرض قيمها:<syntaxhighlight lang="html">
 <!doctype html>
 <html lang="en">
@@ سطر 88: / سطر 88: @@
 </body>
 </html>
-</syntaxhighlight>البحث عن قيمة مربع الإدخال.<syntaxhighlight lang="html">
+</syntaxhighlight>البحث عن قيمة مربع الإدخال <code>[[HTML/input|<input>]]</code>:<syntaxhighlight lang="html">
 <!doctype html>
 <html lang="en">
@@ سطر 132: / سطر 132: @@
 ==== <code>value</code> ====
-سلسلة من النوع [[JavaScript/String|String]] أو [[JavaScript/Number|Number]] أو [[JavaScript/Array|Array]] من السلاسل المقابلة لقيمة كل عنصر مُطابق لتعيينه كما هو مُحدد أو مُؤشر.
+قيمة من النوع [[JavaScript/String|<code>String</code>]] أو [[JavaScript/Number|<code>Number</code>]] أو [[JavaScript/Array|<code>Array</code>]] من السلاسل المقابلة لقيمة كل عنصر مُطابق لتعيينه كما هو مُحدد أو مُؤشر.
 === <code>‎.val( function )‎</code> ===
@@ سطر 138: / سطر 138: @@
 ==== <code>function</code> ====
-دالة على الشكل [[JavaScript/Function|Function]]( Integer index, [[JavaScript/String|String]] value ) => [[JavaScript/String|String]].
+دالة على الشكل <code>[[JavaScript/Function|Function]]( Integer index, [[JavaScript/String|String]] value ) => [[JavaScript/String|String]]</code>.
 وهي تعيد القيمة المراد تعيينها. <code>[[JavaScript/this|this]]</code> هو العنصر الحالي. وهي تستقبل موضع فهرس العنصر في المجموعة والقيمة القديمة كوسائط.
@@ سطر 144: / سطر 144: @@
 يستخدم هذا التابع عادة لتعيين قيم حقول النموذج.
-يسمح <code>val()</code>‎ بتمرير مصفوفة من قيم العناصر. يفيد ذلك عند العمل على كائن jQuery يحتوي على عناصر مثل <code><input type="checkbox"></code> و <code><input type="radio"></code> و <code><options></code> داخل <code><select></code>. في هذه الحالة، سيتحدد <code>input</code> و <code>options</code> إذا كان لهم قيمة <code>value</code> تتطابق مع أحد عناصر المصفوفة، بينما هؤلاء الذين لم يتحدد لهم قيمة <code>value</code> التي لا تطابق أيًا من عناصر المصفوفة أو لم تُحدد، اعتمادًا على النوع. في حالة <code><input type="radio"></code> التي تعد جزءًا من مجموعة راديو و <code><select></code>، سيلغى تحديد أي عنصر مُحدد مسبقًا.
+يسمح <code>val()</code>‎ بتمرير مصفوفة من قيم العناصر. يفيد ذلك عند العمل على كائن jQuery يحتوي على عناصر مثل <code><input type="checkbox"‎></code> و <code><input type="radio"‎></code> و <code>[[HTML/option|<option>]]</code> داخل <code>[[HTML/select|<select>]]</code>. في هذه الحالة، سيُختار أو يُؤشَّر <code>input</code> و <code>options</code> إذا كان لها قيمة <code>value</code> تتطابق مع أحد عناصر المصفوفة، بينما لا يُختار أو يُؤشَّر على الذين لم يتحدد لهم قيمة <code>value</code> لا تطابق أيًا من عناصر المصفوفة أو لم تُحدد، اعتمادًا على النوع. في حالة <code><input type="radio"‎></code> التي تعد جزءًا من مجموعة أزرار الانتقاء (radio) و <code><select></code>، فسيلغى تحديد أي عنصر مُحدد مسبقًا.
-لا يؤدي تعيين القيم باستخدام هذا التابع (أو باستخدام خاصية value الأصلية) إلى إرسال حدث <code>change</code>. لهذا السبب، لن تُنفَّذ معالجات الأحداث ذات الصلة. ويجب استدعاء ‎<code>[[jQuery/trigger|.trigger( "change" )‎]]</code> بعد تعيين القيمة لتنفيذها.
+لا يؤدي تعيين القيم باستخدام هذا التابع (أو باستخدام خاصية <code>value</code> الأصلية) إلى إرسال الحدث <code>change</code>. لهذا السبب، لن تُنفَّذ معالجات الأحداث ذات الصلة. ويجب استدعاء ‎<code>[[jQuery/trigger|.trigger( "change" )‎]]</code> بعد تعيين القيمة لتنفيذها.
 يسمح التابع <code>‎.val()‎</code> بضبط القيمة عن طريق تمريرها في دالة. بدءًا من jQuery [http://api.jquery.com/category/version/1.4 1.4]، يُمرر وسيطان للدالة، فهرس العنصر الحالي وقيمته الحالية:<syntaxhighlight lang="jquery">
@@ سطر 152: / سطر 152: @@
    return value.trim();
 });
-</syntaxhighlight>يزيل هذا المثال المسافات البيضاء السابقة واللاحقة من قيم مدخلات النص من الصنف "tags".
+</syntaxhighlight>يزيل هذا المثال المسافات البيضاء السابقة واللاحقة من قيم مدخلات النص من الصنف <code>tags</code>.
 === أمثلة ===
-ضبط قيمة مربع الإدخال.<syntaxhighlight lang="html">
+ضبط قيمة مربع الإدخال <code>[[HTML/input|<input>]]</code>:<syntaxhighlight lang="html">
 <!doctype html>
 <html lang="en">
@@ سطر 191: / سطر 191: @@
 </body>
 </html>
-</syntaxhighlight>استخدم وسيط الدالة لتعديل قيمة مربع الإدخال.<syntaxhighlight lang="html">
+</syntaxhighlight>استخدم وسيط الدالة لتعديل قيمة مربع الإدخال <code>[[HTML/input|<input>]]</code>:<syntaxhighlight lang="html">
 <!doctype html>
 <html lang="en">
@@ سطر 214: / سطر 214: @@
 </body>
 </html>
-</syntaxhighlight>ضبط خيارًا واحدًا، وخيارات متعددة، وخانات التأشير، وزر الانتقاء.<syntaxhighlight lang="html">
+</syntaxhighlight>ضبط خيار واحد وخيارات متعددة <code>[[HTML/select|<select>]]</code>، وخانات التأشير ([[HTML/input/checkbox|checkbox]])، وزر الانتقاء ([[HTML/input/radio|radio]]):<syntaxhighlight lang="html">
 <!doctype html>
 <html lang="en">