新增註解處理工具

本頁提供詳細指南，說明如何新增及設定註解處理工具做為專案依附元件。如要進一步瞭解註解處理工具，請參閱「設定依附元件」中的項目。

假使您將註解處理工具新增至編譯的類別路徑，便會看到與下列內容類似的錯誤訊息：

Error: Annotation processors must be explicitly declared now.

如要解決此問題，請透過 annotationProcessor 設定依附元件，以將註解處理工具新增至專案，如下所示：

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

注意：Gradle 3.0.0 以上版本的 Android 外掛程式不再支援 android-apt 外掛程式。

將引數傳遞至註解處理工具

假使您需要將引數傳遞給註解處理工具，請使用模組建構設定中的 AnnotationProcessorOptions 區塊。舉例來說，假使您想要將原始資料類型當做鍵/值組合傳遞，可以使用 argument 屬性，如下所示：

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

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

然而，使用 Android Gradle 外掛程式 3.2.0 以上版本時，您需要傳遞代表使用 Gradle CommandLineArgumentProvider 介面的檔案或目錄的處理工具引數。

使用 CommandLineArgumentProvider 即可讓您或註解處理工具作者透過對每個引數套用增量建構屬性類型註解，以改善遞增和快取清理建構的正確性與效能。

舉例來說，下列類別會實作 CommandLineArgumentProvider，並為處理工具的每個引數加上註解。

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 的類別後，您必須建立執行個體，並使用 annotationProcessorOptions.compilerArgumentProvider 方法將其傳送至 Android 外掛程式，如下所示。

// 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 檔案中來停用錯誤檢查功能。請注意，您新增至編譯類別路徑的註解處理工具尚未新增至處理工具類別路徑。

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

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

假使您使用的是 Kotlin 和 kapt：

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

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

如果在將專案的註解處理工具遷移至處理工具類別路徑後遇到問題，您可以將 includeCompileClasspath 設為 true，藉此允許編譯類別路徑上的註解處理工具。然而，我們不建議將此屬性設為 true，並且該選項將在 Android 外掛程式的未來更新中移除。