IntelliJ IDEA插件开发：文件、类、包选择器实战详解

1. 项目概述与整体设计思路做插件做到 UI 这一层大家遇到的第一道坎往往是“让用户选东西”。文件选择器、类选择器、包选择器这三个东西光听名字就知道是干嘛的弹一个原生对话框让用户挑一个文件、挑一个 Java 类、挑一个包然后插件接着取值干活。但你真上手之后就会发现这个坑比想象中深尤其是类选择器和包选择器和普通 Swing 的 JFileChooser 完全是两回事。这篇文章主要讲清楚三件事这三类选择器分别解决什么问题各自的 API 怎么调用以及把它们放进自定义 Dialog 时需要注意哪些细节。适合已经跑通“Hello World Action”的插件新手也适合写了好几个 Action 但对选择器一直一知半解的半熟手。前几篇如果你已经学会建工程、写 Action、挂菜单那这篇可以直接照着抄。说实话这三个选择器是插件开发里“交互层”的标准配置。比如你做一个“根据模板生成代码”的插件用户需要告诉程序在哪一个目录生成、以哪一个类为父类、放到哪一个包下。如果这些都是让用户手动敲路径体验直接崩盘还容易敲错。所以平台给了我们一组现成的选择器我们要做的就是理解它、接住它、别踩它埋的坑。2. 核心原理与选型逻辑2.1 为什么不用原生 Swing 的 JFileChooser刚接触时很多人会想IDEA 是基于 Swing 的那我直接用JFileChooser不就行了技术上行但“能行”和“好用”是两码事。IDEA 的项目里你看到的文件结构并不是操作系统文件系统的直接映射。你切 Project 面板时看到的 src、resources、xml其实是 IDEA 的 VirtualFileSystemVFS封装后的结果。插件如果用系统 JFileChooser拿到的是一堆java.io.File路径这些路径跟项目模块里的 Source Root、Library、Generated Source 没有关系。举个例子用户从系统文件选择器里选中一个.java文件你拿到路径还得自己解析哪个PsiClass在里面而 IDEA 自带的文件选择器返回的是VirtualFile可以直接交给PsiManager转成 PSI 对象或者配合VfsUtil判断是不是在某个模块的源码根目录下面。类选择器就更明显了。选类不能靠文件路径选它要遍历整个项目的类模型还要识别继承关系、注解、可见性这是一个纯 IDE 层面的操作Swing 本身根本没有这个概念。2.2 三个选择器的适用范围先用一句话概括三者定位选择器返回的核心对象典型用途文件选择器VirtualFile选文件、选目录、选任意资源读取内容或路径类选择器PsiClass选目标类作为继承、实现、引用关系的对象包选择器PsiPackage选包节点用于确定代码生成位置或分析包下结构生命周期上也很好区分文件选择器面向 VFS 资源类选择器面向 Java 模型的 PSI 节点包选择器则是“包树”上的节点。这三个对象之间其实可以通过同一套 PsiManager 互相转换后面实操部分会反复用到来回切换的技巧。2.3 项目模型与 PSI 的衔接写选择器之前必须建立一条心法IDEA 插件里所有 UI 组件最终拿到的不是一个字符串而是一个有上下文的模型对象。文件选择器拿VirtualFile通过PsiManager.getInstance(project).findFile(virtualFile)就能拿到PsiFile继续往下一层找PsiJavaFile、PsiClass都顺理成章。类选择器直接拿PsiClass反向用psiClass.getContainingFile().getVirtualFile()又能退回 VFS 层。包选择器拿PsiPackage用psiPackage.getDirectories()可以拿到源码根下对应的所有目录。这一条转换链非常关键。插件需求不管包装成什么样子最后都逃不开“模型层取对象、VFS 层定位、UI 层展示”这套流程。后面所有选择器代码本质上就是在帮你把用户输入转成这层模型的入口。3. 文件选择器实操从弹出到读取3.1 最简调用写法文件选择器的核心是FileChooserDescriptor加FileChooser。最基础的一段代码长这样FileChooserDescriptor descriptor new FileChooserDescriptor( true, // chooseFiles是否允许选文件 false, // chooseDirectories是否允许选目录 false, // chooseJars是否允许选择jar包 false, // chooseJarsAsFilesjar包是否作为文件处理 false, // chooseJarsAsDirectoriesjar是否作为目录展开 false // chooseMultiple是否允许多选 ); descriptor.setTitle(选择资源文件); descriptor.setDescription(请选择一个文件); VirtualFile file FileChooser.chooseFile(descriptor, project, null); if (file ! null) { // file.getPath() 拿完整路径 // file.getName() 拿文件名 }这里第一个参数是文件第二个参数是目录。很多人一开始只会用 true 和 false却不清楚当第一个为 true、第二个为 false 时弹窗里依然可以进入目录浏览只是没法把目录本身作为选中结果。也就是说目录能不能“被选中”和你“能否进入目录”是两个概念过滤规则管的是后者布尔参数管的是前者。3.2 多选与文件过滤实际项目里选一个的情况很少业务常见的是“批量导入多个文件”。这时候用chooseFilesListVirtualFile files FileChooser.chooseFiles(descriptor, project, null); if (!files.isEmpty()) { for (VirtualFile vf : files) { String ext vf.getExtension(); // 业务处理 } }如果你只希望允许选择 txt 或 java 文件不要自己在拿到结果后再做 if 判断直接在描述符里过滤更合规descriptor.withFileFilter(vf - vf.isDirectory() || txt.equals(vf.getExtension()));注意一个细节过滤方法里必须对isDirectory()放行。如果不过滤目录弹窗列表里所有文件夹都是灰色的用户根本进不去目录更不用说选中文件。有些版本还支持链式写法new FileChooserDescriptor(true, false, false, false, false, true) .withFileFilter(vf - vf.isDirectory() || java.equals(vf.getExtension())) .withTitle(选择Java文件) .withDescription(仅支持.java文件);这种链式 API 在文档里一般叫 Builder 风格实际类库里返回的还是同一个 descriptor 对象所以顺序无所谓。3.3 从 VirtualFile 到路径和内容选完了重点就是取值。很多新手在这里会绕弯路用file.getPath()拿到一个路径然后new File(path)转成java.io.File再用各种 File IO 去读内容。这条路不是不行但既然已经拿到 VFS 对象直接读取更安全byte[] bytes file.contentsToByteArray(); String content new String(bytes, file.getCharset());注意getCharset()比你自己猜 UTF-8 要靠谱。一个项目管理里很可能有非 UTF-8 编码的配置文件直接指定字符集容易乱码。如果是选目录你实际上拿到的是一个目录节点VirtualFile这时可以用VfsUtil遍历目录下的子节点for (VirtualFile child : file.getChildren()) { if (!child.isDirectory() java.equals(child.getExtension())) { // 处理目录下的Java文件 } }我习惯上会在 UI 面板里展示相对路径而不是绝对路径方便用户判断位置。判断某路径是否属于项目模块根可以用VfsUtilCore.isAncestor(baseDir, file, false)这样就不会把用户选进来一个项目外面的文件当正常路径处理。4. 类选择器实操从选择到 PSI4.1 用 TreeClassChooserFactory 打开选择弹窗类选择器和文件选择器最大的区别在于它展示的是“类”不是“文件”。平台里面最常用的是TreeClassChooserFactory它会在弹窗中展示一个包树结构用户展开包再选中具体类。下面按我当前环境里能跑通的方式写一个示例如果你的 SDK 版本较新或较老个别参数可能会不一样需要以你本地 SDK 里的 javadoc 为准TreeClassChooserFactory factory TreeClassChooserFactory.getInstance(project); TreeClassChooser chooser factory.createAllProjectScopeChooser( 选择目标类, null, psiClass - true, // ClassFilter返回 true 表示类可选 null // PackageFilternull 表示不过滤包 ); chooser.showDialog(); PsiClass selectedClass chooser.getSelected(); if (selectedClass ! null) { String qualifiedName selectedClass.getQualifiedName(); // 业务处理 }这个弹窗长得很像是 IDEA 里 CtrlN 的类查找弹窗底层逻辑也确实有相通之处会读取项目的编译模型、索引缓存和源码结构。正因为它依赖项目索引如果你刚通过外部命令往项目里放了一批新的.java文件还没来得及触发索引同步这时候打开类选择器很可能看不到它们。遇到这种情况别慌先在 IDEA 里跑一次同步或等右下角进度条完成再测。4.2 设置类过滤条件很多时候我们不想让用户选任意类比如插件是要“选择一个父类”那就只该让 public 类、非已 final 类可选。用 ClassFilter 就能做到ClassFilterPsiClass filter psiClass - { if (psiClass.isInterface()) { return false; } if (psiClass.hasModifierProperty(PsiModifier.ABSTRACT)) { return false; } if (psiClass.hasModifierProperty(PsiModifier.PRIVATE)) { return false; } return !psiClass.getQualifiedName().equals(java.lang.Object); }; TreeClassChooser chooser factory.createAllProjectScopeChooser( 选择父类, null, filter, null );这里PsiModifier里的常量要熟hasModifierProperty这个方法在处理 PSI 类类型时比Modifier.isPublic(...)更贴近 IDEA 的源码模型。有一点必须提醒类过滤器的执行次数比想象中高。你点开弹窗开始输入关键字过滤方法就会被反复调用。不要在过滤条件里写太重的逻辑比如从数据库查数据、从远程接口拉配置不然 UI 会卡到让人想卸载你的插件。所有重逻辑应该提前缓存到内存过滤方法里只做纯判断。4.3 选中类后拿到文件路径选类拿到的PsiClass本身不直接暴露路径但它背后有文件。最常见的转换PsiFile containingFile selectedClass.getContainingFile(); VirtualFile vf containingFile null ? null : containingFile.getVirtualFile(); if (vf ! null) { String path vf.getPath(); }这一条在生成代码时特别常用。比如用户选了一个父类你要定位父类所在的VirtualFile去分析它实现了哪些方法或者要把它所在包目录开放给用户继续选文件位置来回转换就这一句话的事。4.4 创建类引用和继承代码拿到PsiClass后一个很常见的场景是在当前编辑的 Java 文件里写一个继承它的类。这时需要把类引用转成PsiClassTypePsiElementFactory factory JavaPsiFacade.getElementFactory(project); PsiClassType classType factory.createType(selectedClass); String newClassText public class MySubClass extends selectedClass.getName() {}; PsiClass newClass factory.createClassFromText(newClassText, null);当然实际写进代码里时你还要处理包名、导入、方法重写等问题那属于 PSI 写入的范畴。这里想表达的是类选择器只是第一步选完之后你的插件拿到的是 Java 模型上的一个节点而且这个节点的能力远比名字和路径大。5. 包选择器实操从选择到目录映射5.1 使用 PackageChooser 快速调包包选择器的官方类是PackageChooser可能有的版本叫法略有差异写法思路一致。我用下面的方式打开一个包选择弹窗PackageChooser chooser new PackageChooser(project); chooser.show(); PsiPackage selectedPackage chooser.getSelectedPackage(); if (selectedPackage ! null) { String packageName selectedPackage.getQualifiedName(); }如果你当前环境实例化方式对不上也可以换个思路用ChooseByNamePopup加GlobalSearchScope自己拼一个轻量级的包搜索弹窗。不过大型插件没必要造轮子PackageChooser提供的树形浏览模式已经很好用用户按包列表点击可以直接看到包下面有哪些类筛选体验稳定。5.2 包名与源码目录的互相转换选包之后插件要做的事情通常是把一个新文件创建到这个包对应的目录里。这时光拿到包名不够你还需要知道物理目录在哪里VirtualFile[] directories selectedPackage.getDirectories(); if (directories.length 0) { // 第一个目录通常是主源码目录下的对应路径 VirtualFile targetDir directories[0]; // 创建新文件时把 PsiFile 放进去 }为什么会返回数组因为同一个包名可能同时存在于 main、test 甚至多个 module 的 Source Root 下面。比如com.demo.service这个包在 main 源码根下存在在 test 源码根下也有那getDirectories()就会返回两个目录。要不要遍历全部取决于你的业务到底想生成到哪个目录。还有另一个常见反向需求用户通过文件选择器选了一个源码目录你想判断它在哪个包下。这个可以通过PackageIndex来反查PackageIndex index PackageIndex.getInstance(project); PsiPackage pkg index.findPackageNameByDirectoryName(dirName);这种反查一般用于“用户选目录后自动回填包路径”的场景挺提升体验的。5.3 包选择器与目录选择器的取舍很多人分不清“选择包”和“选择目录”。一句话概括目录是文件系统概念包是源代码模型概念。目录选择器可能返回任意磁盘目录这个目录不一定对应任何 Java 类路径而包选择器只允许用户选择在项目源码根下面已经存在的包。你选包天然避免生成到resources或非 Source Root 里。我通常的建议是如果插件生成的代码最终要放到某个包结构里请优先考虑包选择器如果只是读取资源、覆盖文件、定位任意路径用文件选择器只有当你明确需要“找一个目录但不关心 Java 包结构”时才用目录选择器。三者之间别混着用免得后续判断模块归属时出幺蛾子。6. DialogWrapper 集成与交互设计6.1 创建面板并放置选择按钮选择器单独弹出的交互比较单薄更常见的集成方式是自定义一个 Dialog上面一个文本框、一个“浏览...”按钮用户点击按钮后才弹出选择器选择完回填文本框。这个模式很像你在 IDE 配置页里看到的路径选择器。核心代码框架如下public class MyDialog extends DialogWrapper { private final Project myProject; private JTextField pathField; private JButton browseButton; public MyDialog(Project project) { super(project); myProject project; setTitle(生成配置); init(); } Override protected JComponent createCenterPanel() { JPanel panel new JPanel(new BorderLayout()); pathField new JTextField(); browseButton new JButton(选择文件...); panel.add(pathField, BorderLayout.CENTER); panel.add(browseButton, BorderLayout.EAST); browseButton.addActionListener(e - { VirtualFile file FileChooser.chooseFile( new FileChooserDescriptor(true, false, false, false, false, false), myProject, panel); if (file ! null) { pathField.setText(file.getCanonicalPath()); } }); return panel; } public String getSelectedPath() { return pathField.getText().trim(); } }这里是几个容易踩的细节DialogWrapper里不要直接使用JDialog不然你无法继承平台的 MODAL 机制、快捷键和按钮校验体系。按钮监听器里要拿到的是当前面板组件作为 parent传null在某些聚焦场景下弹窗位置会比较奇怪。回填getCanonicalPath()而不是getPath()前者会解决掉..和.这种相对路径问题展示更友好。6.2 让确定按钮跟随校验状态对话框里“确定”按钮什么时候可用是一个交互分水岭。插件启动时默认可点用户什么都没选点确定后要么弹错误要么白选。我更推荐配合doValidate来做校验Override protected ValidationInfo doValidate() { String path pathField.getText().trim(); if (path.isEmpty()) { return new ValidationInfo(请先选择文件, pathField); } File file new File(path); if (!file.exists()) { return new ValidationInfo(文件不存在 path, pathField); } return super.doValidate(); }doValidate在每次输入变化时都会被触发所以它能即时改变 OK 按钮状态。这里不需要手动setOKActionEnabled只要返回ValidationInfoDialogWrapper 会自动把按钮置灰。另外如果校验逻辑很重比如要读文件头判断编码不要放在doValidate里同步等结果。可以把结果缓存到字段在开选择按钮的监听器里提前算好这样 UI 不会卡。6.3 多选择器组合的布局建议如果一个对话框里同时要选文件、类、包建议用FormBuilder或GridLayoutManager把三个字段排成三行。布局上注意几点每行最右侧放“选择”按钮便于对齐和视觉统一。文本框设为只读避免用户手动输入带来脏数据。当选择器之间有关联时比如选了类后包字段自动回填该类所在包记得在类选择按钮监听器里联动更新包字段。联动逻辑我建议统一封装一个SelectionModel类而不是在三个监听器里各写一遍 setText。字段一多直接改 UI 组件会很乱用数据模型驱动 UI 是长远之计。7. 常见问题与排查技巧实录7.1 文件选择器弹出但目录不可点击这个问题十有八九是描述符参数配错了。当你设了chooseFiles false, chooseDirectories true文件列表里的文件项就是灰色目录项可以选中这是正常现象。如果目录项也灰色检查一下withFileFilter里是否把目录过滤掉了。复查写法过滤条件里必须对vf.isDirectory()返回 true否则目录不会出现在可点击项中。7.2 类选择器列表一直空白很多开发者会把问题怪到 API 头上其实大概率是项目索引没建立好。新建一个简单的 Java 类然后在 IDE 里执行一次 “Build Project”等索引完成后再打开选择器。还有一种情况是自己写死了ClassFilter比如psiClass.getQualifiedName() null返回 false而一些匿名类、本地类的 qualifiedName 是 null就会导致大量类不可见。调试时可以先在过滤条件入口打印几行日志看看到底过滤了什么内容。7.3 拿到 PsiClass 后调用 getQualifiedName 为 null这个场景多发生在用户选择了一个 Java 文件里嵌套内部类或者选择了某些语言比如 Kotlin 文件里的类。getQualifiedName()不是对每一种类节点都有值稳妥的方式是退一步用psiClass.getName()配合全路径拼接。如果你确实需要全局唯一标识可以用JavaPsiFacade.getInstance(project).findClass(qualifiedName, GlobalSearchScope.allScope(project))先查一遍能找到说明是你拼错名字找不到说明这个类确实没有合格的 QName。7.4 包选择器返回的目录位置与预期不一致记住getDirectories()返回的是数组即可别只用索引 0。有时你会遇到同一个包在 main 和 test 下都存在用户选择包后你要么两个目录都展示出来让用户选要么根据当前编辑文件的 Module 范围来判定默认选哪个。一个稳妥的思路是拿到当前文件的放置目录作为基准VirtualFile currentFile CommonDataKeys.VIRTUAL_FILE.getData(e.getDataContext()); PsiFile currentPsi PsiManager.getInstance(project).findFile(currentFile);然后比较包目录数组里谁和currentPsi的模块根更近就能做出智能默认。7.5 回调执行没有走上预期分支选择器很多 API 返回对象如果用户点击“取消”返回的是 null。大量新手漏判 null导致后续直接 NPE。所有赋值之后第一件事if (selected ! null) { // 正常逻辑 }另外注意文件选择器里的FileChooser.chooseFile是模态阻塞调用它本身要停在 EDT 上等待而你在 ActionPerformed 里的监听器回调会自动在 EDT 上执行不要再包一层 SwingUtilities.invokeLater那是多余的还会造成弹窗位置错乱。7.6 插件集成测试时选择器与预期 UI 不一致因为 IDEA 是 Swing 写的主题和 Look and Feel 由平台自带插件直接 new 一个 JDialog 会导致字体、颜色和顶部按钮风格脱离整套 IDE。遇到这种问题先检查有没有走平台封装类。文件选择器必须走FileChooser类选择器必须走TreeClassChooserFactory包选择器走PackageChooser如果自己用 JFileChooser 拼出来的界面整体观感很难融入这不叫调试问题属于从一开始选错了实现链路。8. 从选择器到完整插件功能讲到这里三个选择器的单点用法已经覆盖完了但真正写插件时它们是组合使用的。比如一个“快速生成 Service 接口实现类”的插件流程大致是这样先弹一个 Dialog文本框里填类名旁边按钮选包再旁边选接口类确认时插件拿到PsiPackage创建目录结构拿到PsiClass读取接口方法列表自动生成实现类并写入磁盘。个人经验是写选择器 UI 时最容易翻车的不是 API 记不住而是大量代码纠缠在一起把“选择器返回了什么”和“之后要干什么”混在同一个监听器里。更合理的结构是先封装一层返回值对象public class SelectorResult { public final VirtualFile file; public final PsiClass targetClass; public final PsiPackage targetPackage; }然后监听器只负责填充SelectorResult后续所有业务逻辑单独一个方法处理。这样不但好测而且写三个选择器时不会互相污染。最后再分享一个小技巧这几个选择器弹窗在用户使用频繁时尽量记住上次选中的位置或类下次打开时定位到那个节点。特别是包选择器这种记忆功能对老用户来说非常受用。实现上保存一个字符串约等于勾选了路径的缓存不复杂但对插件好评度的提升比想象中大得多。