1. JavaFX FXML 本地化基础
在开发多语言应用程序时，本地化（Localization）是不可或缺的一环。JavaFX通过ResourceBundle提供了强大的本地化支持，它允许应用程序根据用户的语言环境加载不同的文本、图像等资源。当使用FXML构建用户界面时，FXMLLoader扮演着关键角色，它可以在加载FXML文件时，将一个ResourceBundle传递给控制器，以便控制器能够访问本地化的字符串。
通常，FXMLLoader的实例化方式如下，其中第二个参数即为本地化资源包：
import javafx.fxml.FXMLLoader;
import java.util.ResourceBundle;
public class Application {
// ...
public void start(Stage primaryStage) throws Exception {
// 加载名为 "com.example.myApp.MainMenu" 的资源包
ResourceBundle bundle = ResourceBundle.getBundle("com.example.myApp.MainMenu");
FXMLLoader loader = new FXMLLoader(getClass().getResource("main-menu.fxml"), bundle);
Parent root = loader.load();
// ...
}
}然而，如何在FXML控制器内部直接访问这个已传递的ResourceBundle，以便动态地设置文本或其他本地化内容，是开发者经常遇到的问题。
2. 在控制器中访问 ResourceBundle 的方法
为了在控制器中获取FXMLLoader传递的ResourceBundle，JavaFX提供了两种主要机制。
立即学习“Java免费学习笔记（深入）”；
2.1 传统方法：实现 Initializable 接口
Initializable接口是JavaFX早期版本中用于控制器初始化的一种标准方式。它定义了一个initialize方法，该方法会在FXML加载完成后，且所有@FXML注解的字段被注入后被调用。initialize方法接受两个参数：URL location（FXML文件的位置）和ResourceBundle resources（通过FXMLLoader传递的资源包）。
控制器示例：
import javafx.fxml.FXML;
import javafx.fxml.Initializable;
import javafx.scene.control.Label;
import java.net.URL;
import java.util.ResourceBundle;
public class MainMenuController implements Initializable {
@FXML
private Label welcomeText;
private ResourceBundle localisationBundle; // 用于存储资源包
@Override
public void initialize(URL location, ResourceBundle bundle) {
this.localisationBundle = bundle; // 将传入的资源包保存起来
// 可以在这里使用资源包设置初始文本
welcomeText.setText(localisationBundle.getString("welcomeMessage"));
}
@FXML
protected void onButtonClick() {
// 按钮点击时使用资源包获取本地化字符串
welcomeText.setText(localisationBundle.getString("greetMessage"));
}
}注意事项：
- 控制器必须显式实现Initializable接口。
- initialize方法签名必须与接口定义一致。
- 虽然此方法仍然有效，但JavaFX官方文档指出它已被更现代的机制“取代”（superseded），即下文将介绍的自动注入方式。
2.2 现代方法：通过 @FXML 自动注入
JavaFX提供了一种更简洁、推荐的方式来访问location和resources：通过@FXML注解将它们作为控制器类的成员变量进行自动注入。当FXMLLoader加载FXML文件并创建控制器实例时，它会自动查找并注入名为location（类型为URL）和resources（类型为ResourceBundle）的@FXML注解字段。
控制器示例：
import javafx.fxml.FXML;
import javafx.scene.control.Label;
import java.net.URL;
import java.util.ResourceBundle;
public class MainMenuController {
@FXML
private Label welcomeText;
@FXML // 自动注入 ResourceBundle
private ResourceBundle resources;
@FXML // 自动注入 FXML 文件位置 (可选)
private URL location;
// 如果需要，仍然可以使用无参数的 initialize 方法进行其他初始化
@FXML
public void initialize() {
// 此时 resources 和 location 已经被注入
welcomeText.setText(resources.getString("welcomeMessage"));
System.out.println("FXML文件位置: " + location);
}
@FXML
protected void onButtonClick() {
// 直接使用注入的 resources 字段
welcomeText.setText(resources.getString("greetMessage"));
}
}关键点：
- 无需实现任何接口。
- 只需在控制器类中声明@FXML private ResourceBundle resources;和（可选）@FXML private URL location;字段。
- 这些字段会在控制器实例创建并注入所有FXML元素之后、initialize()方法（如果存在）被调用之前自动填充。
- 字段名称必须严格为resources和location，否则注入将失败。
3. FXML 文件与资源文件配置
为了使上述控制器能够正常工作，还需要确保FXML文件和ResourceBundle资源文件配置正确。
FXML 文件示例 (main-menu.fxml)：
在FXML文件中，可以使用%前缀直接引用ResourceBundle中的键，例如text="%welcomeMessage"。这会在FXML加载时自动解析为相应的本地化字符串。
资源文件示例 (MainMenu_en.properties, MainMenu_zh.properties)：
com/example/myApp/MainMenu_en.properties:
welcomeMessage=Welcome to My App! greetMessage=Hello from the button! clickMeButton=Click Me!
com/example/myApp/MainMenu_zh.properties:
welcomeMessage=欢迎来到我的应用！ greetMessage=按钮问候您！ clickMeButton=点击我！
4. 总结与最佳实践
在JavaFX FXML控制器中访问ResourceBundle以实现本地化功能，推荐使用@FXML自动注入机制。这种方法简洁、直观，并且是JavaFX官方推荐的现代实践。
- 推荐方式： 在控制器中声明@FXML private ResourceBundle resources;字段。
- 字段命名： 确保ResourceBundle字段名为resources，URL字段名为location。
- FXMLLoader配置： 务必在实例化FXMLLoader时，通过其构造函数或setResources()方法传入ResourceBundle实例。
- FXML内部引用： 对于静态文本，可以直接在FXML文件中使用%key语法引用资源包中的字符串。
- 控制器动态更新： 对于需要在运行时动态更改的文本，可以通过注入的resources对象调用resources.getString("key")方法来获取本地化字符串。
通过遵循这些实践，您可以有效地在JavaFX FXML应用程序中实现健壮且易于维护的本地化功能。
