time-ar

أول مكتبة npm/cdn عربية مفتوحة المصدر بالشراكة مع الباشمهندس @محمود لعرض كم مضى & تبقى من الزمن مع التركيز على سلامة اللغة والنحو، مع الامكانية الكاملة فالتخصيص والتعديل.

النتيجة تكون هكذا:
• منذ ساعتين
• بعد 3 أيام
• الآن

التثبيت

باستخدام CDN ( للمواقع الثابتة ):

<script src="https://cdn.jsdelivr.net/gh/0xdya/timeAr@cdn/dist/script.js"></script>

باستخدام npm:

npm i time-ar

باستخدام pnpm:

pnpm add time-ar

باستخدام yarn:

yarn add time-ar

الاستخدام السريع

نسخة الـ CDN

تتميز بخاصية التشغيل التلقائي؛ حيث تبحث المكتبة فور تحميلها عن العناصر التي تحمل كلاس .time-arأو سمة data-date وتقوم بتحديثها كل 30 ثانية تلقائياً.

مثال (HTMl)

<span class="time-ar" data-date="2026-03-21T14:30:15">سيتم التحديث هنا</span>
        
<!-- يمكنك أيضًا استخدام الطريقة المختصرة وتعطي نفس النتيجة -->
<span class="time-ar">2026-03-21T14:30:15</span>

نسخة الـ npm

مثال TypeScript & JavaScript

import timeAr from "time-ar";

const t = timeAr();
const out = t.getTimeAr("21-03-2026 14:30:15", t.format.fullDateTime);
console.log(out); // "منذ ..."/"بعد ..."

واجهة المكتبة (API)

عند استدعاء timeAr() ستحصل على كائن يحتوي على:

• format: مجموعة تنسيقات جاهزة.
• getTimeAr(time, timeFormat): تحويل وقت/تاريخ إلى نص نسبي بالعربية.
• setTimezone(timezone): ضبط التايمزون الافتراضي الذي تُحسب بناءً عليه الفروقات الزمنية.

الدالة getTimeAr

التوقيع

getTimeAr(time: Date | string, timeFormat: string): string

ماذا تُرجع؟

• إذا كان الفرق أقل من 5 ثوانٍ: ترجع "الآن"
• إذا كان التاريخ في الماضي: تبدأ بـ "منذ"
• إذا كان التاريخ في المستقبل: تبدأ بـ "بعد"

ما هو timeFormat؟

هو التنسيق الذي سيتم الاعتماد عليه لفهم قيمة التاريخ والوقت عندما يكونان نصًا.

التنسيقات الجاهزة format

هادي جميع القيم المتاحة حاليًا:

إدخال الوقت كـ string (أمثلة عملية)

1) تاريخ كامل

import timeAr from "time-ar";

const t = timeAr();
console.log(t.getTimeAr("21-03-2026 14:30:15", t.format.fullDateTime));

2) تاريخ فقط

import timeAr from "time-ar";

const t = timeAr();
console.log(t.getTimeAr("21-03-2026", t.format.shortDate));

3) وقت فقط (HH:mm أو HH:mm:ss)

إذا مررت وقتًا فقط مثل "14:30" أو "14:30:15" فالمكتبة تعتبره وقت اليوم الحالي في التايمزون الحالي ثم تحسب الفرق مع الآن:

import timeAr from "time-ar";

const t = timeAr();
console.log(t.getTimeAr("14:30", t.format.shortTime));
console.log(t.getTimeAr("14:30:15", t.format.longTime));

ضبط المنطقة الزمنية (Timezone)

افتراضيًا، يتم اختيار التايمزون من نظام التشغيل. يمكنك تغييره عبر setTimezone:

import timeAr from "time-ar";

const t = timeAr();
t.setTimezone("Africa/Cairo");
// t.setTimezone("Africa/Algiers");
// t.setTimezone("Africa/....");

console.log(t.getTimeAr("21-03-2026 14:30:15", t.format.fullDateTime));

أخطاء متوقعة

• إذا كانت المنطقة الزمنية غير صحيحة، سترمي الدالة خطأ:
  file:///path/index.js:4 t.setTimezone("...");

ملاحظات ودقة الإخراج

• تحليل التنسيقات صارم: إذا لم تتطابق قيمة التاريخ النصية مع التنسيق الذي تم اختياره سيتم رمي خطأ مثل:
  Invalid Date: The provided date ... does not match the format ...
• الوحدات المدعومة: ثانية، دقيقة، ساعة، يوم، أسبوع، شهر، سنة.
• صياغة الجمع: يتم تطبيق صيغ عربية مختلفة (مفرد/مثنى/جمع حتى 10/مفرد منصوب بعد 10) مثل:
  منذ ساعة، منذ ساعتين، منذ 3 ساعات، منذ 11 ساعة

أسئلة شائعة

هل يدعم العرض بالانجليزية ؟

أكيد لا ._. ،سبب صنعنا لهاد المكتبة لتكون أول مكتبة عربية خام، تدعم النحو وليس ترجمة آلية.

هل أستطيع استخدام تنسيق غير الموجود ؟

نعم، يقبل أي تنسيق عبر:

console.log(t.getTimeAr("2026|03|21 14-30-15", "YYYY|MM|DD HH-mm-ss"));