إضافة Kotlin إلى تطبيق حالي

يوفّر "استوديو Android" دعمًا كاملاً للغة Kotlin، ما يتيح لك إضافة ملفات Kotlin إلى مشروعك الحالي وتحويل رمز لغة Java إلى Kotlin. يمكنك بعد ذلك استخدام جميع الأدوات الحالية في "استوديو Android" مع رمز Kotlin، بما في ذلك الإكمال التلقائي والتحقّق من الوبر وإعادة الضبط وتصحيح الأخطاء والمزيد.

إذا كنت تبدأ مشروعًا جديدًا وتريد استخدام Kotlin، يمكنك الاطّلاع على المقالة إنشاء مشروع.

للاطّلاع على النماذج، يمكنك مراجعة نماذج التعليمات البرمجية من Kotlin.

إضافة لغة Kotlin إلى مشروع حالي

لإضافة لغة Kotlin إلى مشروعك، عليك اتّباع الخطوات التالية:

1. انقر على ملف > جديد، واختر أحد نماذج Android المتنوعة، مثل جزء فارغ جديد، كما هو موضح في الشكل 1. إذا لم تظهر لك قائمة النماذج في هذه القائمة، افتح أولاً نافذة المشروع واختَر وحدة التطبيق.

   

   الشكل 1. اختَر من بين النماذج المتاحة، مثل جزء أو نشاط.

2. في المعالج الذي يظهر، اختر Kotlin لللغة المصدر. يوضّح الشكل 2 مربع الحوار نشاط جديد على Android عندما تريد إنشاء نشاط جديد.

   

   الشكل 2. مربّع حوار نشاط جديد على Android يمكنك من خلاله اختيار Kotlin كلغة المصدر.

3. تابع الخطوات عبر المعالج.

بدلاً من ذلك، يمكنك النقر على ملف > جديد > ملف/فئة Kotlin لإنشاء ملف Kotlin الأساسي. إذا لم يظهر لك هذا الخيار، افتح نافذة المشروع واختَر دليل JavaScript. تتيح لك نافذة ملف/فئة Kotlin الجديدة تحديد اسم الملف وتوفّر عدة خيارات لنوع الملف: الملف أو الفئة أو الواجهة أو فئة التعداد أو الكائن. يحدد اختيارك الأساسي عملية الإنشاء الأساسية التي تم إنشاؤها لك في ملف Kotlin الجديد. إذا اخترت Class، سينشئ "استوديو Android" ملف مصدر Kotlin الجديد مع الاسم المحدّد وتعريف فئة مطابق. إذا اخترت الواجهة، يتم تعريف الواجهة في الملف، وهكذا.

إذا كانت هذه هي المرة الأولى التي تضيف فيها فئة جديدة أو ملفًا جديدًا بلغة Kotlin إلى مشروعك مباشرةً (بدون استخدام نماذج Android)، يعرض "استوديو Android" تحذيرًا بأنّ لغة Kotlin لم يتم ضبطها في المشروع، كما هو موضّح في الشكل 3. اضبط Kotlin من خلال النقر على ضبط إمّا في أعلى يسار المحرّر أو في تنبيه سجلّ الأحداث الذي يظهر في أسفل يسار الصفحة.

الشكل 3. يعرض "استوديو Android" مربّع حوار تحذيري عندما لا يتم إعداد لغة Kotlin لمشروعك.

حدِّد خيار ضبط لغة Kotlin على جميع الوحدات التي تحتوي على ملفات Kotlin عندما يُطلب منك ذلك، كما هو موضّح في الشكل 4:

الشكل 4. يمكنك اختيار إعداد Kotlin لجميع الوحدات التي تحتوي على رمز Kotlin.

بعد النقر على حسنًا، سيضيف "استوديو Android" لغة Kotlin إلى مسار فئة مشروعك ويطبّق المكوِّن الإضافي Kotlin Android على كل وحدة تحتوي على ملفات Kotlin. من المفترض أن تبدو ملفات build.gradle مشابهة للأمثلة أدناه:

رائع

// Project build.gradle file.
buildscript {
    ext.kotlin_version = '1.4.10'
    ...
    dependencies {
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
    }
}

Kotlin

// Project build.gradle.kts file.
buildscript {
    extra["kotlin_version"] = "1.4.10"
    ...
    dependencies {
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version")
    }
}

رائع

// Inside each module using kotlin
plugins {
    ...
    id 'kotlin-android'
}

...

dependencies {
    implementation 'androidx.core:core-ktx:1.3.2'
    implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
}

Kotlin

// Inside each module using kotlin
plugins {
    ...
    kotlin("android")
}

...

val kotlin_version: String by rootProject.extra

dependencies {
    implementation("androidx.core:core-ktx:1.3.2")
    implementation("org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version")
}

المؤسسة المصدر

يتم تلقائيًا حفظ ملفات Kotlin الجديدة في "src/main/java/"، ما يسهّل الاطّلاع على ملفات Kotlin وJava في مكان واحد. وإذا كنت تفضّل فصل ملفات Kotlin عن ملفات Java، يمكنك وضع ملفات Kotlin ضمن القسم src/main/kotlin/ بدلاً من ذلك. في حال إجراء ذلك، عليك أيضًا تضمين هذا الدليل في إعدادات sourceSets، كما هو موضّح أدناه:

رائع

android {
    sourceSets {
        main.java.srcDirs += 'src/main/kotlin'
    }
}

Kotlin

android {
    sourceSets {
        getByName("main") {
            java.srcDir("src/main/kotlin")
        }
    }
}

تحويل رمز Java الحالي إلى رمز Kotlin

لتحويل رمز Java إلى لغة Kotlin، افتح ملف Java في "استوديو Android" واختَر الرمز > تحويل ملف Java إلى ملف Kotlin. ويمكنك بدلاً من ذلك إنشاء ملف جديد في لغة Kotlin (ملف > جديد > ملف/فئة Kotlin)، ثم لصق رمز Java في ذلك الملف. يعرض Android Studio بعد ذلك رسالة مطالبة ويعرض على المستخدم تحويل الرمز إلى لغة Kotlin، كما هو موضّح في الشكل 5. انقر على نعم للتحويل. ويمكنك اختياريًا وضع علامة في المربّع عدم عرض مربّع الحوار هذا في المرة القادمة، ما يجعل الإحالات الناجحة المستقبلية تلقائية.

الشكل 5. وبإمكان "استوديو Android" تحويل رمز Java إلى لغة Kotlin.

تحويل الرمز والقيمة الفارغة

تُنتج عملية التحويل في "استوديو Android" رمز Kotlin المكافئ من الناحية الوظيفية يتم فيه تجميع وتشغيله. مع ذلك، قد تحتاج إلى إجراء تحسينات إضافية على الرمز الذي تم تحويله. على سبيل المثال، قد ترغب في تحسين كيفية تعامل التعليمة البرمجية المحوَّلة مع الأنواع القابلة للقيم الفارغة.

في Android، من الشائع تأخير إعداد عناصر View والمكوّنات الأخرى إلى أن يصل الجزء أو النشاط المرتبط بها إلى حالة دورة الحياة المناسبة. على سبيل المثال، قد يكون لديك إشارة إلى زر في أحد الأجزاء، كما هو موضح في المقتطف التالي:

public class JavaFragment extends Fragment {

    // Null until onCreateView.
    private Button button;

    @Override
    public View onCreateView(@NonNull LayoutInflater inflater, ViewGroup container,
            Bundle savedInstanceState) {
        View root = inflater.inflate(R.layout.fragment_content, container,false);

        // Get a reference to the button in the view, only after the root view is inflated.
        button = root.findViewById(R.id.button);

        return root;
    }

    @Override
    public void onViewCreated(@NonNull View view, @Nullable Bundle savedInstanceState) {
        super.onViewCreated(view, savedInstanceState);

        // Not null at this point of time when onViewCreated runs
        button.setOnClickListener(new View.OnClickListener() {
            @Override
            public void onClick(View v) {
                ...
            }
        });
    }
}

على الرغم من أن متغير الزر قابل للقيم الفارغة، إلا أنه لجميع الأغراض العملية، لا ينبغي أن يكون فارغًا عند استخدامه في هذا المثال. ومع ذلك، نظرًا لعدم تحديد قيمته عند الإنشاء، يتعامل رمز Kotlin الذي تم إنشاؤه على أنّه Button نوع قابل للقيم الفارغة ويستخدم عامل تشغيل التأكيد غير الفارغ لإلغاء التفاف الزر عند إضافة أداة معالجة نقرات، كما هو موضّح أدناه:

class JavaFragment : Fragment() {

    // Null until onCreateView.
    private var button: Button? = null

    override fun onCreateView(inflater: LayoutInflater, container: ViewGroup?,
            savedInstanceState: Bundle?): View? {
        ...
        // Get a reference to the button in the view, only after the root view is inflated.
        button = root.findViewById(R.id.button)
        ...
    }

    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)

        // Not null at the point of time when onViewCreated fires 
        // but force unwrapped nonetheless
        button!!.setOnClickListener { }
    }
}

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

ملاحظة: لا يعني هذا المثال أنه عليك دائمًا تجنُّب الأنواع القابلة للقيم الفارغة. بشكل عام، ينطبق نمط استخدام lateinit هذا على المتغيّرات التي لا يُتوقّع أبدًا أن تكون null ولكن لا يمكن إعدادها حيث يتم تحديدها، كما هو الحال مع مراجع View داخل الجزء أو النشاط الذي تتوفّر فيه.

في حالات أخرى، حيث يكون null تعيين متغير صالح استنادًا إلى حالة الاستخدام لتطبيقك، فإن استخدام عامل تشغيل استدعاء آمن (?.) مع عامل تشغيل إنهاء elvis (?:) قد يكون وسيلة أكثر ملاءمة لإلغاء التفاف العنصر القابل للقيم الفارغة بأمان أو فرض قيمة تلقائية معقولة غير فارغة. لا تتوفّر لدى "استوديو Android" معلومات كافية لاتخاذ هذا القرار خلال عملية التحويل. وفي حين أن الإعداد التلقائي هو التأكيد غير الفارغ، يجب عليك المتابعة وضبط الرمز المحوّل حسب الحاجة.

مزيد من المعلومات

لمزيد من المعلومات حول استخدام رمزَي Kotlin وJava في مشروعك، يُرجى الاطّلاع على القسم استدعاء رمز Java من Kotlin.

لمزيد من المعلومات حول استخدام Kotlin في سيناريوهات المؤسسات، يُرجى الاطّلاع على استخدام Kotlin للفِرق الكبيرة.

للحصول على معلومات عن برامج تضمين Kotlin الاصطلاحية لواجهات برمجة تطبيقات Android الحالية، يمكنك الاطّلاع على Android KTX.