預編譯腳本外掛程式通常是 Kotlin 腳本，該腳本已編譯並作為 Java 類別檔案分發在程式庫中。這些腳本旨在作為二進制 Gradle 外掛程式使用，建議用作慣例外掛程式。

慣例外掛程式是一種外掛程式，通常使用您自己的慣例（即預設值）配置現有的核心和社群外掛程式，例如透過使用 java.toolchain.languageVersion = JavaLanguageVersion.of(17) 設定 Java 版本。慣例外掛程式也用於強制執行專案標準並幫助簡化建置流程。它們可以套用和配置外掛程式、建立新任務和擴充功能、設定相依性等等。

設定外掛程式 ID

預編譯腳本的外掛程式 ID 從其檔案名稱和可選的套件宣告中衍生而來。

例如，位於 src/main/groovy（或 src/main/kotlin）中且沒有套件宣告的 名為 code-quality.gradle(.kts) 的腳本將作為 code-quality 外掛程式公開

buildSrc/build.gradle.kts
plugins {
    `kotlin-dsl`
}
app/build.gradle.kts
plugins {
    id("code-quality")
}
buildSrc/build.gradle
plugins {
    id 'groovy-gradle-plugin'
}
app/build.gradle
plugins {
    id 'code-quality'
}

另一方面，位於 src/main/kotlin/my 中且具有套件宣告 my 的名為 code-quality.gradle.kts 的腳本將作為 my.code-quality 外掛程式公開

buildSrc/build.gradle.kts
plugins {
    `kotlin-dsl`
}
app/build.gradle.kts
plugins {
    id("my.code-quality")
}
Groovy 預編譯腳本外掛程式不能有套件。

使用擴充功能使外掛程式可配置

擴充功能物件通常在外掛程式中使用，以公開配置選項和額外功能給建置腳本。

當您套用定義擴充功能的外掛程式時，您可以存取擴充功能物件並配置其屬性或呼叫其方法，以自訂外掛程式或外掛程式提供的任務的行為。

Project 具有關聯的 ExtensionContainer 物件，其中包含已套用於專案的外掛程式的所有設定和屬性。您可以透過將擴充功能物件新增至此容器來為您的外掛程式提供配置。

讓我們更新我們的 greetings 範例

buildSrc/src/main/kotlin/greetings.gradle.kts
// Create extension object
interface GreetingPluginExtension {
    val message: Property<String>
}

// Add the 'greeting' extension object to project
val extension = project.extensions.create<GreetingPluginExtension>("greeting")
buildSrc/src/main/groovy/greetings.gradle
// Create extension object
interface GreetingPluginExtension {
    Property<String> getMessage()
}

// Add the 'greeting' extension object to project
def extension = project.extensions.create("greeting", GreetingPluginExtension)

您可以使用 extension.message.set("Hi from Gradle,") 直接設定 message 屬性的值。

但是，GreetingPluginExtension 物件會以與擴充功能物件相同的名稱作為專案屬性提供。您現在可以像這樣存取 message

buildSrc/src/main/kotlin/greetings.gradle.kts
// Where the<GreetingPluginExtension>() is equivalent to project.extensions.getByType(GreetingPluginExtension::class.java)
the<GreetingPluginExtension>().message.set("Hi from Gradle")
buildSrc/src/main/groovy/greetings.gradle
extensions.findByType(GreetingPluginExtension).message.set("Hi from Gradle")

如果您套用 greetings 外掛程式，您可以在您的建置腳本中設定慣例

app/build.gradle.kts
plugins {
    application
    id("greetings")
}

greeting {
    message = "Hello from Gradle"
}
app/build.gradle
plugins {
    id 'application'
    id('greetings')
}

configure(greeting) {
    message = "Hello from Gradle"
}

新增預設配置作為慣例

在外掛程式中，您可以使用 project 物件定義預設值，也稱為慣例。

慣例屬性是使用預設值初始化的屬性，但可以被覆寫

buildSrc/src/main/kotlin/greetings.gradle.kts
// Create extension object
interface GreetingPluginExtension {
    val message: Property<String>
}

// Add the 'greeting' extension object to project
val extension = project.extensions.create<GreetingPluginExtension>("greeting")

// Set a default value for 'message'
extension.message.convention("Hello from Gradle")
buildSrc/src/main/groovy/greetings.gradle
// Create extension object
interface GreetingPluginExtension {
    Property<String> getMessage()
}

// Add the 'greeting' extension object to project
def extension = project.extensions.create("greeting", GreetingPluginExtension)

// Set a default value for 'message'
extension.message.convention("Hello from Gradle")

extension.message.convention(…​) 為擴充功能的 message 屬性設定慣例。此慣例指定 message 的值應預設為 "Hello from Gradle"。

如果未明確設定 message 屬性，則其值將自動設定為 "Hello from Gradle"。

將擴充功能屬性對應至任務屬性

在外掛程式中，使用擴充功能並將其對應至自訂任務的輸入/輸出屬性是很常見的。

在此範例中，GreetingPluginExtension 的 message 屬性會對應至 GreetingTask 的 message 屬性作為輸入

buildSrc/src/main/kotlin/greetings.gradle.kts
// Create extension object
interface GreetingPluginExtension {
    val message: Property<String>
}

// Add the 'greeting' extension object to project
val extension = project.extensions.create<GreetingPluginExtension>("greeting")

// Set a default value for 'message'
extension.message.convention("Hello from Gradle")

// Create a greeting task
abstract class GreetingTask : DefaultTask() {
    @Input
    val message = project.objects.property<String>()

    @TaskAction
    fun greet() {
        println("Message: ${message.get()}")
    }
}

// Register the task and set the convention
tasks.register<GreetingTask>("hello") {
    message.convention(extension.message)
}
buildSrc/src/main/groovy/greetings.gradle
// Create extension object
interface GreetingPluginExtension {
    Property<String> getMessage()
}

// Add the 'greeting' extension object to project
def extension = project.extensions.create("greeting", GreetingPluginExtension)

// Set a default value for 'message'
extension.message.convention("Hello from Gradle")

// Create a greeting task
abstract class GreetingTask extends DefaultTask {
    @Input
    abstract Property<String> getMessage()

    @TaskAction
    void greet() {
        println("Message: ${message.get()}")
    }
}

// Register the task and set the convention
tasks.register("hello", GreetingTask) {
    message.convention(extension.message)
}
$ gradle -q hello
Message: Hello from Gradle

這表示對擴充功能的 message 屬性所做的變更將觸發任務被視為過時，從而確保使用新訊息重新執行任務。

您可以在延遲配置中找到更多關於您可以在任務實作和擴充功能中使用的類型資訊。

套用外部外掛程式

為了在預編譯腳本外掛程式中套用外部外掛程式，必須將其新增至外掛程式專案的實作類別路徑中的外掛程式建置檔案中

buildSrc/build.gradle.kts
plugins {
    `kotlin-dsl`
}

repositories {
    mavenCentral()
}

dependencies {
    implementation("com.bmuschko:gradle-docker-plugin:6.4.0")
}
buildSrc/build.gradle
plugins {
    id 'groovy-gradle-plugin'
}

repositories {
    mavenCentral()
}

dependencies {
    implementation 'com.bmuschko:gradle-docker-plugin:6.4.0'
}

然後可以在預編譯腳本外掛程式中套用它

buildSrc/src/main/kotlin/my-plugin.gradle.kts
plugins {
    id("com.bmuschko.docker-remote-api")
}
buildSrc/src/main/groovy/my-plugin.gradle
plugins {
    id 'com.bmuschko.docker-remote-api'
}

在這種情況下，外掛程式版本是在相依性宣告中定義的。