IDEA 外掛程式 - Gradle 繁體中文

IDEA 外掛與設定快取不相容。

IDEA 外掛會產生 IntelliJ IDEA 使用的檔案，因此可以從 IDEA 開啟專案（檔案 - 開啟專案）。外部依賴項（包括相關的原始碼和 Javadoc 檔案）和專案依賴項都會被考慮在內。

如果您只是想將 Gradle 專案載入 IntelliJ IDEA，請使用 IDE 的匯入工具。您不需要套用這個外掛來將專案匯入 IDEA，不過如果您有這麼做，匯入會考量您任何未直接修改產生檔案的額外 IDEA 設定 — 詳情請參閱設定區段。

IDEA 外掛產生的內容取決於使用哪些其他外掛

總是: 產生 IDEA 模組檔案。如果專案是根專案，也會產生 IDEA 專案和工作區檔案。
Java 外掛程式: 此外，還會將 Java 設定新增至 IDEA 模組和專案檔案。

IDEA 外掛程式的一個重點是開放自訂。外掛程式提供一組標準化的掛鉤，用於新增和移除產生檔案中的內容。

用法

若要使用 IDEA 外掛程式，請將其包含在您的建置指令碼中

範例 1. 使用 IDEA 外掛程式

build.gradle.kts

plugins {
    idea
}

build.gradle

plugins {
    id 'idea'
}

IDEA 外掛程式會新增多個工作至您的專案。idea 工作會為專案產生 IDEA 模組檔案。當專案是根專案時，idea 工作也會產生 IDEA 專案和工作區。IDEA 專案包含 Gradle 建置中每個專案的模組。

當專案是根專案時，IDEA 外掛程式也會新增一個 openIdea 工作。此工作會產生 IDEA 設定檔，並在 IDEA 中開啟結果。這表示您可以從根專案執行 ./gradlew openIdea，以一個便利的步驟產生並開啟 IDEA 專案。

IDEA 外掛程式也會新增一個 cleanIdea 工作至專案。如果存在，此工作會刪除產生的檔案。

工作

IDEA 外掛程式會新增以下所示的工作至專案。請注意，clean 工作不依賴於 cleanIdeaWorkspace 工作。這是因為工作區通常包含許多使用者特定的暫時資料，且不適合在 IDEA 外部處理。

idea: 依賴於：ideaProject、ideaModule、ideaWorkspace

產生所有 IDEA 設定檔
openIdea: 依賴於：idea

產生所有 IDEA 設定檔，並在 IDEA 中開啟專案
cleanIdea — 刪除: 依賴於：cleanIdeaProject、cleanIdeaModule

移除所有 IDEA 設定檔
cleanIdeaProject — 刪除: 移除 IDEA 專案檔案
cleanIdeaModule — 刪除: 移除 IDEA 模組檔案
cleanIdeaWorkspace — 刪除: 移除 IDEA 工作區檔案
ideaProject — GenerateIdeaProject: 產生 .ipr 檔案。此工作只會新增到根專案。
ideaModule — GenerateIdeaModule: 產生 .iml 檔案
ideaWorkspace — GenerateIdeaWorkspace: 產生 .iws 檔案。此工作只會新增到根專案。

組態

此外掛程式新增一些組態選項，讓您自訂它所產生的 IDEA 專案和模組檔案。這些選項的形式為模型屬性和直接修改產生檔案的較低層級機制。例如，您可以新增原始碼和資源目錄，以及插入您自己的 XML 片段。前一種組態類型會受到 IDEA 的匯入功能採用，而後一種則不會。

以下是可以使用的組態屬性

idea — IdeaModel: 頂層元素，讓您以 DSL 友善的方式組態 idea 外掛程式
idea.project IdeaProject: 讓您組態專案資訊
idea.module IdeaModule: 讓您組態模組資訊
idea.workspace IdeaWorkspace: 讓您組態工作區 XML

請點選類型連結，查看使用這些組態屬性的範例。

自訂產生檔案

IDEA 外掛程式提供掛勾和行為，讓您以更受控和詳細的方式自訂產生內容。此外，withXml 掛勾是修改工作區檔案的唯一實際方法，因為其對應的網域物件基本上是空的。

本節討論的技術不適用於 IDEA 的匯入功能

這些工作會辨識現有的 IDEA 檔案，並將它們與產生內容合併。

合併

現有 IDEA 檔案的部分，也是產生內容的目標，將會根據特定部分進行修改或覆寫。其餘部分將保持原樣。

停用合併並完全覆寫

若要完全改寫現有的 IDEA 檔案，請執行清理工作，以及對應的產生工作，例如「gradle cleanIdea idea」（依此順序）。如果您想將此設為預設行為，請將「tasks.idea.dependsOn(cleanIdea)」新增至您的建置指令碼。這樣就不需要明確執行清理工作。

此策略也可以用於外掛會產生的個別檔案。例如，可以使用「gradle cleanIdeaModule ideaModule」針對「.iml」檔案執行此操作。

掛入產生生命週期

外掛提供建模物件，表示由 Gradle 產生的中繼資料檔案部分。產生生命週期如下

讀取檔案；或如果檔案不存在，則使用 Gradle 提供的預設版本
執行 beforeMerged 掛入，並使用表示現有檔案的網域物件
將現有內容與從 Gradle 建置推斷或在 eclipse DSL 中明確定義的組態合併
執行 whenMerged 掛入，並使用表示要保留的檔案內容的網域物件
執行 withXml 掛入，並使用將要保留的 XML 原始表示
保留最終 XML

以下是用於各個模型類型的網域物件

IdeaProject

beforeMerged { Project arg -> … }
whenMerged { Project arg -> … }
withXml { XmlProvider arg -> … }

IdeaModule

beforeMerged { Module arg -> … }
whenMerged { Module arg -> … }
withXml { XmlProvider arg -> … }

IdeaWorkspace

beforeMerged { Workspace arg -> … }
whenMerged { Workspace arg -> … }
withXml { XmlProvider arg -> … }

部分改寫現有內容

「完全改寫」會捨棄所有現有內容，因此會遺失在 IDE 中直接進行的任何變更。beforeMerged 掛入讓您只要覆寫現有內容的特定部分即可。以下範例會從 Module 網域物件中移除所有現有相依性

範例 2. 模組的部分改寫

build.gradle.kts

import org.gradle.plugins.ide.idea.model.Module

idea.module.iml {
    beforeMerged(Action<Module> {
        dependencies.clear()
    })
}

build.gradle

idea.module.iml {
    beforeMerged { module ->
        module.dependencies.clear()
    }
}

產生的模組檔案將只包含 Gradle 產生的相依性項目，但不會包含原始檔案中可能存在的任何其他相依性項目。（在相依性項目的情況下，這也是預設行為。）模組檔案的其他部分將保持原樣或合併。專案檔案中的模組路徑也可以執行相同的操作

範例 3. 專案的部分重寫

build.gradle.kts

import org.gradle.plugins.ide.idea.model.Project

idea.project.ipr {
    beforeMerged(Action<Project> {
        modulePaths.clear()
    })
}

build.gradle

idea.project.ipr {
    beforeMerged { project ->
        project.modulePaths.clear()
    }
}

修改已完全填入的網域物件

whenMerged 掛鉤讓您可以操作已完全填入的網域物件。這通常是自訂 IDEA 檔案的首選方式。以下是匯出 IDEA 模組所有相依項目的方法

範例 4. 匯出相依項目

build.gradle.kts

import org.gradle.plugins.ide.idea.model.Module
import org.gradle.plugins.ide.idea.model.ModuleDependency

idea.module.iml {
    whenMerged(Action<Module> {
        dependencies.forEach {
            (it as ModuleDependency).isExported = true
        }
    })
}

build.gradle

idea.module.iml {
    whenMerged { module ->
        module.dependencies*.exported = true
    }
}

修改 XML 表示法

withXml 掛鉤讓您可以在檔案寫入磁碟之前操作記憶體中的 XML 表示法。雖然 Groovy 的 XML 支援和 Kotlin 的擴充功能彌補了很多，但這種方法不如操作網域物件方便。相對地，您可以完全控制產生的檔案，包括網域物件未建模的部分。

範例 5. 自訂 XML

build.gradle.kts

import org.w3c.dom.Element

idea.project.ipr {
    withXml(Action<XmlProvider> {
        fun Element.firstElement(predicate: (Element.() -> Boolean)) =
            childNodes
                .run { (0 until length).map(::item) }
                .filterIsInstance<Element>()
                .first { it.predicate() }

        asElement()
            .firstElement { tagName == "component" && getAttribute("name") == "VcsDirectoryMappings" }
            .firstElement { tagName == "mapping" }
            .setAttribute("vcs", "Git")
    })
}

build.gradle

idea.project.ipr {
    withXml { provider ->
        provider.node.component
                .find { it.@name == 'VcsDirectoryMappings' }
                .mapping.@vcs = 'Git'
    }
}

識別其他測試目錄

將此外掛程式與 Java 外掛程式一起使用時，在新增其他來源組後，您可能希望在它們包含測試來源而非生產來源時通知 IDEA，以便 IDE 可以適當地處理目錄。這可以使用此外掛程式的 Module 區塊來完成。

範例 6. 在來源組中識別其他測試目錄

build.gradle.kts

sourceSets {
    create("intTest") {
        java {
            setSrcDirs(listOf("src/integration"))
        }
    }
}

idea {
    module {
        testSources.from(sourceSets["intTest"].java.srcDirs)
    }
}

build.gradle

sourceSets {
    intTest {
        java {
            srcDirs = ['src/integration']
        }
    }
}

idea {
    module {
        testSources.from(sourceSets.intTest.java.srcDirs)
    }
}

使用 JVM 測試套件外掛程式時，會自動正確識別測試來源。

進一步考慮的事項

產生的 IDEA 檔案中的相依項目路徑是絕對路徑。如果您手動定義指向 Gradle 相依項目快取的路徑變數，IDEA 會自動將絕對相依項目路徑替換為此路徑變數。您可以透過「idea.pathVariables」屬性設定此路徑變數，以便它可以在不建立重複項目的情況下進行適當的合併。

此頁面有幫助嗎？