عرض مصدر jQuery/outerHeight

<noinclude>{{DISPLAYTITLE:التابع <code>‎‎.outerHeight()‎</code>‎ في jQuery}}</noinclude>
يجلب هذا التابع قيمة الارتفاع الخارجي (outer height، تتضمن الحواشي [[[CSS/padding|padding]]]، والإطار [[[CSS/border|border]]]، والهامش [[[CSS/margin|margin]]] اختياريًّا) الحاليَّة لأول عنصر في مجموعة العناصر المطابقة، أو يغير قيمة الارتفاع الخارجي لكل العناصر المطابقة.

== <code>‎.outerHeight( [includeMargin ] )‎</code> ==

=== القيم المعادة ===
يعيد عددًا من النوع [[JavaScript/Number|Number]].

=== الوصف ===
يجلب هذا التابع قيمة الارتفاع الخارجي (outer height، تتضمن الحواشي [padding]، والإطار [border]، والهامش [margin] اختياريًّا) الحاليَّة لأول عنصر في مجموعة العناصر المطابقة.

=== <code>‎.outerHeight( [includeMargin ] )‎</code> ===
أضيف مع الإصدار 1.2.6.

==== <code>includeMargin</code> ====
[[JavaScript/Boolean|قيمة منطقيَّة]] (boolean) تحدِّد إن كانت ستضاف قيمة هوامش العنصر إلى قيمة ارتفاعه الخارجي أم لا. القيمة الافتراضيَّة هي <code>false</code>.

يعيد هذا التابع قيمة ارتفاع العنصر وتتضمن الحواشي، والإطار، والهوامش (اختياريًّا) العليا والسفلى بواحدة البكسل. إن استُدعي التابع مع مجموعة عناصر فارغة، فسيعيد القيمة <code>[[JavaScript/undefined|undefined]]</code> (أو القيمة <code>[[JavaScript/null|null]]</code> قبل الإصدار jQuery 3.0).

لا يمكن استعمال هذا التابع على العنصر <code>window</code> والعنصر <code>document</code>، إذ يُستعمل معهما التابع ‎<code>[[jQuery/height|.height()]]</code>‎ عوضًا عن ذلك. رغم أنه يمكن استعمال التابع ‎<code>.outerHeight()‎</code> مع عناصر الجدول <code>[[HTML/table|<nowiki><table></nowiki>]]</code>، فقد يعيد نتائج غير متوقعة إن كان الجدول يستعمل الخاصِّيَّة <code>[[CSS/border-collapse|border-collapse: collapse]]</code>.

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

== أمثلة ==
إعادة قيمة الارتفاع الخارجي لفقرة <code>[[HTML/p|<nowiki><p></nowiki>]]</code>:<syntaxhighlight lang="html">
<!doctype html>
<html lang="ar">
<head>
  <meta charset="utf-8">
  <title>outerHeight مثالٌ عن استعمال التابع</title>
  <style>
  p {
    margin: 10px;
    padding: 5px;
    border: 2px solid #666;
  }
  </style>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
<p>مرحبًا</p><p></p>
 
<script>
var p = $( "p:first" );
$( "p:last" ).text(
  "الارتفاح الخارجي: " + p.outerHeight() +
  " - الارتفاع الخارجي متضمنًا الهوامش: " + p.outerHeight( true ) );
</script>
 
</body>
</html>

</syntaxhighlight>

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

=== القيم المعادة ===
يعيد كائنًا من النوع [[jQuery/jQuery|jQuery]].

=== الوصف ===
يغيِّر هذا التابع قيمة ارتفاع عنصر [[CSS]] الخارجي لكل العناصر المطابقة.

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

==== <code>value</code> ====
سلسلة نصية تحتوي على عدد مع واحدة أو عدد بدون واحدة (واحدته البكسل فرضًا) ويمثلان قيمة الارتفاع الخارجي.

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

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

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

== أمثلة ==
تغيير الارتفاع الخارجي لكل عنصر <code>[[HTML/div|<nowiki><div></nowiki>]]</code> عند الضغط عليه لأول مرة، وتغيير لونه أيضًا:<syntaxhighlight lang="html">
<!doctype html>
<html lang="ar">
<head>
  <meta charset="utf-8">
  <title>outerHeight مثالٌ عن استعمال التابع</title>
  <style>
  div {
    width: 50px;
    padding: 10px;
    height: 60px;
    float: left;
    margin: 5px;
    background: red;
    cursor: pointer;
  }
  .mod {
    background: blue;
    cursor: default;
  }
  </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>
var modHeight = 60;
$( "div" ).one( "click", function() {
  $( this ).outerHeight( modHeight ).addClass( "mod" );
  modHeight -= 8;
});
</script>
 
</body>
</html>

</syntaxhighlight>

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