التابع ‎‎.outerHeight()‎‎ في jQuery

من موسوعة حسوب
اذهب إلى: تصفح، ابحث

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

‎.outerHeight( [includeMargin ] )‎

القيم المعادة

يعيد عددًا من النوع Number.

الوصف

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

‎.outerHeight( [includeMargin ] )‎

أضيف مع الإصدار 1.2.6.

includeMargin

قيمة منطقيَّة (boolean) تحدِّد إن كانت ستضاف قيمة هوامش العنصر إلى قيمة ارتفاعه الخارجي أم لا. القيمة الافتراضيَّة هي false.

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

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

ملاحظات إضافية

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

أمثلة

إعادة قيمة الارتفاع الخارجي لفقرة <p>:
<!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>

‎.outerHeight( value )‎

القيم المعادة

يعيد كائنًا من النوع jQuery.

الوصف

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

‎.outerHeight( value )‎

أضيف مع الإصدار 1.8.0.

value

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

‎.outerHeight( function )‎

أضيف مع الإصدار 1.8.0.

function

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

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

أمثلة

تغيير الارتفاع الخارجي لكل عنصر <div> عند الضغط عليه لأول مرة، وتغيير لونه أيضًا:
<!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>

مصادر