idea插件开发文档

设置指南

走着路睡觉大约 8 分钟

设置指南

设置在 Windows中是Settings，在macOS中是Preferences，所有基于IntelliJ Platform平台的IDE中的设置都由Settings 控制。

插件使用持久化模型 来创建和存储它们的配置。可以在IDE的设置open in new window 对话框中添加用户自定义的设置项。

设置（Settings）可以设置不同级别的作用域。当前文档主要是添加项目级、应用级和全局级（Project and Application，Global）的自定义设置项

设置（Settings）的扩展点

根据设置项的作用域，可以使用两个扩展点 [extension points (缩写为EP)] 之一在 plugin.xml 注册自定义设置项。两个扩展点大部门的属性是共享的。

项目级、应用级（Project and Application)的设置项不能使用运行时依赖，需要提供一个Configurableopen in new window 接口的实现类，具体可以在下文中的扩展点的实现类中查看如何实现。

提示

由于性能原因，在plugin.xml注册的 'Settings' 实现类应尽量配置更多的属性。如果不配置，这个组件就需要从实现类中获取所需要的属性，会降低 UI 响应能力。

注册应用级（application-level）设置项

用com.intellij.applicationConfigurable 扩展点来注册应用级的设置项

<!--该示例表示这个设置位于 tools 设置组下面，实现类是 com.example.ApplicationSettingsConfigurable-->
<!--唯一id，和实现类的全限定命名一致-->
<!--设置项的显示名称为 My Application Settings-->
<!--可以在下文中 注册点的属性 中了解更多属性信息-->
<extensions defaultExtensionNs="com.intellij">
  <applicationConfigurable
      parentId="tools"
      instance="com.example.ApplicationSettingsConfigurable"
      id="com.example.ApplicationSettingsConfigurable"
      displayName="My Application Settings"/>
</extensions>

注册项目级（project-level）设置

用 com.intellij.projectConfigurable 扩展点来注册项目级（project-level）的设置

<!-- 属性和上面应用级的设置基本一致-->
<!-- nonDefaultProject=true 表示这个设置在 default project（https://www.jetbrains.com/help/idea/configure-project-settings.html?_gl=1*h9qmcz*_ga*NjQ4Mjk3NDAwLjE2MTU5OTA0Mzg.*_ga_9J976DJZ68*MTY2MDI4MTgwNS4xNzAuMS4xNjYwMjgxOTM4LjA.&_ga=2.155679932.647259505.1660118069-648297400.1615990438#new-default-settings） 不会自动加载-->
<!--可以在下文中 注册点的属性 中了解更多属性信息-->
<extensions defaultExtensionNs="com.intellij">
    <projectConfigurable
            parentId="tools"
            instance="com.example.ProjectSettingsConfigurable"
            id="com.example.ProjectSettingsConfigurable"
            displayName="My Project Settings"
            nonDefaultProject="true"/>
</extensions>

注册点的属性

鼓励开发者去查看 Configurableopen in new window 和 ConfigurableProvider 的 Javadoc 注释，下面内容对注释提供了补充说明。

属性列表

下面包括com.intellij.projectConfigurable 和com.intellij.applicationConfigurable 扩展点的属性描述

属性适用接口是否必填属性值
instanceConfigurable看下文注意事项1Configurable 实现类的全限定命名，实现方式可查看下文文档 Configurable接口
providerConfigurableProvider看下文注意事项1ConfigurableProvider 实现类的全限定命名，实现方式可查看下文文档 ConfigurableProvider接口
nonDefaultProjectConfigurableY只能在项目级 com.intellij.projectConfigurable 扩展点使用，false表示所有的项目设置都可见，true表示除了 default projectopen in new window 外都可见
displayNameConfigurableProvider
Configurable		看下文注意事项2在设置左边列表显示的名称(不支持文本国际化)，如果要支持国际化，使用下面的属性
key and bundleConfigurableProvider
Configurable		看下文注意事项2在设置左边列表显示的名称(支持文本国际化)
idConfigurableProvider
Configurable		Y唯一性，可以使用实现类的全限定命名
parentIdConfigurableProvider
Configurable		Y放在哪个设置组下面,可选值参考 设置的id列表 ,groupId已失效（看下文注意事项3）
groupWeightConfigurableProvider
Configurable		N设置的显示顺序，默认为0，排在最后
dynamicConfigurable.CompositeN该设置的子设置项都是通过 getConfigurables() 方法获取，不推荐使用，因为会加载很多类，尽量使用XML属性配置子设置项
childrenEPNameConfigurableN扩展点的全限定命名，通过这个扩展点来获取子设置

注意事项：

  1. instance 或 provider 必须指定一个

  2. displayName 和 key and bundle 必须指定一个，文本不需要国际化使用displayName，需要国际化使用key and bundle

  3. 如果同时配置了groupId和parentId，idea会提示警告信息。parentId列表见下文 设置的id列表

设置的id列表

上文中的parentId的列表

parentId设置组名称描述
defaultother如果groupId和parentId都未配置，则会放入该设置组，不建议，详情看 other 的描述
appearanceAppearance & Behavior
buildBuild, Execution, Deployment
build.toolsBuild Integration上面build的子组，主要包括构建插件，例如 maven ,gradle等
editorEditor编辑器相关
languageLanguages and Frameworks和使用的编辑语言相关的配置
tools3rd Party Settings三方设置，如何 SSH终端配置，管理服务器密码等
rootSuper Parent所有设置的超父类，不建议使用
otherCatch-all不建议使用它，可以用 tools 代替
projectProject-related Settings不建议使用，主要存储项目相关的设置

扩展点的实现类

com.intellij.projectConfigurable 和com.intellij.applicationConfigurable 扩展点的实现有以下2种方式:

Configurable接口

intellij-community 大多数的设置项都基于 Configurable 接口或它的子类，例如 SearchableConfigurableopen in new window ，推荐开发者阅读 Configurable接口的 Javadoc注释

构造器

实现类的构造器，必须满足以下一些条件

  • 使用com.intellij.applicationConfigurable扩展点注册的实现类，必须有默认无参构造器

  • 使用com.intellij.projectConfigurable扩展点注册的设置实现类，必须有带 Projectopen in new window 一个参数的构造器

  • 从2020.2版本开始，不允许构造器注入其它参数（除了 Project ）

对使用扩展点正确注册的设置项来说，用户不点击该设置，不会调用该实现类的构造器进行初始化。

注意

IntelliJ Platform 在后台线程中实例化Configurable实现类，所以在构造器中创建Swing组件会降低响应速度

IntelliJ Platform和Configurable接口交互

Configurable接口常用方法如下：

  • 在调用了Configurable.createComponent() 方法后会立即调用 Configurable.reset() 方法。所以不需要在构造函数或 createComponent() 方法中初始化设置项相关组件

  • 上文中的构造器内容

  • 一旦Configurable实例化，无论设置是否更改，或者用户在设置对话框菜单上选择其它条目，实例的生命周期都会继续

  • 当用户点击了设置对话框里的OK或Cancel时，Configurable实例的生命周期才会结束。关闭设置对话框时会调用Configurable.disposeUIResources() 方法

打开设置对话框或显示某一个 Configurable，可以使用 ShowSettingsUtil 类

Configurable的标记接口

基于Configurable的实现类也可以实现标记接口，标记接口提供了一些特性

下面的标记接口，可以将 Swing表单信息传递给 IntelliJ Platform

  • Configurable.NoScroll 通知设置对话框不能增加滚动条。默认情况下，设置的组件会放入一个带滚动条的面板里，这个接口可以删除滚动条
  • Configurable.NoMargin 通知设置对话框不能添加空边框。默认情况下，插件的组件会添加一个空边框

基于Configurable的其它接口

IntelliJ Platform有一些基于 com.intellij.openapi.options.ConfigurableEP 特定功能的类。例如：Settings/Preferences | Editor | General | Appearance 中可以使用 EditorSmartKeysConfigurableEP和com.intellij.editorSmartKeysConfigurable 扩展点来注册设置项

示例

可以参考以下实现：

ConfigurableProvider接口

ConfigurableProvideropen in new window 只在满足某些条件的时候提供 Configurable实现类。IntelliJ Platform 先调用ConfigurableProvider.canCreateConfigurable() 方法，进行逻辑判断，返回true 表示当前设置是有效的，然后调用 ConfigurableProvider.createConfigurable() 方法获取设置项。

ConfigurableProvider 是通过属性列表 中的provider 属性来指定的

示例: RunToolbarSettingsConfigurableProvideropen in new window

上次编辑于:
贡献者: zhaojingbo
Loading...