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

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

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

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")
}

Groovy

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")
            }
        }
    }
}

Groovy

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

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

إنّ استخدام 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 {...}

Groovy

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")))
            }
        }
    }
}

Groovy

// 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")
            }
        }
    }
}

Groovy

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

في حال استخدام Kotlin وkapt:

Kotlin

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

Groovy

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

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