إضافة معالجات التعليقات التوضيحية

تتضمن هذه الصفحة إرشادات مفصلة حول كيفية إضافة وتهيئة معالجات التعليقات التوضيحية كتبعيات للمشروع. لمزيد من المعلومات حول معالِجات التعليقات التوضيحية، يمكنك الاطّلاع على الإدخال في ضبط التبعيات.

إذا أضفت معالجات تعليقات توضيحية إلى مسار فئة التجميع، ستظهر لك رسالة خطأ مشابهة لما يلي:

Error: Annotation processors must be explicitly declared now.

لحل هذا الخطأ، أضِف معالجات التعليقات التوضيحية إلى مشروعك من خلال ضبط تبعيتك باستخدام annotationProcessor كما هو موضَّح أدناه:

Kotlin

dependencies {
    // Adds libraries defining annotations to only the compile classpath.
    compileOnly("com.google.dagger:dagger:version-number")
    // Adds the annotation processor dependency to the annotation processor classpath.
    annotationProcessor("com.google.dagger:dagger-compiler:version-number")
}

رائع

dependencies {
    // Adds libraries defining annotations to only the compile classpath.
    compileOnly 'com.google.dagger:dagger:version-number'
    // Adds the annotation processor dependency to the annotation processor classpath.
    annotationProcessor 'com.google.dagger:dagger-compiler:version-number'
}

ملاحظة: لم يعُد المكوّن الإضافي لنظام التشغيل Android لنظام Gradle 3.0.0 والإصدارات الأحدث متوافقًا مع المكوّن الإضافي android-apt.

تمرير الوسيطات إلى معالجات التعليقات التوضيحية

إذا كنت بحاجة إلى تمرير الوسيطات إلى معالج تعليقات توضيحية، يمكنك إجراء ذلك باستخدام الكتلة AnnotationProcessorOptions في إعداد تصميم الوحدة. على سبيل المثال، إذا كنت تريد تمرير أنواع البيانات الأولية كأزواج المفتاح/القيمة، يمكنك استخدام السمة argument، كما هو موضح أدناه:

Kotlin

android {
    ...
    defaultConfig {
        ...
        javaCompileOptions {
            annotationProcessorOptions {
                arguments += mapOf("key1" to "value1",
                                   "key2" to "value2")
            }
        }
    }
}

رائع

android {
    ...
    defaultConfig {
        ...
        javaCompileOptions {
            annotationProcessorOptions {
                argument 'key1', 'value1'
                argument 'key2', 'value2'
            }
        }
    }
}

ومع ذلك، عند استخدام الإصدار 3.2.0 من المكوّن الإضافي لنظام Gradle المتوافق مع Android والإصدارات الأحدث، عليك تمرير وسيطات المعالج التي تمثّل الملفات أو الأدلة باستخدام واجهة CommandLineArgumentProvider من Gradle.

يتيح لك استخدام CommandLineArgumentProvider أنت أو مؤلف معالج التعليقات التوضيحية تحسين دقة وأداء البنى النظيفة المتزايدة والمخزنة مؤقتًا من خلال تطبيق التعليقات التوضيحية بشأن نوع خاصية الإصدار التزايدي على كل وسيطة.

على سبيل المثال، تُنفذ الفئة أدناه CommandLineArgumentProvider وتضيف تعليقات توضيحية إلى كل وسيطة للمعالج.

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

Kotlin

class MyArgsProvider(
    // Annotates each directory as either an input or output for the
    // annotation processor.
    @get:InputFiles
    // Using this annotation helps Gradle determine which part of the file path
    // should be considered during up-to-date checks.
    @get:PathSensitive(PathSensitivity.RELATIVE)
    val inputDir: FileCollection,

    @get:OutputDirectory
    val outputDir: File
) : CommandLineArgumentProvider {
    // Specifies each directory as a command line argument for the processor.
    // The Android plugin uses this method to pass the arguments to the
    // annotation processor.

    override fun asArguments(): Iterable<String> {
        // Use the form '-Akey[=value]' to pass your options to the Java compiler.
        return listOf("-AinputDir=${inputDir.singleFile.absolutePath}",
                      "-AoutputDir=${outputDir.absolutePath}")
    }
}

android {...}

رائع

class MyArgsProvider implements CommandLineArgumentProvider {

    // Annotates each directory as either an input or output for the
    // annotation processor.
    @InputFiles
    // Using this annotation helps Gradle determine which part of the file path
    // should be considered during up-to-date checks.
    @PathSensitive(PathSensitivity.RELATIVE)
    FileCollection inputDir

    @OutputDirectory
    File outputDir

    // The class constructor sets the paths for the input and output directories.
    MyArgsProvider(FileCollection input, File output) {
        inputDir = input
        outputDir = output
    }

    // Specifies each directory as a command line argument for the processor.
    // The Android plugin uses this method to pass the arguments to the
    // annotation processor.
    @Override
    Iterable<String> asArguments() {
        // Use the form '-Akey[=value]' to pass your options to the Java compiler.
        ["-AinputDir=${inputDir.singleFile.absolutePath}",
         "-AoutputDir=${outputDir.absolutePath}"]
    }
}

android {...}

بعد تعريف فئة تنفّذ CommandLineArgumentProvider، عليك إنشاء مثيل وتمريره إلى مكوّن Android الإضافي باستخدام الطريقة annotationProcessorOptions.compilerArgumentProvider كما هو موضّح أدناه.

Kotlin

// This is in your module's build.gradle file.
android {
    defaultConfig {
        javaCompileOptions {
            annotationProcessorOptions {
                // Creates a new MyArgsProvider object, specifies the input and
                // output paths for the constructor, and passes the object
                // to the Android plugin.
                compilerArgumentProvider(MyArgsProvider(files("input/path"),
                                                          file("output/path")))
            }
        }
    }
}

رائع

// This is in your module's build.gradle file.
android {
    defaultConfig {
        javaCompileOptions {
            annotationProcessorOptions {
                // Creates a new MyArgsProvider object, specifies the input and
                // output paths for the constructor, and passes the object
                // to the Android plugin.
                compilerArgumentProvider new MyArgsProvider(files("input/path"),
                                         new File("output/path"))
            }
        }
    }
}

لمعرفة المزيد من المعلومات حول كيف يساعد تنفيذ CommandLineArgumentProvider في تحسين أداء الإصدار، يمكنك الاطّلاع على جارٍ التخزين في مشاريع Java في ذاكرة التخزين المؤقت.

إيقاف التحقق من أخطاء معالج التعليقات التوضيحية

إذا كانت لديك تبعيات على مسار فئة التجميع تتضمّن معالِجات تعليقات توضيحية لا تحتاج إليها، يمكنك إيقاف التحقق من الأخطاء من خلال إضافة ما يلي إلى ملف build.gradle.kts. ضع في اعتبارك أنه لا تتم إضافة معالِجات التعليقات التوضيحية التي تضيفها إلى مسار فئة التحويل البرمجي إلى مسار فئة المعالج.

Kotlin

android {
    ...
    defaultConfig {
        ...
        javaCompileOptions {
            annotationProcessorOptions {
                argument("includeCompileClasspath", "false")
            }
        }
    }
}

رائع

android {
    ...
    defaultConfig {
        ...
        javaCompileOptions {
            annotationProcessorOptions {
                includeCompileClasspath false
            }
        }
    }
}

إذا كنت تستخدم لغتَي Kotlin وkapt:

Kotlin

android {
    ...
    defaultConfig {
        ...
        kapt {
            includeCompileClasspath = false
        }
    }
}

رائع

android {
    ...
    defaultConfig {
        ...
        kapt {
            includeCompileClasspath false
        }
    }
}

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