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

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

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

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'
}

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

إذا كنت بحاجة إلى تمرير وسيطات إلى معالج تعليقات توضيحية، يمكنك إجراء ذلك باستخدام مجموعة 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'
            }
        }
    }
}

ومع ذلك، عند استخدام المكوّن الإضافي لنظام Gradle المتوافق مع Android‏ 3.2.0 والإصدارات الأحدث، عليك تمرير وسيطات المعالج التي تمثّل الملفات أو الأدلة باستخدام واجهة 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 path
    // to consider 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 path
    // to consider 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.