简介JavaFX官方示例合集Ensemble由Oracle开发并随JDK发布是一套面向桌面与富客户端开发者的经典学习资源覆盖UI控件、布局容器、动画效果、图表绘制、媒体播放及CSS样式化等核心主题。资源包内共包含673个文件压缩包大小约20.24MB其中243个Java源文件提供各示例的实现代码236张PNG与46张JPG图片用作界面与图标素材44个XML和19个CSS文件分别对应场景构建与样式定制另有WAV音频、FXML布局及properties配置等辅助文件目录分类明确便于按需检索。目前已有275人学习下载。通过运行和阅读这组示例读者可掌握JavaFX从界面搭建、样式美化到业务逻辑的完整写法并可参考曲线拟合图表、透明/叠加/流媒体播放器以及自定义登录界面等典型案例提炼通用开发模式FXML与CSS的搭配使用也直观展示了界面与逻辑分离的推荐实践是官方API文档之外极佳的动手学习样例。1. javafx Ensemble 不是玩具 demo它是 JavaFX 技术栈的“活字典”如果你和我一样第一次打开 javafx Ensemble 时是被它的界面花哨程度惊到的那么你大概率低估了这个资源。某一次我接了一个桌面端数据大屏需求甲方要求图表联动、卡片翻转、带模糊阴影的悬浮按钮还要把整套 UI 做成皮肤可切换。我当时对 JavaFX 的理解停留在基础控件层面第一反应是上网找组件库结果越找越乱最后老老实实把 javafx Ensemble 的源码完整拆了一遍。说实话那三千行业务代码最后只写了不到五百行剩下的全是从这个示例集里抄组织结构、抄样式写法、抄动画参数。Ensemble 不是给你“看看效果”的展示程序它是一个把 JavaFX 的控件、布局、图表、特效、CSS、FXML 全部串起来的可运行工程。适合谁适合那些不想把时间耗在“这个控件到底支不支持圆角”这类问题上的开发者也适合刚把 JavaFX 跑起来、正需要一套完整代码来建立坐标系的新手。它能解决的核心问题只有一个当你不确定某个界面方案“在 JavaFX 里到底能不能做”时它给你答案而且给的是能直接抄的答案。2. Ensemble 的源码结构先读懂它的分类思想再谈复制代码2.1 一级结构samples、controls、charts三层之间靠什么连接把 javafx Ensemble 的工程克隆下来之后第一件事别急着运行先看目录。之前的版本是 JavaFX SDK 里带的一个独立模块后面改版后变成了一个相对独立的项目工程。它的源码结构大体上分成三块核心外壳界面框架、样例仓库Sample 的注册与读取、具体样例一组组独立的示例。核心外壳负责把左侧分类列表、右侧预览区、底部代码区组装出来样例仓库负责管理“有哪些示例、属于哪个分类、用什么方式加载”具体样例则是你真正要抄的东西每个样例通常是一个独立的类或者一套完整的 FXML 加控制器。我强烈建议你先把ensemble/samples这个目录当作一本书的目录来读。它内部按charts、controls、graphics、layout、media、web、fxml分包。举个例子charts分包里不是把所有图表示例平铺而是再按bar、line、pie、scatter、area等继续细分。这个层层分类的结构非常重要因为它决定了你后续“找例子”的速度。如果你只想要一个“带数据提示的堆叠面积图”你可以先进入charts再进area直接定位到stacked-area-chart这个 sample。没有这个分类思路你会陷入“全项目搜索图表关键字”的低效循环。2.2 Sample 类的注册机制它不是硬编码列表而是注解驱动Ensemble 能做得这么有条理核心是因为它对“示例单元”做了抽象。每一个示例不管是一个纯图表还是一个复杂交互界面都实现成了一个继承自Sample的类。我在拆源码的时候发现它的注册方式很有趣并不是在一个巨大的配置类里手动new出所有示例而是通过注解或者类名反射来自动发现。老版本里是每个示例类标一个Sample注解新版又改成在SampleCategory里直接引用类对象。以我平常用得最多的写法来看新版这种“显式引用”反而更容易学public class LineChartSample extends Sample { public LineChartSample() { super(new LineChartApp()); } }不要小看这个几行代码的壳子。new LineChartApp()里的LineChartApp才是真正画图表的类而Sample本身承担的是“元信息”功能。我个人的理解是Sample这个父类其实是在为整个 Ensemble 外壳提供统一的加载契约。外壳不关心你到底画的是折线还是饼图它只问你三个问题你的标题是什么、你的内容是什么、你的源码文件路径是什么。这种解耦方式是我在实际项目里复用得最狠的一个设计。后来我在做一个插件化桌面工具时直接借鉴了这套思想把每个业务功能页做成一个类似Sample的实现类主框架只负责加载。2.3 源码预览区为什么要单独标一个CodeSample路径很多第一次用 Ensemble 的新手都会发现一个奇特的地方界面上每个样例右边都能看到对应源码但是你以为它显示的是源代码其实它是把源码文件当纯文本读出来的。CodeSample或者相关资源类里通常会写类似下面的片段public static final String CODE samples/LineChartApp.java;那字符串里存的是相对于源码根目录的文件路径。这个做法看起来不起眼但很值得借鉴。它意味着“演示内容”和“演示代码”是天然分离的——你改一行业务代码预览区的源码文本如果路径没变它仍然能同步显示新代码。很多初学 JavaFX 的人以为这里的源码是运行时从内存里反射出来的其实不是它就是把硬盘上的.java文件用InputStream读进来而已。如果你在打包自己的应用时也想做类似功能注意一点路径字符串里不要带前导/否则打包成 jar 之后会读不到这是后文要讲的坑之一。2.4 样式文件不是在每个样例里都引一次而是走全局 CSS 覆盖再往深看一层Ensemble 里每个示例虽然看起来风格各异但那些按钮、滑块、进度条的基础样式并没有在每个样例里都复制一遍。它的做法是在基础外壳里定了一套Modena风格然后各个样例只写自己特有的那一小段 CSS最后在启动时通过样式表叠加。这个做法直接决定了你抄示例时的姿势千万不要看到某个特效漂亮就把它整段 CSS 复制进自己的application.css你得先搞清楚那段 CSS 是写在全局还是写在局部。我当时抄一个“按钮点击波纹特效”的样例直接把它写的button.css拖进了自己的项目结果整个应用所有按钮全部变得花里胡哨连取消按钮都带上了夸张的阴影。后来才明白样例里那个 CSS 是加载在单个Scene上的不是全局的。你要么也单独建一个Scene沿用局部样式要么用更具体的类选择器隔离。这一点很反直觉建议你拆源码时重点标记。3. 把 javafx Ensemble 跑起来模块化环境是第一个坎3.1 没有模块化经验先别碰 jlink直接用 Maven 插件很多人在下载 Ensemble 源码后第一个动作是找Main.java然后点运行结果被一连串的module not found报错拦住了。原因很简单JavaFX 从某个版本开始全面模块化Ensemble 的构建方式默认走的是模块路径不是 classpath。老式的“把 jar 塞进 classpath 再运行”到了 JavaFX 桌面项目上经常出问题尤其在控件类比较多的时候。我一般不会在自己的项目里手写javac命令去编译 Ensemble太容易漏模块。Maven 加org.openjfx插件是最不容易出错的路子。你只需要在pom.xml里声明 JavaFX 依赖并指定主类plugin groupIdorg.openjfx/groupId artifactIdjavafx-maven-plugin/artifactId version0.0.8/version configuration mainClassensemble.EnsembleApp/mainClass /configuration /plugin然后执行mvn javafx:run插件会自动处理模块路径。这个写法的好处是你不必手动推导--module-path指向哪、--add-modules要加哪些模块插件会从你声明的依赖里推导。如果你用的是 Gradle我建议照抄application插件后把模块信息写进module-info.java。注意module-info.java必须放在src/main/java/module-info.java路径错一个字都会导致运行时找不到模块。3.2 从源码目录启动时的--module-path怎么配如果你的项目结构特殊必须用纯命令行跑那--module-path的配置就得自己心里门清。假设你下载的是编译好的 Ensemble 示例包并且已经用某个包管理工具安装了 JavaFX那么启动命令往往长这样java --module-path /path/to/javafx-sdk/lib \ --add-modules javafx.controls,javafx.fxml,javafx.web,javafx.media \ -jar ensemble.jar这段命令里最容易被忽略的是javafx.web和javafx.media。Ensemble 里有 WebView 相关的示例和音视频相关示例如果只加javafx.controls和javafx.fxml应用本身能启动但一点到 web 或 media 分类里的样例就直接抛ClassNotFoundException。这不是 Ensemble 程序的问题是模块缺失导致的。我建议你干脆把所有模块都加上最大减少运行时缺模块概率。还有一个小细节--add-modules后面的模块名不支持通配符必须逐个列全。曾经有人图省事写成了--add-modules javafx.*结果终端直接报错。这个参数不解析通配表达式。那怎么办你可以在module-info.java里统一requires javafx.web;这样启动时只写一个--add-modules用手写清晰列出所有。3.3 启动之后黑屏还是白屏先看 GPU 渲染环境按说前面配置没问题Ensemble 应该能弹出来。但还有一类不算少见的场景程序启动过程中没有报错窗口也出来了但整个界面是白底左侧分类列表死活刷不出来。这时候你先别怀疑代码先把渲染管线切到软件渲染试试。启动参数里加上一句-Dprism.ordersw干净利落。如果加了这句之后界面正常出现那说明是你的显卡驱动或虚拟化环境对硬件加速支持不完整。Ensemble 里的大量效果示例都会触发Prism的渲染路径某些老显卡在es2管线里会摔跟头。特别是远程桌面环境这种情况比例很高。我一般会在跑 Ensemble 之前先用一个最小的 JavaFX 窗口程序测试渲染最小窗口正常才继续跑完整资源省得混淆问题来源。4. 抄作业的正确姿势怎么从 Ensemble 提取代码到真实业务项目4.1 不是整包复制而是“样例最小化”很多人看到 Ensemble 里某个图表效果好直接把整个样例类连同关联的 FXML、CSS 一股脑复制进自己的项目。如果样例本身是自包含的这种复制勉强能用。但 Ensemble 里的样例并不都是自包含的有些图表需要SampleBase之类的父类才能运行你要是只复制叶子类编译必然报错。我自己的习惯是三条线同时抓。第一先把样例类运行起来确认它在 Ensemble 里的效果第二打开这个样例对应的源码文件从import列表反推它依赖了哪些包第三把和业务无关的外壳代码全部删掉只保留核心逻辑方法。举个例子我必须拿到一个“鼠标悬浮显示数据点数值”的折线图。Ensemble 里有个样例做得极好但我并不把它的整个StackedAreaChart复制下来我只提取这一段核心逻辑lineChart.setCreateSymbols(true); lineChart.getData().setAll(series); lineChart.setAlternativeRowFillVisible(false);然后我把series数据源替换成自己接口返回的数据。这样确保功能到位又不引入演示代码里那些固定数据集。4.2 FXML 与控制器分离的样例注意 fx:id 命名冲突Ensemble 里有一部分样例用 FXML 构建界面例如一个带表单输入和动态验证的示例。这种样例复制起来最危险FXML 里的fx:id是局部命名它和你的业务代码里用FXML注入的字段必须严格对应。你单独复制 FXML 文件到自己的工程后如果你的 Controller 字段名跟它写的不一样运行时会报找不到属性。这个报错信息本身说得又隐晦经常只是一句Can not set ... field ...不仔细看根本发现不了是fx:id对不上。我踩过这个坑之后给自己定了规矩从 Ensemble 复制 FXML 样例时必须连带它对应的 Controller 一起复制然后先保证原版能跑再改字段名。不要图省事只复制界面文件然后自己猜反射字段名。默认规则所有带FXML注解的字段其变量名必须和 fxml 里的fx:id完全一致包括大小写。这是 JavaFX 框架的硬约束不存在巧劲。4.3 图表样例复用时的数据源替换套路图表类样例在 Ensemble 里占大头也是实际业务需求最高的一类。但 Ensemble 的图表数据基本上都是写死的静态数据我们拿来用一定要改成“列表驱动”。常见的做法是保留它的显示配置然后把数据构造段一分为二第一部分是从业务接口拿到的原始数据集合第二部分是把集合转换成为XYChart.Series。下面这段是我从 Ensemble 一个柱状图样例里攒出来的通用代码我已经在原基础上加了注释public XYChart.SeriesString, Number buildSeries(ListDouble dataList) { XYChart.SeriesString, Number series new XYChart.Series(); series.setName(业务指标); for (int i 0; i dataList.size(); i) { series.getData().add(new XYChart.Data(T (i 1), dataList.get(i))); } return series; }这里的XYChart.Data构造参数第一个是类目轴上的值第二个是数值轴上的值。很多新手把String和Number的位置写反导致图表显示出来类别轴变成了数字轴。拿这个 Series 赋给图表之前还要注意先清空旧数据chart.getData().clear()否则反复刷新时图表会出现重叠数据旧柱状图和新柱状图叠在一起视觉上像是没重绘干净。4.4 CSS 复制的边界从修饰控件到修饰容器Ensemble 里的 CSS 样例是最容易让人产生“原来还可以这样”感觉的部分。但我强烈建议你克制一下每次复制 CSS 时先问一个问题这条规则有没有使用类型选择器比如.button {}这种选择器一旦放进全局样式表会把应用里所有按钮全部影响。Ensemble 里的 CSS 之所以看起来安全性高是因为它的样例界面本身比较独立样式表只挂在那个样例所在的Scene上。我的建议是如果是容器级样式例如面板背景、VBox 间距、圆角卡片这部分可以放心抄。如果是控件级样式比如按钮、列表项、滚动条必须给它加上一个作用范围更精确的类名。举例来说你看到一个list-view .list-cell的样式抄进自己的 CSS 时最好改成#member-list .list-cell或者.custom-list-view .list-cell。这样可以让你的主界面不过度设计。5. JavaFX Ensemble 常见问题排查五个我实测过的翻车现场5.1 现象左侧示例列表出现但右侧预览区一直空白原因多半是预览区所在的TabPane没有正确加载Sample内容。Ensemble 外壳会根据左侧选中状态动态创建Sample的getContent()但某些样例在构造过程中需要访问外部资源例如图片文件或者 FXML资源路径写的是相对路径运行时因工作目录不同而找不到文件于是异常被吞掉后界面表现为空白。解决启动时把工作目录切到工程根目录或者在配置里把资源加载路径统一改成从 classpath 读。我自己的习惯是预览之前先用getResource来验证资源如果返回null就立刻暂停不要等界面白屏再回头找原因。示例getClass().getResource(images/logo.png)返回 null 直接打印日志。5.2 现象点开 web 示例时整个程序直接崩控制台提示模块未导出原因Ensemble 里的 WebView 样例使用javafx.web模块但程序的外壳模块在module-info.java里只requires了javafx.controls和javafx.fxml并没有对外开放javafx.web的访问权限。Java 模块化体系里跨模块访问类需要两边都声明好缺一不可。解决在module-info.java中增加requires javafx.web;同时在启动命令中把javafx.web也加进--add-modules。如果你是 Maven 构建还要在pom.xml里给 JavaFX 的javafx-web依赖添加正确的 classifier不同操作系统要选不同平台的构件包。这个坑最隐蔽的是它在编译期完全正常运行到对应样例才炸所以排查成本高你最好一开始就把 web 模块备好。5.3 现象用自己封装的 jar 打包 Ensemble 后样例源码预览区显示“文件找不到”原因源码预览区读取的是.java源文件路径它设计时假设你运行的是源码工程工作目录里有samples/目录。当你用jlink或jpackage打包成独立镜像时源码文件不会默认进入镜像预览区自然拿不到文件流。解决如果只是自己学习不要打包ensemble成带源码预览的独立应用保持跑源码工程即可。如果你的确需要把预览功能嵌入到自己的产品中那就要在构建脚本里把样例源文件目录作为资源拷贝进 jar然后改用getResourceAsStream读取。拷贝时注意不要带前导/否则 zip 文件系统找不到路径。5.4 现象自定义 CSS 在 Ensemble 里有效但放到自己应用里控制台报错原因最常见的报错是UnsupportedOperationException或CSS Error。往往是因为 Ensemble 里有些 CSS 属性只服务特定控件皮肤或特定 JavaFX 版本比如某个 skin 类在最新版本里被重命名选择器仍然沿用旧名导致解析不出正确的样式类。与此同时Ensemble 本身可能在启动时自动调整了默认皮肤自己应用没有那个步骤。解决先锁定 Ensembl 使用的 JavaFX 版本再用自己项目的对应版本来验证。把 CSS 文件切到一半用二分注释法测试哪一行触发报错。比较实用的技巧是给Scene设置getStylesheets().add(...)时放在界面创建完成后不要放在构造器里避免控件还没有初始化完成时就应用样式。我吃过这个亏构造器里加样式表单组件还没生成样式直接失效。5.5 现象所有示例都能跑但点击“回到首页”按钮后内存一直涨原因这个现象在 Ensemble 里其实不算 bug而是典型的“示例对象不被释放”。Ensemble 外壳为了快速切换大量使用了缓存每个样例实例一旦创建就不会主动销毁图表样例里的动画线程和历史数据都还在引用对象。结果就是你在不同示例间反复切换内存占用呈阶梯式上涨。解决确认是学习用途可以接受这种设计如果是借鉴 Ensemble 外壳做产品框架就要在界面切走时主动释放数据引用。我一般的做法是在Sample里增加一个dispose()方法把图表数据清空、动画停掉、事件监听移除。切走的动作里调用dispose()再清空内容面板。这个设计写到自己的框架里比直接搬外壳代码更健康。6. 进阶用法用 Ensemble 当 JavaFX 版本的“效果验收场”如果你已经把 Ensemble 里的示例抄进了业务代码下一步可以试试高效的工作流拿它当作你当地 JavaFX 环境的“效果验收场”。具体做法很简单每次项目里要新加一个复杂界面我先不直接在自己的工程里写而是把需求抽象成 Ensemble 里已有的相近示例用 Ensemble 跑起来看真实样式再决定这个方案是否值得做。这里有个我非常依赖的技巧改掉 Ensemble 的默认主题 CSS换上你自己项目的主题颜色观察所有样例在新主题下的表现。这样你能提前判断哪些组件样式在不同主题之间会产生明显视觉冲突。.root { -fx-base: #2b3e50; -fx-accent: #1abc9c; }把这两行加到 ensemble 的全局样式表尾部所有图表、按钮、列表项的配色会被统一替换。如果某些控件在换主题后出现文字看不清、选区边框消失那说明你在写的业务界面里也可能会遇到同款问题。这个办法不需要写任何业务代码只是改了一处 CSS就能提前暴露掉一大批主题适配问题。我后来给自己立了一个习惯每个 JavaFX 项目启动前强制把 Ensemble 在当前 JDK 版本上完整跑一遍不做手工观察而是直接跑一遍它的所有分类样例只要有一个分类样例在切换时报错就不启动实际项目开发。听起来有点玄学但这个做法确实帮我挡住了好几次因为系统字体或显卡驱动问题导致的荒谬渲染故障。从那以后我每次升级 JDK 或 JavaFX 版本第一件事就是拿出 Ensemble 过一遍它就像一把尺子能让我快速知道新环境里哪些东西翻了车、哪些东西还稳着。希望帮到你。本文还有配套的精品资源点击获取
