1. ما هي المكتبة ولماذا تحتاجها؟

kotlinx-datetime هي مكتبة رسمية من JetBrains للتعامل مع التاريخ والوقت في نظام Kotlin البيئي. ميزتها الأساسية هي العمل عبر المنصات (Multiplatform): يمكنك استخدام نفس الكود على JVM، JS (في المتصفح و Node.js)، Native (iOS، macOS، Windows، Linux) و Wasm. هذا يريح المطورين من كتابة أكواد خاصة بكل منصة أو استخدام مكتبات مختلفة لأغراض مختلفة.

لماذا تحتاجها؟ المكتبة القياسية لـ Kotlin/JVM تستخدم java.time، وهي غير متوفرة على المنصات الأخرى. بالنسبة لـ Kotlin/Native و Kotlin/JS، كان عليك إما استخدام واجهات برمجة التطبيقات الخاصة بالمنصة (مثل NSDate، Date) أو إضافة مكتبات خارجية. kotlinx-datetime تحل هذه المشكلة بتوفير واجهة برمجة تطبيقات موحدة تعتمد على معيار ISO-8601. تتضمن المكتبة فئات لتمثيل اللحظات الزمنية (Instant)، التواريخ بدون وقت (LocalDate)، الوقت بدون تاريخ (LocalTime)، التاريخ مع الوقت (LocalDateTime)، المناطق الزمنية (TimeZone) والفترات الزمنية (DateTimePeriod).

المكتبة مثالية للمشاريع التي تستخدم Kotlin Multiplatform (KMP)، تطبيقات الخادم على Ktor، تطبيقات Android (كبديل لـ java.time)، وحتى للبرامج النصية والأدوات الطرفية. إنها خفيفة الوزن، ليس لها تبعيات خارجية، وتحظى بدعم نشط من المجتمع.

2. التثبيت

يتم توزيع المكتبة عبر Maven Central. لإضافتها، يجب إضافة التبعية إلى ملف build.gradle.kts (أو build.gradle). فيما يلي الكود الدقيق باستخدام Gradle Kotlin DSL.

// build.gradle.kts
repositories {
    mavenCentral()
}

dependencies {
    // المكتبة الأساسية
    implementation("org.jetbrains.kotlinx:kotlinx-datetime:0.6.1")

    // إذا كنت تستخدم مشروع متعدد المنصات، أضفها في commonMain:
    // commonMain.dependencies {
    //     implementation("org.jetbrains.kotlinx:kotlinx-datetime:0.6.1")
    // }
}

ملاحظة مهمة: الإصدار 0.6.1 هو آخر إصدار مستقر وقت كتابة هذا المقال. تحقق من أحدث إصدار على صفحة إصدارات GitHub. بالنسبة لـ Gradle Groovy DSL، الأمر مشابه ولكن بدون علامات اقتباس حول النصوص.

إذا كنت تستخدم Maven، أضف إلى ملف pom.xml:

<dependency>
    <groupId>org.jetbrains.kotlinx</groupId>
    <artifactId>kotlinx-datetime</artifactId>
    <version>0.6.1</version>
</dependency>

بالنسبة لـ Gradle Kotlin DSL في مشروع متعدد المنصات (KMP)، أضف في commonMain:

kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("org.jetbrains.kotlinx:kotlinx-datetime:0.6.1")
        }
    }
}

3. البداية السريعة

مثال عملي بسيط: إنشاء اللحظة الزمنية الحالية، تنسيقها، وطباعتها على الشاشة.

import kotlinx.datetime.*

fun main() {
    // الحصول على اللحظة الزمنية الحالية بالتوقيت العالمي (UTC)
    val now: Instant = Clock.System.now()
    println("اللحظة الحالية بالتوقيت العالمي: $now")

    // تحويلها إلى تاريخ ووقت محليين (باستخدام المنطقة الزمنية للنظام)
    val localDateTime: LocalDateTime = now.toLocalDa