ForHosting KIT · أدوات المطورين

حساب الإزاحة والحد الأقصى وعدد الصفحات

حوّل رقم صفحة يبدأ من واحد إلى القيم الدقيقة التي يحتاج إليها استعلام يعتمد على الإزاحة.

● Betaمجاني · داخل متصفحك

استخدمها من الويبAPIالبريدTelegramالتطبيق قريبًا

أدخل الصفحة المطلوبة، والحد الأقصى للسجلات في كل صفحة، وإجمالي العناصر المتاحة. تعيد الحاسبة إزاحة تبدأ من الصفر، وحد الاستعلام، والعدد الإجمالي للصفحات. كما ترفض رقم الصفحة أو حجمها إذا كان أقل من واحد، مما يساعد حضرتكم على منع استعلامات قاعدة البيانات غير الصالحة وعناصر التنقل غير المتسقة قبل وصولها إلى شيفرة التطبيق.

حوّل طلب الصفحة إلى معاملات للاستعلام

تعرض واجهات المستخدم ترقيم الصفحات عادةً بأرقام مفهومة للبشر، بينما تتطلب قواعد البيانات وواجهات API غالبًا إزاحة تبدأ من الصفر وحدًا أقصى. تصل هذه الحاسبة بين الطريقتين. أدخل رقم صفحة يبدأ من واحد، وحجم الصفحة، وإجمالي العناصر في المجموعة الكاملة. تُحسب الإزاحة بطرح واحد من رقم الصفحة ثم ضرب الناتج في حجم الصفحة، أما الحد فيساوي حجم الصفحة نفسه. فعلى سبيل المثال، تبدأ الصفحة الثالثة من مجموعة تُعرض بواقع خمسة وعشرين عنصرًا في الصفحة بعد أول خمسين عنصرًا، ولذلك تكون إزاحتها خمسين وحدها خمسة وعشرين. يمكنكم تمرير هاتين القيمتين مباشرةً إلى عبارة SQL شائعة تستخدم LIMIT وOFFSET، أو ربطهما بمعاملات مكافئة في خدمة أخرى. النتيجة حتمية، ولا تفحص الحاسبة السجلات الفعلية ولا تجلبها. فهي تنفذ فقط العملية الحسابية اللازمة لإعداد طلب مقسم إلى صفحات، ولذلك تفيد في الأنظمة الخلفية والبرامج النصية والاختبارات والتوثيق وجلسات تشخيص الأعطال.

افهم إجمالي الصفحات والحالات الحدية

يُحسب إجمالي الصفحات بقسمة العدد الكلي للعناصر على حجم الصفحة ثم تقريب الناتج إلى الأعلى. هذا التقريب مهم لأن الصفحة الأخيرة تظل صفحة حتى إن كانت ممتلئة جزئيًا. إذا عُرض مئة وعنصر واحد بمعدل خمسة وعشرين عنصرًا في الصفحة، فإن أربع صفحات تحتوي على مئة عنصر، وتحتوي صفحة خامسة على العنصر المتبقي. عندما يكون إجمالي العناصر صفرًا، يكون إجمالي الصفحات صفرًا أيضًا لعدم وجود صفحة نتائج. لا تُقيد الصفحة المطلوبة تلقائيًا بهذا الإجمالي؛ ولذلك قد ينتج عن طلب الصفحة العاشرة إزاحة صحيحة حسابيًا حتى لو كانت المجموعة لا تتجاوز ثلاث صفحات. هذا السلوك مقصود، إذ تقدم الحاسبة العمليات الحسابية وتترك سياسة التطبيق لكم. يمكن لتطبيقكم مقارنة الصفحة المطلوبة مع total_pages، ثم إعادة نتيجة فارغة، أو التوجيه إلى الصفحة الأخيرة، أو عرض استجابة تفيد بعدم العثور. إن فصل الحساب عن سياسة المعالجة يجعل المخرجات متوقعة في قواعد البيانات وخدمات REST وواجهات المستخدم.

تحقق من المدخلات قبل إنشاء الاستعلام

يجب أن تكون قيمتا page وpage_size عددين صحيحين آمنين لا تقلان عن واحد. فالقيمة الصفرية أو السالبة تخالف قاعدة بدء الصفحات من واحد أو تنشئ حدًا بلا معنى، ولهذا ينتج عنها خطأ إدخال غير صالح. ويجب أن تكون total_items عددًا صحيحًا آمنًا لا يقل عن صفر، لأن المجموعة لا يمكن أن تحتوي على عدد سالب أو كسري من السجلات. يمنع التحقق من الأعداد الصحيحة الآمنة كذلك فقدان الدقة بصمت في JavaScript عند ضرب قيم كبيرة جدًا. إذا تجاوزت الإزاحة المحسوبة النطاق الآمن، يُرفض الطلب بدلًا من إرجاع رقم غير دقيق. تفيد هذه القواعد خارج الحاسبة أيضًا؛ فتطبيق التحقق نفسه عند حدود API يمنع وصول المعاملات المشوهة إلى موصل قاعدة البيانات. لا تجري القدرة أي طلب شبكي، ولا تخزن البيانات، ولا تستخدم قيمًا عشوائية أو مرتبطة بالوقت. المدخل نفسه يعطي دائمًا المخرج نفسه. تبلغ تكلفة كل طلب آلي عبر API مقدار $0.002، ويمكنكم استخدام المتصفح للتحقق من الأمثلة أثناء تصميم منطق ترقيم الصفحات أو معالجة مشكلاته.

حالات الاستخدام

إنشاء استعلام لقاعدة البيانات

حوّل الصفحة المختارة في الواجهة إلى قيمتي LIMIT وOFFSET لاستخدامهما في استعلام SQL.

عرض عناصر التحكم في الصفحات

احسب إجمالي الصفحات اللازم لتمكين عناصر التنقل أو تعطيلها أو وضع تسميات لها.

اختبار الحالات الحدية في API

أنشئ القيم المتوقعة للمجموعات الفارغة والصفحات الأخيرة الجزئية والصفحات التي تتجاوز النتائج.

الأسئلة الشائعة

هل يبدأ رقم الصفحة من الصفر أم من الواحد؟

يبدأ من الواحد: الإزاحة في الصفحة 1 هي 0، وتبدأ الصفحة 2 بعد مقدار page_size كامل.

كيف تُحسب total_pages؟

تقسم الحاسبة total_items على page_size ثم تقرب الناتج إلى الأعلى لاحتساب الصفحة الأخيرة الجزئية.

ماذا يحدث عندما تكون total_items صفرًا؟

تكون total_pages مساوية لـ 0، بينما يستمر حساب offset وlimit من الصفحة والحجم المطلوبين.

هل يمكن طلب صفحة تأتي بعد total_pages؟

نعم. تعيد الحاسبة الإزاحة الحسابية، ويقرر تطبيقكم عرض نتيجة فارغة أو رفض الصفحة.

ما تكلفة طلب API؟

تبلغ تكلفة كل طلب API مقدار $0.002. وتتوفر الحاسبة كذلك في المتصفح.

للمطوّرين — الوصول عبر API

كل ما في هذه الصفحة متاح برمجيًا. هذا القسم موجّه للفرق التقنية التي تريد ربط الأداة بأنظمتها الخاصة؛ بقية المستخدمين يمكنهم استخدام الأداة أعلاه مباشرة دون الحاجة لقراءة ما يلي.

الـEndpoint

POSThttps://api.kit.forhosting.com/dev/pagination-offset-calc

صادِق على طلبك بترويسة Bearer، وأرسل طلب POST واحدًا لتدخل مهمتك قائمة التنفيذ فورًا؛ ثم تستلم النتيجة عبر webhook أو رابط موقّع.

استدعِ الخدمة من بيئتك

curl -X POST https://api.kit.forhosting.com/dev/pagination-offset-calc \
  -H "Authorization: Bearer $KIT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page":3,"page_size":25,"total_items":123}'

const res = await fetch("https://api.kit.forhosting.com/dev/pagination-offset-calc", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.KIT_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "page": 3,
    "page_size": 25,
    "total_items": 123
  })
});
const { task_id } = await res.json();

import os, requests

res = requests.post(
    "https://api.kit.forhosting.com/dev/pagination-offset-calc",
    headers={"Authorization": f"Bearer {os.environ['KIT_KEY']}"},
    json={
    "page": 3,
    "page_size": 25,
    "total_items": 123
},
)
task_id = res.json()["task_id"]

<?php
$res = file_get_contents("https://api.kit.forhosting.com/dev/pagination-offset-calc", false, stream_context_create([
  "http" => [
    "method"  => "POST",
    "header"  => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
    "content" => '{"page":3,"page_size":25,"total_items":123}',
  ],
]));
$task = json_decode($res, true);

body := bytes.NewBufferString(`{"page":3,"page_size":25,"total_items":123}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/dev/pagination-offset-calc", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)

مثال على الطلب

{
  "page": 3,
  "page_size": 25,
  "total_items": 123
}

مثال على الاستجابة

{
  "task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
  "type": "dev.pagination_offset_calc",
  "status": "queued",
  "_links": {
    "result": "/tasks/tsk_…/result"
  }
}

الواجهة غير متزامنة: تستلم task_id فور الإرسال، ويمكنك الاستعلام عن الحالة بمعدل طلب واحد في الثانية.

الأسعار

لكل طلب$0.002

السعر معلن كما تراه: لا tokens ولا نظام نقاط؛ وإن فشلت المهمة فلن تُحاسَب عليها.

الأخطاء

HTTP	الرمز	المعنى
`401`	`unauthorized`	مفتاح الوصول مفقود أو غير صالح؛ تحقق من ترويسة Bearer في طلبك.
`402`	`insufficient_balance`	رصيدك لا يكفي لتنفيذ هذه المهمة؛ أعد شحن الرصيد ثم أعد المحاولة.
`404`	`unknown_type`	نوع المهمة المطلوب غير موجود في الكتالوج — راجع الاسم المرسل في الطلب.
`429`	`rate_limited`	تجاوزت الحد المسموح من الطلبات؛ انتظر قليلًا ثم أعد المحاولة.

اطّلع على توثيق KIT الكامل ←