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

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

يجلب الإحداثيات الحاليَّة للعنصر الأول أو يضبط إحداثيات كل عنصر في مجموعة العناصر المطابقة نسبةً إلى الصفحة.

‎.offset()‎

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

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

الوصف

يجلب الإحداثيات الحاليَّة للعنصر الأول في مجموعة العناصر المطابقة نسبةً إلى الصفحة.

‎.offset()‎

أُضيف مع الإصدار: 1.2. لا يقبل هذا الشكل أي وسائط.

يسمح لنا التابع ‎.offset()‎ بمعرفة الموقع الحالي لعنصر محدَّد (خصوصًا معرفة حدوده ويُستثنى منها الهوامش) نسبةً إلى الصفحة. من جهة أخرى، نجد أنَّ التابع ‎.position()‎ يعيد الموقع الحالي للعنصر نسبة إلى بعد العنصر الأب. عند وضع عنصر جديد فوق عنصر حالي من أجل التعديل العام (خصوصًا من أجل تنفيذ السحب والإفلات [drag-and-drop])، فاستعمال التابع ‎.offset()‎ ذو فائدة أكبر.

يعيد التابع كائنًا يحتوي على الخاصِّيَّة top والخاصِّيَّة left.

ملاحظة: لا تدعم jQuery الحصول على إحداثيات العناصر المخفية ولا تأخذ بالحسبان قيمة الهوامش المضبوطة للعنصر <html> في الصفحة. على أي حال، يمكن الحصول على إحداثيات العناصر ذات الخاصِّيَّة visibility: hidden، إذ تُستبعَد العناصر ذات الخاصِّيَّة display: none من تصييرها (rendering) ضمن الشجرة وبذلك تكون إحداثياتها غير معروفة (undefined).

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

قد يكون العدد المُعاد باستعمال الوجهات البرمجية (APIs) المتعلقة بالأبعاد، من ضمنها ‎.offset()‎، كسريًّا. فيجب ألا تفترض الشيفرة أنَّ هذا العدد صحيحٌ (integer). بالإضافة إلى ذلك، قد تكون الأبعاد خطأ عندما يكبِّر المستخدم الصفحة، إذ لا توفِّر المتصفحات واجهةً برمجيةً لمعرفة أنَّ هذه الحالة قد وقعت.

أمثلة

جلب إحداثيات الفقرة الثانية:
<!doctype html>
<html lang="ar">
<head>
  <meta charset="utf-8">
  <title>offset مثالٌ عن استعمال التابع</title>
  <style>
  p {
    margin-left: 10px;
  }
  </style>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
<p>مرحبًا، أنا الفقرة الأولى</p><p>أهلًا بك، أنا فقرةٌ ثانية</p>
 
<script>
var p = $( "p:last" );
var offset = p.offset();
p.html( "left: " + offset.left + ", top: " + offset.top );
</script>
 
</body>
</html>
الضغط على العنصر لمعرفة إحداثياته:
<!doctype html>
<html lang="ar">
<head>
  <meta charset="utf-8">
  <title>offset مثالٌ عن استعمال التابع</title>
  <style>
  p {
    margin-left: 10px;
    color: blue;
    width: 200px;
    cursor: pointer;
  }
  span {
    color: red;
    cursor: pointer;
  }
  div.abs {
    width: 50px;
    height: 50px;
    position: absolute;
    left: 220px;
    top: 35px;
    background-color: green;
    cursor: pointer;
  }
  </style>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
<div id="result">اضغط على أي عنصر</div>
<p>
  هذه أفضل طريقة <span>لإيجاد</span> الإحداثيات
</p>
<div class="abs">
</div>
 
<script>
$( "*", document.body ).click(function( event ) {
  var offset = $( this ).offset();
  event.stopPropagation();
  $( "#result" ).text( this.tagName +
    " إحداثيات ( " + offset.left + ", " + offset.top + " )" );
});
</script>
 
</body>
</html>

‎.offset( coordinates )‎

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

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

الوصف

يضبط هذا التابع إحداثيات كل عنصر في مجموعة العناصر المطابقة نسبةً إلى الصفحة.

‎.offset( coordinates )‎

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

coordinates

كائن مجرَّد يحتوي على الخاصِّيَّة top والخاصِّيَّة left اللتان تمثلان الإحداثيات الجديدة للعناصر.

‎.offset( function )‎

أُضيف مع الإصدار: 1.4.

دالة من الشكل Function( Number index, Object coords )‎ تعيد كائنًا مجرَّدًا يمثل الإحداثيات الجديدة. الوسيط الأول المُمرَّر إلى هذه الدالة هو فهرس العنصر في المجموعة، والوسيط الثاني هو الإحداثيات الحاليَّة. يجب أن تعيد الدالة كائنًا يحتوي على الخاصِّيَّة top والخاصِّيَّة left الجديدتان.

يسمح لنا التابع ‎.offset()‎ بتغيير موقع عنصر محدَّد. تعطى موقع إطار (border-box) العنصر نسبةً إلى الصفحة. إن كانت قيمة الخاصِّيّة position للعنصر هي static، فيجب تغييرها إلى القيمة relative من أجل التمكن من تغيير موضعها.

أمثلة

تغيير موقع الفقرة الثانية:
<!doctype html>
<html lang="ar">
<head>
  <meta charset="utf-8">
  <title>offset مثالٌ عن استعمال التابع</title>
  <style>
  p {
    margin-left: 10px;
  }
  </style>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
<p>مرحبًا، أنا الفقرة الأولى</p><p>أهلًا بك، أنا الفقرة الثانية</p>
 
<script>
$( "p:last" ).offset({ top: 10, left: 30 });
</script>
 
</body>
</html>

مصادر