JavaFX Application 啟動參數處理與基本架構範例

前言

JavaFX 是 Java 豐富客戶端應用程式的標準 UI 工具組。本文透過一個最小化範例，示範 Application 類別的啟動流程、命令列參數接收與基本場景建立。

一、核心架構圖解

┌─────────────────────────────────────┐
│         JavaFX Launcher             │
│  (啟動器: 載入 FX runtime, 呼叫 main)│
└──────────────┬──────────────────────┘
               ▼
┌─────────────────────────────────────┐
│      Application 子類別              │
│  • init()       : 初始化 (非 UI 執行緒)│
│  • start(Stage) : 主進入點 (JavaFX 應用執行緒)│
│  • stop()       : 關閉前清理          │
└──────────────┬──────────────────────┘
               ▼
┌─────────────────────────────────────┐
│         Stage (舞台/視窗)            │
│  └─ Scene (場景)                    │
│      └─ Root Node (佈局容器)         │
│          └─ UI Controls (按鈕、文字等)│
└─────────────────────────────────────┘

二、完整可執行範例：接收命令列參數顯示圖片

package com.example.javafx;

import javafx.application.Application;
import javafx.geometry.Insets;
import javafx.scene.Group;
import javafx.scene.Scene;
import javafx.scene.effect.SepiaTone;
import javafx.scene.image.Image;
import javafx.scene.image.ImageView;
import javafx.scene.layout.HBox;
import javafx.stage.Stage;

import java.util.List;

public class ImageViewerApp extends Application {

    @Override
    public void init() {
        // 應用程式初始化 (非 JavaFX 應用執行緒)
        System.out.println("🔧 初始化階段...");
    }

    @Override
    public void start(Stage primaryStage) {
        // 1. 取得命令列參數
        Parameters params = getParameters();
        List rawArgs = params.getRaw(); // 未解析的原始參數
        List namedArgs = params.getNamed(); // --key=value 格式
        List unnamedArgs = params.getUnnamed(); // 非 key-value 參數
        
        System.out.println("原始參數: " + rawArgs);
        System.out.println("具名參數: " + namedArgs);
        System.out.println("無名參數: " + unnamedArgs);

        // 2. 解析圖片路徑 (第一個無名參數)
        String imageUrl = unnamedArgs.isEmpty() 
            ? "https://openjfx.io/images/openjfx-davinci.png" // 預設圖片
            : unnamedArgs.get(0);

        // 3. 建立 UI 元件
        Image image = new Image(imageUrl, true); // 背景載入
        ImageView imageView = new ImageView(image);
        imageView.setFitWidth(600);
        imageView.setPreserveRatio(true);
        imageView.setEffect(new SepiaTone(0.5)); // 應用複古濾鏡

        // 4. 佈局
        HBox root = new HBox(imageView);
        root.setPadding(new Insets(20));
        root.setStyle("-fx-background-color: #f0f0f0;");

        // 5. 建立場景與舞台
        Scene scene = new Scene(root);
        primaryStage.setTitle("JavaFX 圖片檢視器 - 參數: " + imageUrl);
        primaryStage.setScene(scene);
        primaryStage.show();
    }

    @Override
    public void stop() {
        System.out.println("🛑 應用程式關閉，釋放資源...");
    }

    // 標準 main 方法 (非必要，但方便 IDE 直接執行)
    public static void main(String[] args) {
        launch(args); // 啟動 JavaFX 應用程式
    }
}

三、參數傳遞方式說明

四、常見啟動方式

1. IDE 直接執行 (IntelliJ / Eclipse)

• 右鍵主類別 → Run，預設無參數
• 設定 Program Arguments：--width=1024 --theme=dark image.png

2. 命令列執行 (需 JavaFX SDK)

# 模組化專案 (Java 11+)
java --module-path /path/to/javafx-sdk/lib \
     --add-modules javafx.controls,javafx.fxml \
     -cp target/classes com.example.javafx.ImageViewerApp \
     --width=800 photo.jpg

# 非模組化 (Java 8 或打包 Fat JAR)
java -cp "target/classes;/path/to/javafx-sdk/lib/*" com.example.javafx.ImageViewerApp photo.jpg

3. 打包為原生安裝檔 (jpackage, Java 14+)

jpackage --input target/dist \
         --name ImageViewer \
         --main-class com.example.javafx.ImageViewerApp \
         --main-jar ImageViewerApp.jar \
         --type exe --icon icon.ico

五、關鍵生命週期方法對照

六、最佳實踐提醒

• 長時間任務：init() 或事件處理中執行耗時操作 (資料庫、網路) 必須使用 Task/Service 背景執行緒，避免凍結 UI。
• 平台相容：使用 Platform.runLater() 確保 UI 更新在 JavaFX 執行緒執行。
• 資源管理：Image、MediaPlayer 等持有原生資源的物件，在 stop() 中釋放。
• 模組化：Java 9+ 需在 module-info.java 宣告 requires javafx.controls; requires javafx.fxml; 並 opens com.example.javafx to javafx.graphics;。

結語

JavaFX Application 的啟動參數處理機制簡潔有力，搭配 Parameters API 即可輕鬆實現命令列驅動的桌面應用。掌握生命週期與執行緒模型，是開發穩健 JavaFX 應用的關鍵基石。