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

نسبة السنة المنقضية

تعيد حاسبة التقدم السنوي هذه نسبة ما انقضى من السنة التقويمية وفق UTC عند تاريخ ووقت صريح بتنسيق ISO 8601.

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

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

تحوّل الوقت المرفق بالرمز Z أو بإزاحة رقمية إلى UTC، وتقيس العدد الدقيق للميلي ثانية منذ 1 يناير عند 00:00:00 UTC، ثم تقسمه على مدة سنة UTC الناتجة كاملة. تتكون السنة الكبيسة من 366 يوما، والعادية من 365 يوما. لا يؤثر التاريخ الحالي أو النطاق الزمني المحلي أو الشبكة أو العشوائية أو أي قيمة افتراضية خفية في النتيجة.

معنى نسبة السنة المنقضية

تمثل النسبة المعادة مقياسا متصلا للتقدم داخل سنة تقويمية واحدة وفق UTC. البسط هو عدد وحدات الميلي ثانية من 1 يناير عند 00:00:00.000 UTC حتى اللحظة المدخلة، والمقام هو عدد وحدات الميلي ثانية في سنة UTC كلها. تكون النتيجة صفرا تماما عند أول لحظة من 1 يناير، ثم تزداد على مدار السنة، لكنها تظل أقل من واحد لكل تاريخ ووقت صالحين داخل تلك السنة. أما الواحد فيقع عند أول لحظة من السنة التالية، وهي لحظة تنتمي بالفعل إلى السنة الجديدة، لذلك يبدأ الحساب فيها مجددا من الصفر. يختلف هذا التعريف عن نسبة تعتمد على ترتيب اليوم في السنة فتعد تواريخ كاملة أو تعتبر اليوم الحالي منقضيا بكامله. يضيف وقت الظهر نصف ذلك التاريخ، وتضيف الثواني حصتها الدقيقة، ويحتفظ الحساب بما يصل إلى ثلاث خانات من كسور الثانية بوصفها ميلي ثانية. يساوي المقام 365 يوما في السنة العادية و366 يوما في السنة الكبيسة وفق التقويم الغريغوري. ولأن الإزاحة تطبع قبل اختيار سنة UTC، فقد تنتمي لحظة مكتوبة في وقت متأخر من 31 ديسمبر ضمن نطاق آخر إلى 1 يناير من سنة UTC التالية على نحو صحيح.

كيفية إدخال تاريخ ووقت ISO بلا التباس

أرسل datetime بالصيغة YYYY-MM-DDTHH:mm:ssZ. ويمكنك إضافة خانة إلى ثلاث خانات كسرية للثانية، أو استبدال Z بإزاحة رقمية ذات إشارة مثل +05:30 أو -04:00. بيان النطاق الزمني إلزامي لأن التاريخ والوقت من دونه لا يحددان لحظة واحدة بعينها. ترفض الأداة التاريخ وحده، والصيغ المحلية، وأسماء الشهور، والمسافة بدلا من T، والإزاحة التي لا تحتوي على نقطتين، ولا تحاول تخمين المقصود. يتحقق المحلل كذلك من أطوال الشهور الغريغورية واليوم الكبيس والساعات والدقائق والثواني وحقول الإزاحة. لا تقبل الثواني الكبيسة؛ إذ تتراوح الثواني من 00 إلى 59 بما يوافق نموذج الدقيقة المدنية الحتمي المستخدم في الحساب. بعد التحليل، تطبق الإزاحة بحساب صحيح وتعرض اللحظة الناتجة في utc_datetime. كما تتضمن الاستجابة utc_year وelapsed_milliseconds وyear_milliseconds، كي تتمكن من تدقيق النسبة دون إعادة بناء قواعد التقويم. تنتج سلسلتان تصفان اللحظة نفسها بإزاحتين مختلفتين التاريخ المطبع نفسه والنسبة نفسها. تبلغ تكلفة الطلب المؤتمت الناجح $0.002، ويمكن أيضا إجراء الحساب محليا في المتصفح.

مواضع استخدام نسبة سنوية حتمية

استخدم هذه القدرة عندما يحتاج نموذج أو رسم مرئي أو تقرير أو اختبار إلى موضع ثابت داخل السنة التقويمية، بدلا من إجابة ترتبط بوقت تشغيل الجهاز. تستطيع لوحات المعلومات تحويل النسبة إلى قيمة مئوية أو شريط تقدم مع الاحتفاظ بالبسط والمقام الدقيقين للتسميات والتدقيق. ويمكن لمسارات معالجة البيانات إثراء السجلات ذات الطابع الزمني بإحداثي سنوي مطبع للتحليل الموسمي أو الاستيفاء أو السمات الدورية، مع ضمان مقارنة المدخلات ذات الإزاحات على خط UTC الزمني نفسه. وتستطيع الاختبارات تثبيت حالات الحدود عند رأس السنة أو اليوم الكبيس أو آخر ميلي ثانية من ديسمبر من دون محاكاة ساعة. تعتمد النتيجة على المدة المنقضية، ولذلك لا تصلح لعد التواريخ المكتملة أو أيام العمل أو الفترات المالية أو الشهور المفترضة متساوية الطول. كما تمثل أيام UTC المدنية عمدا بوصفها 86,400 ثانية ولا تضيف الثواني الكبيسة، مما يجعل العملية قابلة للنقل وإعادة الإنتاج. إذا احتجت إلى نسبة مئوية، فاضرب fraction في مئة ولا تقرب إلا عند العرض. أما نسبة السنة المالية فتتطلب حدود التقويم المالي المعني بدلا من إعادة تسمية هذه النتيجة.

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

لوحات التقدم السنوي

حوّل طابعا زمنيا صريحا إلى موضع دقيق من صفر إلى واحد داخل سنة UTC لاستخدامه في أشرطة التقدم ومؤشرات KPI.

سمات التحليل الموسمي

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

اختبارات حتمية للحدود

أنشئ بيانات اختبار قابلة لإعادة الإنتاج حول رأس السنة واليوم الكبيس من دون قراءة ساعة النظام أو محاكاتها.

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

هل يمكن أن تساوي النسبة واحدا؟

لا، بالنسبة إلى لحظة داخل سنة UTC المختارة. تنتمي أول لحظة من السنة التالية إلى السنة الجديدة وتعيد صفرا.

كيف يعالج الحساب السنوات الكبيسة؟

يستخدم المقام 366 يوما إذا كانت سنة UTC تقبل القسمة على أربعة، باستثناء السنوات المئوية التي لا تقبل القسمة على أربعمئة؛ وإلا فيستخدم 365 يوما.

لماذا يجب تحديد النطاق الزمني؟

لأن تاريخ ووقت ISO المحليين من دون Z أو إزاحة رقمية لا يحددان لحظة UTC واحدة، وقد ينتجان إجابات مختلفة باختلاف البيئة.

هل يشمل الحساب الثواني الكبيسة؟

لا. يستخدم أياما مدنية ثابتة من 86,400 ثانية، ويقبل الثواني من 00 إلى 59، لتقديم نسبة تقويمية حتمية قابلة للنقل.

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

تبلغ تكلفة حساب API الناجح $0.002 لكل طلب. وتتوفر العملية الحتمية نفسها أيضا في المتصفح.

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

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

الـEndpoint

POSThttps://api.kit.forhosting.com/date/fraction-of-year-elapsed

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

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

curl -X POST https://api.kit.forhosting.com/date/fraction-of-year-elapsed \
  -H "Authorization: Bearer $KIT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"datetime":"2026-07-02T12:00:00Z"}'

const res = await fetch("https://api.kit.forhosting.com/date/fraction-of-year-elapsed", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.KIT_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "datetime": "2026-07-02T12:00:00Z"
  })
});
const { task_id } = await res.json();

import os, requests

res = requests.post(
    "https://api.kit.forhosting.com/date/fraction-of-year-elapsed",
    headers={"Authorization": f"Bearer {os.environ['KIT_KEY']}"},
    json={
    "datetime": "2026-07-02T12:00:00Z"
},
)
task_id = res.json()["task_id"]

<?php
$res = file_get_contents("https://api.kit.forhosting.com/date/fraction-of-year-elapsed", false, stream_context_create([
  "http" => [
    "method"  => "POST",
    "header"  => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
    "content" => '{"datetime":"2026-07-02T12:00:00Z"}',
  ],
]));
$task = json_decode($res, true);

body := bytes.NewBufferString(`{"datetime":"2026-07-02T12:00:00Z"}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/date/fraction-of-year-elapsed", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)

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

{
  "datetime": "2026-07-02T12:00:00Z"
}

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

{
  "task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
  "type": "date.fraction_of_year_elapsed",
  "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 الكامل ←