Gradle 1.12用户指南翻译——第三十九章. IDEA 插件

本文由CSDN博客万一博主翻译，其他章节的翻译请参见：

http://blog.csdn.net/column/details/gradle-translation.html

翻译项目请关注Github上的地址：

https://github.com/msdx/gradledoc

本文翻译所在分支：

https://github.com/msdx/gradledoc/tree/1.12。

直接浏览双语版的文档请访问：

http://gradledoc.qiniudn.com/1.12/userguide/userguide.html。

另外，Android 手机用户可通过我写的一个程序浏览文档，带缓存功能的，目前0.2.1版本兼容 android 2.2以上系统，地址如下：

http://www.wandoujia.com/apps/com.githang.gradledoc

翻译不易，转载请注明本文在CSDN博客上的出处：

http://blog.csdn.net/maosidiaoxian/article/details/47291703

关于我对Gradle的翻译，以Github上的项目及http://gradledoc.qiniudn.com 上的文档为准。如有发现翻译有误的地方，将首先在以上两个地方更新。因时间精力问题，博客中发表的译文基本不会同步修改。

第三十九章. IDEA 插件

IDEA 插件生成IntelliJ
IDEA所使用的文件，从而让项目能够在 IDEA 中打开 （File - Open
Project）。它考虑到了外部依赖项 （包括相关联的源文件和 javadoc 文件） 和项目依赖项。

IDEA 插件生成的内容完全取决于使用了哪些其他的插件：

表 39.1. IDEA插件行为

插件	描述
None	生成一个IDEA 模块文件。如果该项目为根项目，同时生成一个 IDEA 项目和工作区文件。
Java	将 Java 配置添加到模块和项目文件。

IDEA 插件的重点之一是对自定义项较为开放。该插件提供了一套标准化的 hooks 用于添加和删除生成的文件的内容。

39.1. 用法

要使用 IDEA 插件，请在构建脚本中包含以下语句：

示例 39.1. 使用 IDEA 插件

build.gradle

apply plugin: 'idea'

IDEA 插件向你的project 添加了大量的任务。您将使用的主要任务是 idea 和 cleanIdea 任务。

39.2.
任务

IDEA 插件向一个 project 添加了如下所示的任务。请注意，clean并不依赖于cleanIdeaWorkspace。这是因为工作区包含大量的用户特定的临时数据，在
IDEA 之外操纵它的做法通常是不可取的。

表 39.2. IDEA插件 - 任务

任务名称	依赖于	类型	描述
idea	ideaProject, ideaModule, ideaWorkspace	-	生成所有的 IDEA 配置文件
cleanIdea	cleanIdeaProject, cleanIdeaModule	Delete	删除所有的 IDEA 配置文件
cleanIdeaProject	-	Delete	删除 IDEA 项目文件
cleanIdeaModule	-	Delete	删除 IDEA 模块文件
cleanIdeaWorkspace	-	Delete	删除 IDEA 工作区文件
ideaProject	-	GenerateIdeaProject	生成 .ipr 文件。此任务仅添加到根项目。
ideaModule	-	GenerateIdeaModule	生成 .iml 文件
ideaWorkspace	-	GenerateIdeaWorkspace	生成 .iws 文件。此任务仅添加到根项目。

39.3.
配置

表 39.3. idea 插件的配置

模型	引用名称	描述
IdeaModel	idea	顶级元素，以DSL友好的方式启用 idea 插件的配置
IdeaProject	idea.project	允许配置项目信息
IdeaModule	idea.module	允许配置模块信息
IdeaWorkspace	idea.workspace	允许配置工作区 XML

39.4.
自定义生成的文件

IDEA 插件提供了一些 hook 和行，用于自定义生成的内容。工作区文件可以有效地只通过withXml hook
来操作，因为其相应的域对象实际上是空的。

该任务会识别现有的 IDEA 文件，并将它们与生成的内容进行合并。

39.4.1.
合并

已存在的 IDEA 文件的部分，也是生成的目标内容，将会被修改或覆盖，具体取决于特定的部分。剩余的部分则不变。

39.4.1.1.
禁用完整覆盖的合并

若要完整覆盖现有 IDEA 文件，请执行clean任务和其相应的生成任务，例如gradle
cleanIdea idea (按此顺序)。如果你想要让它成为默认行为，请将tasks.idea.dependsOn(cleanIdea)添加到构建脚本中。这样一来，我们就没有必要显式执行
clean 任务。

完整覆盖同样可以用于个人文件，例如通过执行gradle
cleanIdeaModule ideaModule。

39.4.2. Hooking到生成的生命周期中

本插件提供了一些对象，对由 Gradle 生成的元数据文件的这一部分内容进行建模。生成的生命周期如下:

1. 读取文件;如果它不存在，则使用由 Gradle 提供的默认版本
2. beforeMerged的
   hook 会随着一个表示现有文件的域对象执行
3. 从 Gradle 构建推断出来或在 eclipse DSL 中显示定义的配置会与现有的内容合并在一起
4. whenMerged的
   hook 会随着一个表示持久化的域对象执行
5. withXml的 hook
   会随着一个表示将被持久化的XML的 raw 执行
6. 最终的 XML 被持久化

下表列出了用于每个模型类型的域对象：

表 39.4. Idea 插件 hook

模型	beforeMerged { arg -> } 参数类型	whenMerged { arg -> } 参数类型	withXml { arg -> } 参数类型
IdeaProject	Project	Project	XmlProvider
IdeaModule	Module	Module	XmlProvider
IdeaWorkspace	Workspace	Workspace	XmlProvider

39.4.2.1.
部分重写现有内容

一个完全覆盖会导致现有的所有内容被丢弃，从而丢失在
IDE 中直接做的任何修改。beforeMerged hook
可以实现只覆盖现有的某些部分的内容。下面的示例从Module域对象中删除现有的所有依赖关系:

示例 39.2. 部分覆盖模块

build.gradle

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

生成的模块文件将只包含 Gradle 生成的依赖项，而没有其他可能存在于原始文件的依赖项。(对于依赖项，这也是默认行为。)其他部分的模块文件将会被保留或合并。对项目文件中的模块路径的处理也是一样：

示例 39.3. 部分覆盖项目

build.gradle

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

39.4.2.2.
修改完全填充的域对象

WhenMerged hook
允许操作完全填充的域对象。通常，这是自定义 IDEA 文件的首选方法。下面的例子展示了如何导出一个 IDEA 模块的所有依赖项：

示例 39.4. 导出依赖项

build.gradle

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

39.4.2.3.
修改 XML 的表示形式

WithXml hook
允许在文件写入到磁盘之前，操纵内存中的 XML 的表示形式。尽管 Groovy 的 XML 支持对其有很大作用，但这种方法比起操纵域对象依然不大方便 。作为回报，你可以对生成的文件进行全面的控制，包括未由域对象建模的那些部分。

示例 39.5. 自定义 XML

build.gradle

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

39.5.
进一步要考虑的事项

在生成的 IDEA 文件的依赖项路径是绝对路径。如果您手动定义路径变量来指向 Gradle 依赖缓存，IDEA 会自动把绝对依赖路径替换为此路径变量。如果你使用这种路径变量，您需要通过 idea.pathVariables 配置此路径变量，以便它可以做适当的合并而不会重复创建。