# FableUI

**Repository Path**: qsyan/FableUI

## Basic Information

- **Project Name**: FableUI
- **Description**: FableUI                      
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: v1
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2026-08-12
- **Last Updated**: 2026-10-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FableUI

基于 **Swing + JNA** 的 Windows 桌面 UI 框架：**保留系统窗口框架**（非 `setUndecorated`），由 Swing 自绘标题栏接管非客户区交互，并提供一套 **Element Plus 风格**的控件与组件库。

一句话概括：**照常写标准 Swing，就能得到现代 IDEA 风格的窗口与 Element Plus 风格的界面。**

> **版本号：`0.0.3`**　·　变更见 [CHANGELOG.md](CHANGELOG.md)

![截图描述](preview/light.png)

## 特性

- **零侵入装配**：`FableUI.setup()` 注册 LAF 钩子，之后任意 `JFrame` / `JDialog` 构造即自动获得自绘标题栏、圆角窗口与原生窗口能力；业务内容继续用原生 `frame.setContentPane(content)` 注入，无需继承任何基类。
- **原生窗口能力**（Windows）：标题栏拖动、双击最大化、8 向边缘缩放、拖顶最大化、左右贴靠分屏、Snap Layout 悬停入口、DWM 圆角；Swing 侧仅作为非 Windows 平台的回退路径。
- **Element Plus 风格控件**：按钮（5 种语义 + plain / round / circle / text / link / loading）、输入框、下拉框、复选框（含半选）、单选框、开关、滑块、进度条、细滚动条、选项卡、表格、树、菜单体系。
- **自研组件**：`FTable`（表头排序 / 48px 选择列 / 斑马纹 / 行分隔线开关 / 表头列分隔竖线开关 / 空数据占位）、`FTree`（系统文件图标 / 真实目录树 / 整行悬停与选中高亮，节点自身无方框无额外底色）、`FLoading`（加载圆环 + `JLayer` 遮罩）、`FPathField` / `FFileDialogs` / `FFileChooser`（路径与文件选择：`FFileDialogs` **原生优先**、原生不可用时自动回退；`FFileChooser` 自绘窗口含「返回上一级」「新建文件夹」与右键菜单「复制 / 剪切 / 粘贴 / 新建 / 重命名 / 删除」，重命名为**列表内就地编辑**，F2 触发）、`FTag` / `FBadge` / `FAlert` / `FCard` / `FEmpty` / `FResult` / `FSkeleton`，以及分隔条 `FSplitter` + `FSplitterPanel`（横向 / 纵向分栏，拖拽分隔条调整面板尺寸，支持 `min` / `max` 与 `resizable`，对齐 Element Plus `el-splitter`）等。
- **Element Plus 布局模型**（`com.fable.layout`）：`FRow` / `FCol` 24 栅格（`gutter` 列间距、`offset` 偏移、6 种分布、4 种垂直对齐、按容器宽度的断点响应式、自动换行），以及单轴堆叠容器 `FStack`（纵向 / 横向、交叉轴对齐、`grow` 吸收剩余空间、`wrap` 换行）—— 替代 `BorderLayout` / `GridLayout` / `BoxLayout` / `FlowLayout` 的各种样板写法（`setMaximumSize(getPreferredSize())`、`createVerticalStrut`、`createVerticalGlue`、`createHorizontalStrut` 等）。**框架自身与 demo 的界面布局均采用该模型**；旧布局名称仍会出现在迁移对照文档和源码注释中，业务容器也可继续使用标准 Swing 布局。
- **明暗双主题 + CSS 主题变量**：`ThemeMode.DARK` / `LIGHT`，运行期 `FableUI.applyThemeMode(...)` 一键切换并刷新所有已打开窗口；配色定义在 `theme.css`（CSS 子集：`var()` 引用、分层覆盖、选择器列表，对齐 Element Plus `--el-*` 的命名方式），因此**自定义主题只需写差异** —— `FableTheme.deriveFrom(基底, 资源, id)` + `FableUI.applyTheme(...)`。
- **可定制标题栏**：左 / 中 / 右三个插槽可放任意业务控件，空白区域仍保持原生拖动能力。

## 环境要求

| 项 | 要求 |
| --- | --- |
| JDK | 21 及以上 |
| 构建 | Maven 3.x |
| 依赖 | JNA 5.19.1（`jna` + `jna-platform`） |
| 平台 | Windows 10/11 可启用完整原生能力；其它平台（含 Linux / macOS）自动回退到 Swing 行为，不抛异常。文件 / 文件夹选择：Windows 走**现代通用项对话框**（`IFileDialog`，文件与文件夹都支持，带导航窗格 / 地址栏 / 搜索框），macOS 的文件选择走原生 `NSOpenPanel`，其余情况回退自绘窗口。**不支持 Windows 7 / 8.1**：JDK 21 的最低系统要求是 Windows 10（JDK 17 起的 Windows 版二进制在 Win7 上无法运行），而本项目语言级别为 21 |
| Maven 坐标 | `io.github.yannexus:fableui` |
| 版本 | `0.0.3` |
| 许可证 | Apache License 2.0 |

## 快速开始

**1. 安装到本地仓库并引入**

```bash
cd FableUI
mvn -o clean install -DskipTests
```

```xml
<dependency>
  <groupId>io.github.yannexus</groupId>
  <artifactId>fableui</artifactId>
  <version>0.0.3</version>
</dependency>
```

> Maven 坐标 `io.github.yannexus:fableui`（2026-09-19 由 `com.fable:FableUI:1.0-SNAPSHOT` 变更）；构件版本以依赖片段为准，**版本号为 `0.0.3`**（变更明细见 [CHANGELOG.md](CHANGELOG.md)）。
> `pom.xml` 已配置 `maven-source-plugin` / `maven-javadoc-plugin` / `maven-gpg-plugin` 与
> `central-publishing-maven-plugin`，`mvn verify` 会一并产出 `sources` / `javadoc` 与签名构件。

**2. 最小示例**

```java
import com.fable.components.FButtonUI;
import com.fable.core.FableUI;
import com.fable.layout.FStack;
import com.fable.layout.FStackAlignment;
import com.fable.theme.ThemeMode;

import javax.swing.JButton;
import javax.swing.JFrame;
import javax.swing.JLabel;
import javax.swing.SwingUtilities;

/** 使用框架布局创建最小桌面窗口。 */
public class HelloFable {

  /** 在 Swing 事件派发线程中安装主题并创建界面。 */
  public static void main(String[] args) {
    SwingUtilities.invokeLater(() -> {
      FableUI.setup(ThemeMode.LIGHT);          // 必须在任何窗口创建之前调用一次

      // 标准 Swing 按钮通过客户端属性使用主色外观。
      JButton primary = new JButton("主色按钮");
      primary.putClientProperty(FButtonUI.CLIENT_PROPERTY_TYPE,
        FButtonUI.FButtonType.PRIMARY);

      // 纵向内容区：文字吸收剩余高度，按钮按内容宽度靠左。
      FStack content = new FStack(12);
      content.addGrowing(new JLabel("你好，FableUI"));
      content.add(primary, FStackAlignment.START);

      // 创建标准窗口，框架自动装配标题栏。
      JFrame frame = new JFrame();              // 构造即自动装配装饰层
      frame.setContentPane(content);            // 原生 API，无需包装
      frame.setTitle("Hello FableUI");
      frame.setSize(640, 400);
      frame.setLocationRelativeTo(null);
      frame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
      frame.setVisible(true);
    });
  }
}
```

运行后即得到一个带自绘标题栏的圆角窗口：标题栏可原生拖动、双击最大化、边缘 8 向缩放，按钮为 Element Plus 主色填充样式。

**3. 运行内置演示**（20 个组件分区，覆盖全部控件）

```powershell
mvn -o -q compile
mvn -o dependency:build-classpath -Dmdep.outputFile=target/cp.txt
$cp = "target/classes;" + (Get-Content target/cp.txt -Raw).Trim()
java -cp $cp FableDemo
```

## 文档

| 文档 | 内容 |
| --- | --- |
| [docs/LAYOUT.md](docs/LAYOUT.md) | **布局指南（推荐新手先读）**：两条轴的心智模型、`FStack` / `FRow` / `FCol` 用法、固定宽与撑满的做法、响应式断点、常用配方、旧布局迁移对照、常见坑与 API 速查 |
| [docs/USAGE.md](docs/USAGE.md) | 使用手册：引入方式、快速上手、窗口与标题栏、主题与尺寸体系、全部组件用法与示例、场景配方、能力边界、打包分发与排错 FAQ |
| [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) | 开发文档：包职责、核心对象职责、Win32 消息处理、状态流转、高风险修改清单、问题排查记录、验证清单与累计变更记录 |
| [docs/HANDOFF.md](docs/HANDOFF.md) | 交接报告：当前状态、已修复问题、踩坑记录、名称变更映射表 |

## 构建与测试

```bash
mvn -q -DskipTests package     # 打包为 target/fableui-<version>.jar（不含依赖）
mvn clean test                  # 执行当前源码的全量测试
mvn -q verify                   # 额外产出 sources / javadoc 与 GPG 签名构件
```

运行时 classpath 需包含 JNA 两个 jar（`jna` 与 `jna-platform`）。

最近的全量验证记录见 [交接报告](docs/HANDOFF.md)：2026-10-09 记录为 39 个测试类、303 个用例，其中 1 个 COM 槽位自检用例跳过（另有 2 个 `FFileActionsTest` 错误为沙箱环境 junction 清理限制、非回归）。该记录是当时的验证结果，当前结果以重新运行后的 Surefire 报告为准。

## 许可证

本项目采用 [Apache License, Version 2.0](LICENSE)（全文见仓库根目录的 [`LICENSE`](LICENSE)）。