實作預先編譯的腳本外掛

預編譯腳本外掛通常是已編譯並以封裝在函式庫中的 Java 類別檔案形式發行的 Kotlin 腳本。這些腳本旨在作為二進位 Gradle 外掛使用，建議用作慣例外掛。

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

設定外掛 ID

預編譯腳本的外掛 ID 是根據其檔名和選用的套件宣告衍生而來。

例如，一個名為 code-quality.gradle(.kts) 的腳本位於 src/main/groovy（或 src/main/kotlin）中，且沒有套件宣告，將會顯示為 code-quality 外掛

plugins {
    id("code-quality")
}

另一方面，一個名為 code-quality.gradle(.kts) 的腳本位於 src/main/groovy/my（或 src/main/kotlin/my）中，且套件宣告為 my，將會顯示為 my.code-quality 外掛

plugins {
    id("my.code-quality")
}

使用檔案

您應該使用 Gradle 的管理屬性。這將啟用延遲配置，以便只有在需要檔案時才會解析實際位置，且可以在建置組態期間隨時重新組態。

讓我們從建立名為 greetings 的慣例外掛開始

buildSrc/src/main/kotlin/greetings.gradle.kts

// Create extension object
interface GreetingPluginExtension {
    val message: Property<String>
}

buildSrc/src/main/groovy/greetings.gradle

// Create extension object
interface GreetingPluginExtension {
    Property<String> getMessage()
}

您可以在使用檔案中找到有關延遲使用檔案的更多資訊。

使用擴充功能讓外掛可組態

擴充功能物件 通常用於外掛中，以公開組態選項和額外的功能來建置指令碼。

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

專案有關聯的 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 的值應預設為位於專案建置目錄中的名為 defaultGreeting.txt 檔案的內容。

如果未明確設定 message 屬性，其值將自動設定為 defaultGreeting.txt 的內容。

將擴充功能屬性對應至工作屬性

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

在此範例中，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'
}

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

此頁面有幫助嗎？