عرض مصدر jQuery/offset

<noinclude>{{DISPLAYTITLE:التابع <code>‎‎.offset()‎</code>‎ في jQuery}}</noinclude>
يجلب الإحداثيات الحاليَّة للعنصر الأول أو يضبط إحداثيات كل عنصر في مجموعة العناصر المطابقة نسبةً إلى الصفحة.

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

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

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

=== <code>‎.offset()‎</code> ===
أُضيف مع الإصدار: 1.2. لا يقبل هذا الشكل أي وسائط.

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

يعيد التابع كائنًا يحتوي على الخاصِّيَّة <code>[[CSS/top|top]]</code> والخاصِّيَّة <code>[[CSS/left|left]]</code>.

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

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

=== أمثلة ===
جلب إحداثيات الفقرة الثانية:<syntaxhighlight lang="html">
<!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>

</syntaxhighlight>الضغط على العنصر لمعرفة إحداثياته:<syntaxhighlight lang="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>

</syntaxhighlight>

== <code>‎.offset( coordinates )‎</code> ==

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

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

=== <code>‎.offset( coordinates )‎</code> ===
أضيف مع الإصدار: 1.4.

==== <code>coordinates</code> ====
كائن مجرَّد يحتوي على الخاصِّيَّة <code>[[CSS/top|top]]</code> والخاصِّيَّة <code>[[CSS/left|left]]</code> اللتان تمثلان الإحداثيات الجديدة للعناصر.

=== <code>‎.offset( function )‎</code> ===
أُضيف مع الإصدار: 1.4.

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

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

=== أمثلة ===
تغيير موقع الفقرة الثانية:<syntaxhighlight lang="html">
<!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>
</syntaxhighlight>

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