本文由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插件行为

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插件 - 任务

39.3.
配置

表 39.3. idea 插件的配置

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

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 配置此路径变量，以便它可以做适当的合并而不会重复创建。