compileSdkVersion: الأساسيات، واجهات برمجة التطبيقات الجديدة والإعداد في Gradle

ما هو compileSdkVersion في Android؟

compileSdkVersion هو معامل صحيح في build.gradle يحدد إصدار Android SDK الذي سيتم التجميع ضده. عندما تكتب كودًا يستخدم فئات من android.* أو androidx.*، يتحقق المترجم منها مقابل واجهات برمجة التطبيقات المتاحة في إصدار compileSdk المحدد. إذا تم تقديم طريقة في API 36 وكان compileSdk = 35، فلن يتم تجميع الكود. إذا كان compileSdk = 36، فسيتم تجميع الكود، لكن استدعاء تلك الطريقة على جهاز مع API 35 بدون فحص سيؤدي إلى تعطل.

يتم تحميل compileSdkVersion من منصة Android SDK المثبتة عبر SDK Manager في Android Studio. كل مستوى API له منصته الخاصة: android-21، android-29، android-34، android-35، android-36. تحتوي المنصة على android.jar — مجموعة من الفئات والطرق والثوابت التي يستخدمها مترجم Kotlin/Java. إذا لم يتم تثبيت المنصة، سيقوم Gradle بتنزيلها تلقائيًا عبر sdkmanager في أول بناء.

AGP (Android Gradle Plugin) الإصدار 8.7+ يُوصي بتحديد compileSdk كعدد صحيح عبر compileSdk = 36 في Kotlin DSL، بدون البادئة android-. يمكن أيضًا تعيين compileSdk عبر compileSdkVersion 36 في Groovy DSL أو compileSdkPreview للإصدارات الأولية من SDK (المعاينات المطورة). يُستخدم compileSdkPreview لاختبار مستويات API القادمة قبل الإصدار الرسمي.

// build.gradle.kts — إعداد compileSdkVersion
android {
    namespace = "com.example.myapp"

    // compileSdk = 36 — أحدث مستوى API مستقر (Android 16)
    compileSdk = 36

    defaultConfig {
        applicationId = "com.example.myapp"
        minSdk = 26
        targetSdk = 36
        versionCode = 1
        versionName = "1.0.0"
    }
}

// بديل: compileSdkPreview للإصدارات الأولية
// compileSdkPreview = "Baklava"

في المثال، compileSdk = 36 يوفر الوصول إلى جميع واجهات برمجة التطبيقات لنظام Android 16 (Baklava). يجب تثبيت منصة Android SDK 36 في SDK Manager. يمكن استخدام compileSdkPreview بالاسم "Baklava" لاختبار واجهات برمجة التطبيقات غير المستقرة قبل الإصدار الرسمي للمنصة. بعد الإصدار، يتم استبدال المعاينة بـ compileSdk = 36 المستقر.

compileSdkVersion مقابل targetSdkVersion مقابل minSdkVersion

ثلاثة معاملات لمستوى API في build.gradle — compileSdkVersion و targetSdkVersion و minSdkVersion — غالبًا ما يتم الخلط بينها. كل منها مسؤول عن جانب مختلف من التوافق، ويجب أن تتبع قيمها القاعدة compileSdk >= targetSdk >= minSdk. minSdk هو الحد الأدنى: الأجهزة الأقل منه لن ترى التطبيق. targetSdk هي نقطة الاختبار: يتم تمكين تغييرات السلوك حتى هذا المستوى. compileSdk هو السقف: واجهات برمجة التطبيقات فوق هذا المستوى غير متاحة للمترجم.

قاعدة عملية رئيسية: compileSdk يمكن زيادته دون أي اختبار على الأجهزة. هذه عملية آمنة توفر للمترجم ببساطة إصدارًا جديدًا من android.jar. الخطر الوحيد هو واجهات برمجة التطبيقات القديمة التي قد تتم إزالتها في إصدار المنصة الجديد، ولكن يتم اكتشاف ذلك في وقت التجميع وإصلاحه بسهولة. زيادة targetSdk، من ناحية أخرى، تتطلب دورة كاملة لضمان الجودة.

لماذا يمكن أن يكون compileSdk أعلى من targetSdk؟ تخيل أنه تم إصدار Android 16 (API 36) مع واجهات برمجة تطبيقات جديدة تريد استخدامها في الكود، لكنك لم تختبر تغييرات السلوك لـ API 36 بعد. تقوم بتعيين compileSdk = 36 (واجهات برمجة التطبيقات الجديدة متاحة)، targetSdk = 35 (تغييرات السلوك لـ API 36 معطلة). سيتم تجميع الكود، وسيستخدم طرقًا جديدة تحت فحوصات SDK_INT، ولن تؤدي تغييرات السلوك لـ API 36 إلى كسر التطبيق لأن targetSdk = 35.

أمثلة على التركيبات الصحيحة

compileSdk = 36، targetSdk = 36، minSdk = 26 — توافق كامل مع أحدث واجهات برمجة التطبيقات وتغييرات السلوك، تغطي 85% من الأجهزة. compileSdk = 36، targetSdk = 34، minSdk = 26 — واجهات برمجة التطبيقات الجديدة متاحة، تغييرات السلوك فقط حتى API 34. compileSdk = 35، targetSdk = 36 — غير صحيح: compileSdk أقل من targetSdk، API 36 غير متاحة بينما تغييرات السلوك لـ 36 نشطة.

كيفية تحديث compileSdkVersion: دليل خطوة بخطوة

تحديث compileSdkVersion هي واحدة من أبسط وأكثر العمليات أمانًا في مشروع Android. على عكس targetSdk، لا تتطلب اختبارًا مكثفًا لتغييرات السلوك. ومع ذلك، هناك بعض الخطوات التي يجب اتباعها لتجنب أخطاء التجميع وتحذيرات الإهمال.

الخطوة 1 — قم بتثبيت المنصة الجديدة عبر SDK Manager في Android Studio: Tools → SDK Manager → SDK Platforms → اختر مستوى API الجديد. إذا لم تقم بتثبيت المنصة، سيحاول Gradle تنزيلها تلقائيًا، لكن هذا قد يبطئ البناء الأول. الخطوة 2 — قم بتغيير compileSdk في build.gradle إلى القيمة الجديدة. الخطوة 3 — قم بالبناء (Build → Make Project) وأصلح أي أخطاء تجميع.

الخطوة 4 — تحقق من واجهات برمجة التطبيقات القديمة. بعد رفع compileSdk، قد يتم وضع علامة @Deprecated على بعض الطرق مع ملاحظة "removed in API X". يقوم Android Studio بتمييزها بخط يتوسطها ويعرض تحذيرًا. استبدل الاستدعاءات القديمة ببدائل جديدة. إذا كان البديل يتطلب مستوى API أعلى من minSdk، أضف فحصًا في وقت التشغيل. الخطوة 5 — تحقق من التبعيات: قد تتطلب بعض المكتبات إصدارًا معينًا من compileSdk. AGP 8.7+ يُوصي بـ compileSdk = 36.

// بعد رفع compileSdk: استبدال واجهات برمجة التطبيقات القديمة
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.os.Process
import android.app.ActivityManager

class CompileSdkMigration {

    // قبل: طريقة قديمة (قد تتم إزالتها في API الجديد)
    @Suppress("DEPRECATION")
    fun getMemoryClassOld(context: android.content.Context): Int {
        val am = context.getSystemService(
            android.content.Context.ACTIVITY_SERVICE
        ) as ActivityManager
        return am.memoryClass  // قد تصبح قديمة في API 36
    }

    // بعد: بديل جديد (إذا كان متاحًا)
    fun getMemoryClassNew(context: android.content.Context): Int {
        if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // واجهة برمجة تطبيقات جديدة من compileSdk 36
            val am = context.getSystemService(
                android.content.Context.ACTIVITY_SERVICE
            ) as ActivityManager
            return am.getMemoryClassSafe()  // مثال لواجهة برمجة تطبيقات جديدة
        }
        @Suppress("DEPRECATION")
        return context.getSystemService(
            android.content.Context.ACTIVITY_SERVICE
        ) as ActivityManager
            .memoryClass
    }
}

الفئة CompileSdkMigration تظهر نمط الترحيل الصحيح. قد تتم إزالة الطريقة القديمة memoryClass في API الجديد — سيعرض المترجم خطأ. البديل الجديد getMemoryClassSafe متاح فقط على API 36+، لذلك يتم استدعاؤه تحت فحص SDK_INT >= BAKLAVA. للأجهزة القديمة، يتم استخدام الرجوع مع @Suppress("DEPRECATION").

العمل مع واجهات برمجة التطبيقات الجديدة: الفحوصات الشرطية والرجوع

واجهات برمجة التطبيقات الجديدة المتاحة بفضل رفع compileSdkVersion لا يمكن استدعاؤها مباشرة إذا كان minSdkVersion أقل من ذلك المستوى. بدون فحص في وقت التشغيل، سيتعطل التطبيق مع AbstractMethodError أو NoSuchMethodError أو VerifyError على الأجهزة القديمة. آلية الحماية الرئيسية هي التحقق من Build.VERSION.SDK_INT، واستدعاء API الجديد فقط عندما يكون مستوى API كافيًا، وتوفير رجوع للإصدارات القديمة.

AndroidX يوفر إصدارات خلفية للعديد من واجهات برمجة التطبيقات الجديدة، مما يسمح باستخدام طرق حديثة حتى مع compileSdk منخفض. على سبيل المثال، Activity Result API من androidx.activity:activity-ktx:1.9.3 تعمل على جميع إصدارات Android بدءًا من API 14. NotificationCompat من AndroidX يتيح إشعارات حديثة على واجهات برمجة التطبيقات القديمة. PhotoPicker متاح عبر ActivityResultContracts.PickVisualMedia بدءًا من API 34+.

// استدعاء آمن لواجهة برمجة تطبيقات جديدة مع compileSdk 36 و minSdk 26
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.graphics.Color

class NewApiHelper {

    // API 36+: طريقة جديدة للعمل مع اللون
    fun formatColor(colorInt: Int): String {
        if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // واجهة برمجة تطبيقات جديدة من compileSdk 36 — تتطلب API 36+
            return Color.toArgbHexString(colorInt)
        }
        // رجوع: تنسيق يدوي لواجهات برمجة التطبيقات القديمة
        return String.format(
            "#%08X", (0xFFFFFFFF toLong() and colorInt.toLong())
        )
    }

    // AndroidX: لا حاجة لإصدار خلفي — فحص SDK_INT
    fun isEdgeToEdgeAvailable(): Boolean {
        return VERSION.SDK_INT >= VERSION_CODES.VANILLA_ICE_CREAM
    }
}

// الاستخدام في Activity
class ColorActivity : android.app.Activity() {
    override fun onCreate(savedInstanceState: android.os.Bundle?) {
        super.onCreate(savedInstanceState)
        val helper = NewApiHelper()
        val colorStr = helper.formatColor(0xFF6200EE)
        println("Color: $colorStr")
    }
}

الفئة NewApiHelper توضح الاستدعاء الآمن لواجهة برمجة التطبيقات الجديدة Color.toArgbHexString (API 36 افتراضية) مع تنسيق رجوع للإصدارات القديمة. المبدأ الرئيسي: compileSdk يعطي الوصول لاستدعاء طرق جديدة في الكود، لكن فحص SDK_INT في وقت التشغيل يحمي من الأعطال على الأجهزة القديمة. بدون فحص SDK_INT، تطبيق مع minSdk 26 و compileSdk 36 سيتعطل على Android 8-15.

AGP (Android Gradle Plugin) و compileSdkVersion

Android Gradle Plugin (AGP) هو أداة البناء الرئيسية لتطبيقات Android. كل إصدار من AGP يدعم نطاقًا معينًا من compileSdkVersion. AGP 8.7.x (الذي تم إصداره في 2026) يتطلب compileSdk >= 34 ويُوصي بـ compileSdk = 36. AGP 8.5.x يدعم compileSdk 33-35. إذا كان compileSdk أقل من الحد الأدنى لـ AGP، سيفشل البناء مع الخطأ: "The SDK platform (X) is not supported by this version of the Android Gradle Plugin".

NDK (Native Development Kit) مرتبط أيضًا بـ compileSdkVersion. إذا كان مشروعك يستخدم كودًا أصليًا بلغة C/C++ عبر NDK، فإن compileSdk يحدد إصدار ملفات الرأس والمكتبات. NDK r27+ يُوصي بـ compileSdk 36. للمكتبات ذات ملفات .so، يؤثر compileSdk على الحد الأدنى لمستوى API للكود الأصلي عبر APP_MIN_SDK_VERSION في Application.mk.

Gradle (7.6+) و Kotlin (2.0+) يؤثران أيضًا على توافق compileSdk. AGP 8.7+ يتطلب Gradle 8.9+ و Kotlin 2.0+. عند رفع compileSdk، يُوصى بتحديث AGP و Gradle و Kotlin إلى أحدث الإصدارات المستقرة. تحقق من التوافق في جدول توافق Android Gradle Plugin الرسمي.

المشكلات الشائعة عند رفع compileSdk

المشكلات عند رفع compileSdkVersion تنقسم إلى ثلاث فئات: أخطاء التجميع، تحذيرات الإهمال، وعدم التوافق في وقت التشغيل. أخطاء التجميع — تتم إزالة الطرق من واجهة برمجة التطبيقات ولا يتم تجميع الكود. تحذيرات الإهمال — الطرق موسومة بـ @Deprecated، يتم تجميع الكود مع تحذيرات. عدم التوافق في وقت التشغيل — واجهات برمجة التطبيقات الجديدة مطلوبة لوظائف معينة وتسبب أخطاء إذا كان مستوى API على الجهاز غير كافٍ.

المشكلة الأولى الشائعة — "Cannot resolve symbol X". هذا يعني أنه تمت إزالة فئة أو طريقة من واجهة برمجة التطبيقات العامة في إصدار SDK الجديد. الحل: ابحث عن بديل في المنصة الجديدة أو استخدم مكافئًا من AndroidX. على سبيل المثال، فئة AsyncTaskLoader تم إهمالها في API 28 وإزالتها من واجهة برمجة التطبيقات العامة في الإصدارات الأحدث. البدائل تشمل Kotlin Coroutines أو WorkManager.

المشكلة الثانية — تغيير توقيع الطريقة. في إصدار API الجديد، قد تغير الطريقة عدد أو أنواع معاملاتها. يعرض مترجم Kotlin/Java خطأ: "None of the following functions can be called with the arguments supplied". الحل: قم بتحديث استدعاء الطريقة ليتوافق مع التوقيع الجديد أو أضف فحص SDK_INT مع استدعاء التوقيع القديم للأجهزة القديمة.

// حل المشكلات عند رفع compileSdk
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.content.pm.PackageManager

class CompileSdkProblemFixer {

    // مشكلة: الطريقة hasSystemFeature غيرت التوقيع في API 36
    fun hasCamera(pm: PackageManager): Boolean {
        return if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // التوقيع الجديد: hasSystemFeature(String, FeatureType)
            pm.hasSystemFeature(
                PackageManager.FEATURE_CAMERA,
                PackageManager.FEATURE_TYPE_BACK
            )
        } else {
            // التوقيع القديم: hasSystemFeature(String)
            @Suppress("DEPRECATION")
            pm.hasSystemFeature(PackageManager.FEATURE_CAMERA)
        }
    }

    // مشكلة: فئة محذوفة، استخدم مكافئ AndroidX
    fun loadFragment(manager: androidx.fragment.app.FragmentManager) {
        // بدلاً من android.app.FragmentManager (محذوف) استخدم
        // androidx.fragment.app.FragmentManager
        val fragment = CustomFragment()
        manager.beginTransaction()
            .replace(android.R.id.content, fragment)
            .commit()
    }
}

الفئة CompileSdkProblemFixer تحل المشكلات الشائعة: التوقيع المتغير لـ hasSystemFeature (تغيير افتراضي في API 36) يتم التعامل معه عبر فحص SDK_INT لاستدعاء الإصدار الصحيح من الطريقة. الفئة المحذوفة android.app.FragmentManager يتم استبدالها بمكافئها من AndroidX. للاستدعاءات القديمة حيث لا يوجد بديل، يتم استخدام @Suppress("DEPRECATION") مع تعليق يوضح سبب الاحتفاظ بها.