عرض مصدر jQuery/height

<noinclude>{{DISPLAYTITLE:التابع <code>‎.height()‎</code>‎ في jQuery}}</noinclude>
يجلب هذا التابع الطول الحالي لأول عنصر في مجموعة العناصر المتطابقة أو يغير الطول لكل العناصر المتطابقة.

== <code>‎.height()‎</code> ==

=== القيم المعادة ===
عدد من النوع Number.

=== الوصف ===
يجلب هذا التابع الطول الحالي لأول عنصر في مجموعة العناصر المتطابقة سابقًا.

=== <code>‎.height()‎</code> ===
أضيف مع الإصدار 1.0، ولا يقبل هذا التابع أي معاملات.

الفرق بين التابع <code>‎.css( "height" )‎</code> والتابع <code>‎.height()‎</code> هو أن الأخير يعيد قيمة الطول بدون واحدة (يعيد 400 مثلًا)، بينما يعيد التابع الأول قيمة الطول مع واحدة (يعيد 400px مثلًا). يفضل استعمال التابع <code>‎.height()‎</code> عندما الحاجة إلى استعمال طول العنصر في حسابات رياضية.

يمتلك هذا التابع أيضًا القدرة على إيجاد طول نافذة المتصفح و طول الصفحة.<syntaxhighlight lang="html">
// إعادة ارتفاع إطار العرض
$( window ).height();
 
// إعادة ارتفاع المستند
$( document ).height();
</syntaxhighlight>يجب الانتباه إلى أن التابع <code>‎.height()‎</code> يعيد طول صندوق المحتوى دومًا بغض النظر عن قيمة الخاصية <code>[[CSS/box-sizing|box-sizing]]</code> في [[CSS]]. قد يتطلَّب ابتداءًا من الإصدار jQuery 1.8 استرجاع قيمة الخاصية <code>height</code> في CSS بالإضافة إلى قيمة الخاصية <code>[[CSS/box-sizing|box-sizing]]</code> للحصول على طول المحتوى، ثمَّ يُطرح بعد ذلك قيمة الحواشي أو الإطار لكل عنصر عندما تكون قيمة الخاصية <code>box-sizing</code> هي نفسها <code>border-box</code>. لتجنب هذا التعقيد، استعمل التابع <code>‎.css( "height" )‎</code> عوضًا عن التابع <code>‎.height()‎</code>.

'''ملاحظة''': رغم أن العناصر <code>[[HTML/style|<style>]]</code> و <code>[[HTML/script|<script>]]</code> ستبلغ عن قيمةٍ للتابع <code>[[jQuery/width|‎.width()‎]]</code> أو التابع <code>‎.height()</code>‎ عند ضبط خاصيات CSS التالية عليها: <code>position: absolute</code> و <code>display: block</code>، إلا أنَّه لا ينصح مطلقًا استعمال هذه التوابع مع تلك العناصر. بالإضافة إلى كون هذا عادة سيئة، ومن الممكن أن تكون النتائج غير صحيحة.

=== ملاحظات إضافية ===
* يمكن للعدد الذي يُعاد باستعمال الواجهات البرمجية (API) المتعلقة بالأبعاد، بما في ذلك التابع <code>()height.</code>، أن يكون عددًا كسريًا في بعض الحالات، لذا لا يجب للشيفرة المكتوبة أن تفترض بأنه عدد صحيح. يمكن للأبعاد أيضًا أن تكون خطأ عندما تكون الصفحة مكبرة (zoomed) من طرف المستخدم، إذ لا تعطي المتصفحات واجهةً برمجيةً للتعرف تلك على هذه الحالة.
* لا يمكن ضمان أن القيمة التي يعيدها التابع <code>()height.</code> دقيقةٌ في حالة أن العنصر أو أبوه مخفيين (hidden). للحصول على قيمة دقيقة، يجب التأكد من أن العنصر مرئي قبل استعمال التابع. رغم ذلك، ستحاول jQuery إظهار العنصر لقياس أبعاده و من ثم إخفاه، ولكن هذه الطريقة غير مضمونة (حتى لو أُعيدت قيم دقيقة)، إذ من الممكن أن تؤثر بشكل ملحوظ عن أداء الصفحة. من المحتمل حذف طريقة الإظهار والإخفاء هذه، المستعملة في القياس، في إصدارات jQuery القادمة.

=== أمثلة ===
إظهار أطوال مختلفة. يجب الإنتباه إلى أن القيم تتعلق بالإطار المراد الحصول على طوله، لذا من الممكن أن تكون القيم أصغر مما تتوقع. الخلفية الصفراء توضح جسم الإطار.<syntaxhighlight lang="html">
<!doctype html>
<html lang="en">
<head>
 <meta charset="utf-8">
 <title>height demo</title>
 <style>
 body {
   background: yellow;
 }
 button {
   font-size: 12px;
   margin: 2px;
 }
 p {
   width: 150px;
   border: 1px red solid;
 }
 div {
   color: red;
   font-weight: bold;
 }
 </style>
 <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
<button id="getp">Get Paragraph Height</button>
<button id="getd">Get Document Height</button>
<button id="getw">Get Window Height</button>
<div>&nbsp;</div>
<p>
 Sample paragraph to test height
</p>
<script>
function showHeight( element, height ) {
 $( "div" ).text( "The height for the " + element + " is " + height + "px." );
}
$( "#getp" ).click(function() {
 showHeight( "paragraph", $( "p" ).height() );
});
$( "#getd" ).click(function() {
 showHeight( "document", $( document ).height() );
});
$( "#getw" ).click(function() {
 showHeight( "window", $( window ).height() );
});
</script>
</body>
</html>
</syntaxhighlight>

== <code>‎.height( value )‎</code> ==

=== القيم المعادة ===
يعيد كائن jQuery.

=== الوصف ===
يغير هذا التابع طول عنصر CSS لكل العناصر المطابقة.

=== <code>height( value )‎.</code> ===
أضيف مع الإصدار 1.0.

=== <code>value</code> ===
سلسلة نصية تحتوي على عدد مع واحدة أو عدد بدون واحدة ويمثلان عدد البكسلات (pixels).

=== <code>‎.height( function )‎</code> ===
أضيف مع الإصدار 1.8.0.

==== <code>function</code> ====
دالة من الشكل <code>Function( Number index, Number height )‎</code> تعيد سلسلة نصية أو عددًا يمثل قيمة الطول. يمرر لهذه الدالة معاملين اثنين هما: فهرس يمثل موضع العنصر في مجموعة العناصر المطابقة، والطول القديم. داخل الدالة، تشير <code>this</code> إلى العنصر الحالي ضمن المجموعة.

عند استدعاء التابع <code>height(value)‎.</code>، يمكن أن يكون المعامل <code>value</code> سلسلة نصية (عددًا وبجانبه واحدة) أو عددًا. إذا كان المعامل عددًا فإن jQuery تفترض أن الواحدة المستعملة هي البكسل. أما إذا كان المعامل سلسلة نصية فيمكن استعمال أي واحدة قياس تدعمها [[CSS]] للارتفاع (مثل 100px  أو 50% أو  auto). يجب الانتباه إلى أنه في المتصفحات الحديثة لا تتضمن قيمة خاصية الطول في CSS قيمة الحواشي، أو الإطار، أو الهوامش.

إذا لم تُحدَّد واحدة قياس (مثل 'em' أو '%')، فإن الواحدة الافتراضية التي ستستعمل هي البكسل ‘px’.

يجب الانتباه إلى أن التابع <code>‎.height(value)‎</code> يغير طول محتوى الصندوق بغض النظر عن قيمة خاصية <code>[[CSS/box-sizing|box-sizing]]</code> في CSS.

=== أمثلة ===
تغيير اللون إلى الأخضر و تغيير الطول إلى 30px عند النقر على أي عنصر <code>[[HTML/div|<nowiki><div></nowiki>]]</code>:<syntaxhighlight lang="html">
<!doctype html>
<html lang="en">
<head>
 <meta charset="utf-8">
 <title>height demo</title>
 <style>
 div {
   width: 50px;
   height: 70px;
   float: left;
   margin: 5px;
   background: rgb(255,140,0);
   cursor: pointer;
 }
 </style>
 <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
<div></div>
<div></div>
<div></div>
<div></div>
<div></div>
<script>
$( "div" ).one( "click", function() {
 $( this ).height( 30 ).css({
   cursor: "auto",
   backgroundColor: "green"
 });
});
</script>
</body>
</html>

</syntaxhighlight>

== مصادر ==
* [http://api.jquery.com/height/ صفحة التابع ‎‎.height()‎‎ في توثيق jQuery الرسمي.]
[[تصنيف:jQuery]]
[[تصنيف:jQuery Traversing]]