التابع .outerWidth() في jQuery
يجلب هذا التابع قيمة العرض الخارجي (outer width، تتضمن الحواشي padding، والإطار border، والهامش margin اختياريًّا) الحاليَّة لأول عنصر في مجموعة العناصر المطابقة، أو يغير قيمة العرض الخارجي لكل العناصر المطابقة.
.outerWidth( [includeMargin ] )
القيم المعادة
يعيد عددًا من النوع Number.
الوصف
يجلب هذا التابع قيمة العرض الخارجي (outer height، تتضمن الحواشي [padding]، والإطار [border]، والهامش [margin] اختياريًّا) الحاليَّة لأول عنصر في مجموعة العناصر المطابقة.
.outerWidth( [includeMargin ] )
أضيف مع الإصدار 1.2.6.
includeMargin
قيمة منطقيَّة (boolean) تحدِّد إن كانت ستضاف قيمة هوامش العنصر إلى قيمة عرضه الخارجي أم لا. القيمة الافتراضيَّة هي false.
يعيد هذا التابع قيمة عرض العنصر وتتضمن الحواشي، وحدَّ الإطار، والهوامش (اختياريًّا) اليمنى واليسرى بواحدة البكسل. إن استُدعي التابع مع مجموعة عناصر فارغة، فسيعيد القيمة undefined (أو القيمة null قبل الإصدار jQuery 3.0).
لا يمكن استعمال هذا التابع على العنصر window والعنصر document، إذ يُستعمل معهما التابع .width() عوضًا عن ذلك. رغم أنه يمكن استعمال التابع .outerWidth() مع عناصر الجدول <table>، فقد يعيد نتائج غير متوقعة إن كان الجدول يستعمل الخاصِّيَّة border-collapse: collapse.
ملاحظات إضافية
- يمكن للعدد الذي يُعاد باستعمال الواجهات البرمجية (API) المتعلقة بالأبعاد، بما في ذلك التابع
()outerWidth.، أن يكون عددًا كسريًا في بعض الحالات، لذا لا يجب على الشيفرة المكتوبة أن تفترض بأنه عدد صحيح. يمكن للأبعاد أيضًا أن تكون خطأ عندما تكون الصفحة مكبرة (zoomed) من طرف المستخدم، إذ لا تعطي المتصفحات واجهةً برمجيةً للتعرف تلك على هذه الحالة. - لا يمكن ضمان أن القيمة التي يعيدها التابع
()outerWidth.دقيقةٌ إن كان العنصر أو أبوه مخفيين (hidden). للحصول على قيمة دقيقة، يجب التأكد من أنَّ العنصر مرئي قبل استعمال التابع. رغم ذلك، ستحاول jQuery إظهار العنصر مؤقتًا لقياس أبعاده ثم إخفاه مجدَّدًا، ولكن هذه الطريقة غير مضمونة (حتى لو أُعيدت قيم دقيقة)، إذ من الممكن أن تؤثِّر بشكل ملحوظ على أداء الصفحة. من المحتمل حذف طريقة الإظهار والإخفاء هذه، المستعملة في القياس، في إصدارات jQuery القادمة.
أمثلة
إعادة قيمة العرض الخارجي لفقرة <p>:
<!doctype html>
<html lang="ar">
<head>
<meta charset="utf-8">
<title>outerWidth مثالٌ عن استعمال التابع</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.outerWidth() +
" - العرض الخارجي متضمنًا الهوامش: " + p.outerWidth( true ) );
</script>
</body>
</html>
.outerWidth( value )
القيم المعادة
يعيد كائنًا من النوع jQuery.
الوصف
يغيِّر هذا التابع قيمة عرض عنصر CSS الخارجي لكل العناصر المطابقة.
.outerWidth( value )
أضيف مع الإصدار 1.8.0.
value
سلسلة نصية تحتوي على عدد مع واحدة أو عدد بدون واحدة (واحدته البكسل فرضًا) ويمثلان قيمة الارتفاع الخارجي.
.outerWidth( function )
أضيف مع الإصدار 1.8.0.
function
دالة من الشكل Function( Integer index, Number width ) تعيد سلسلةً نصيةً أو عددًا يمثل قيمة العرض الخارجي. يُمرَّر لهذه الدالة وسيطين اثنين هما: فهرسٌ يمثل موضع العنصر في مجموعة العناصر المطابقة، وقيمة العرض الخارجي القديمة. تشير this داخل الدالة إلى العنصر الحالي ضمن المجموعة.
عند استدعاء التابع outerWidth(value).، يمكن أن يكون الوسيط value سلسلةً نصيةً (عددًا وبجانبه واحدة) أو عددًا فقط. إذا أعطي عددٌ فقط، فستفترض jQuery أنَّ الواحدة المستعملة هي البكسل. أمَّا إن أعطيت سلسلة نصية، فيمكن حينئذٍ استعمال أي واحدة قياس تدعمها CSS (مثل 100px أو 50% أو auto).
أمثلة
تغيير العرض الخارجي لكل عنصر <div> عند الضغط عليه لأول مرة، وتغيير لونه أيضًا:
<!doctype html>
<html lang="ar">
<head>
<meta charset="utf-8">
<title>outerWidth مثالٌ عن استعمال التابع</title>
<style>
div {
width: 60px;
padding: 10px;
height: 50px;
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 modWidth = 60;
$( "div" ).one( "click", function() {
$( this ).outerWidth( modWidth ).addClass( "mod" );
modWidth -= 8;
});
</script>
</body>
</html>