# swing-element-ui

**Repository Path**: gitbird/swing-element-ui

## Basic Information

- **Project Name**: swing-element-ui
- **Description**: Swing Element UI 是一个将 Vue.js 的 Element UI 设计语言移植到 Java Swing 的桌面端组件库。采用纯矢量自绘方式实现所有组件的外观，不依赖任何外部库（除 JDK 自带的 FlatLaf 作为可选的 Swing 增强），支持运行时主题切换、动画过渡、WCAG 2.1 AA 级对比度合规
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-09-30
- **Last Updated**: 2026-10-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# swing-element-ui

Element UI 风格的 Java Swing 组件库（JDK 8，零依赖）。

## 快速开始

```
.\run-demo.bat      # 一键构建并启动组件演示（ComponentShowcase）
```

Maven 坐标（当前以源码形式分发，见下「构建」；`mvn install` 到本地仓库后即可按坐标引入）：

```xml
<dependency>
    <groupId>org.swelement</groupId>
    <artifactId>swing-element-ui</artifactId>
    <version>1.0.0</version>
</dependency>
```

最小可运行示例（组件可直接放进普通 Swing 容器）：

```java
import org.swelement.ui.AstButton;
import javax.swing.JFrame;
import javax.swing.SwingUtilities;

SwingUtilities.invokeLater(() -> {
    JFrame f = new JFrame("Hello swing-element-ui");
    f.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
    f.add(new AstButton("你好，Element 风格"));
    f.setSize(360, 200);
    f.setLocationRelativeTo(null);
    f.setVisible(true);
});
```

更多见[入门指南](docs/framework/getting-started.md)。

## 构建

```
.\build.bat        # 编译到 out/ 并跑全部组件自检
.\run-checks.bat   # 仅跑全部组件自检（含文档-代码一致性校验）
```

> **在 IDEA 中运行**：本项目源码根是 `src/`、编译输出是 `out/`，`pom.xml` 已显式声明
> `sourceDirectory` / `outputDirectory`（与上面命令行的 `-cp out` 一致）。
> 首次打开或改过 `pom.xml` 后，点 **Maven 面板 → Reload All Maven Projects**（或右上角刷新图标），
> 再 `Build → Rebuild Project`，然后对 Demo 的 `main` 右键 Run。
> 若报「找不到或无法加载主类」，通常是 IDEA 的模块输出还停在 `target/classes`（空目录）——
> Reload Maven 项目即可恢复为 `out/`。

## 运行 Demo

```
java -cp out org.swelement.demo.ComponentShowcase
```

全部 71 个组件（56 widget + 15 图表）的演示收敛于 ComponentShowcase 单一入口（八大分类 + 布局体系实景页，图表页恢复自退役 AstChartDemo）；
历史 47 个独立 *Demo 类已于 demo 收敛批次退役，组件自检回归各自 selfCheck。

## 核心自检

```
java -ea -cp out org.swelement.core.Easing
java -ea -cp out org.swelement.core.ElementTheme
java -ea -cp out org.swelement.core.AnimationManager
java -ea -cp out org.swelement.core.theme.ThemeManager
java -ea -cp out org.swelement.ui.AstSelect
java -ea -cp out org.swelement.ui.AstPagination
```

## 设计

见 `docs/superpowers/specs/2026-08-19-swing-element-ui-design.md`

## 组件总览

> 文档列为组件说明页（`docs/components/` 下）。Demo 已收敛：全部组件演示见
> `org.swelement.demo.ComponentShowcase`（八大分类 + 布局体系实景页，菜单导航 → 每组件一页）。
> 历史 47 个独立 `*Demo` 类已退役（2026-09-22，见 CHANGELOG [未发布]），表中 Demo 列为该组件在 Showcase 中的所在分类。

| 组件 | 文档 | Demo |
|------|------|------|
| Alert 提示 | [文档](docs/components/alert.md) | Showcase·反馈 |
| Avatar 头像 | — | Showcase·数据展示 |
| Badge 角标 | [文档](docs/components/badge.md) | Showcase·数据展示 |
| BarChart 柱状图 | [文档](docs/components/barchart.md) | Showcase·图表 |
| BoxPlotChart 箱线图 | [文档](docs/components/boxplotchart.md) | Showcase·图表 |
| Breadcrumb 面包屑 | [文档](docs/components/breadcrumb.md) | Showcase·导航 |
| Button 按钮 | [文档](docs/components/button.md) | Showcase·表单 |
| Calendar 日历 | — | — |
| CalendarHeatmap 日历热力图 | [文档](docs/components/calendarheatmap.md) | Showcase·图表 |
| CandlestickChart K 线图 | [文档](docs/components/candlestickchart.md) | Showcase·图表 |
| Card 卡片 | — | Showcase·数据展示 |
| Carousel 走马灯 | — | — |
| Cascader 级联选择 | — | — |
| Checkbox 多选框 | [文档](docs/components/checkbox.md) | Showcase·表单 |
| CloseButton 关闭按钮 | — | — |
| Collapse 折叠面板 | [文档](docs/components/collapse.md) | Showcase·数据展示 |
| Container 布局容器 | — | Showcase·布局 |
| ControlChart 控制图（SPC） | [文档](docs/components/controlchart.md) | Showcase·图表 |
| CrudPage 增删改查页 | [文档](docs/components/crudpage.md) | Showcase·聚合组件 |
| DataLoader 数据装载契约 | [文档](docs/components/crudpage.md)（数据双模式节） | Showcase·聚合组件 |
| DatePicker 日期选择 | [文档](docs/components/datepicker.md) | Showcase·表单 |
| DeviceMonitorView 设备监控墙 | [文档](docs/components/devicemonitorview.md) | Showcase·聚合组件 |
| Dialog 对话框 | — | — |
| Divider 分割线 | — | — |
| Drawer 抽屉 | — | — |
| Dropdown 下拉菜单 | — | — |
| DynamicForm 动态表单 | [文档](docs/components/dynamicform.md) | — |
| FilterBar 声明式筛选条 | [文档](docs/components/crudpage.md)（FilterBar 联动节） | Showcase·聚合组件 |
| Funnel 漏斗图 | [文档](docs/components/funnel.md) | Showcase·图表 |
| Form 表单 | — | Showcase·表单 |
| FormDialog 弹窗表单 | [文档](docs/components/formdialog.md) | Showcase·聚合组件 |
| Gauge 仪表盘 | [文档](docs/components/gauge.md) | Showcase·图表 |
| Heatmap 热力图 | [文档](docs/components/heatmap.md) | Showcase·图表 |
| Icon 图标 | — | Showcase·数据展示 |
| Input 输入框 | [文档](docs/components/input.md) | Showcase·表单 |
| InputNumber 数字输入 | — | — |
| KpiBoard 指标墙 | [文档](docs/components/kpiboard.md) | Showcase·聚合组件 |
| LineChart 折线图 | [文档](docs/components/linechart.md) | Showcase·图表 |
| ListPage 四槽列表页 | [文档](docs/components/crudpage.md)（基件 API 附录节） | Showcase·数据展示 |
| Loading 加载 | — | Showcase·反馈 |
| MasterDetailView 主从视图 | [文档](docs/components/masterview.md) | Showcase·聚合组件 |
| Menu 导航菜单 | [文档](docs/components/menu.md) | Showcase·导航 |
| Message 消息 | — | — |
| MessageBox 弹框 | — | — |
| Pagination 分页 | [文档](docs/components/pagination.md) | Showcase·导航 |
| ParetoChart 帕累托图 | [文档](docs/components/paretochart.md) | Showcase·图表 |
| PieChart 饼图 | [文档](docs/components/piechart.md) | Showcase·图表 |
| Popover 弹出框 | — | Showcase·反馈 |
| Progress 进度条 | [文档](docs/components/progress.md) | Showcase·反馈 |
| RadarChart 雷达图 | [文档](docs/components/radarchart.md) | Showcase·图表 |
| Radio 单选框 | [文档](docs/components/radio.md) | Showcase·表单 |
| Rate 评分 | — | — |
| SankeyChart 桑基图 | [文档](docs/components/sankeychart.md) | Showcase·图表 |
| ScatterChart 散点图 | [文档](docs/components/scatterchart.md) | Showcase·图表 |
| ScanField 扫码录入 | [文档](docs/components/scanfield.md) | — |
| Select 选择器 | [文档](docs/components/select.md) | Showcase·表单 |
| Slider 滑块 | [文档](docs/components/slider.md) | Showcase·表单 |
| Sparkline 迷你图 | [文档](docs/components/sparkline.md) | Showcase·图表 |
| SpcAnalysisPage SPC 分析页 | [文档](docs/components/spcanalysispage.md) | Showcase·聚合组件 |
| Statistic 统计数值 | [文档](docs/components/statistic.md) | Showcase·数据展示 |
| Steps 步骤条 | [文档](docs/components/steps.md) | Showcase·导航 |
| Switch 开关 | [文档](docs/components/switch.md) | Showcase·表单 |
| Table 表格 | [文档](docs/components/table.md) | Showcase·数据展示 |
| Tabs 标签页 | [文档](docs/components/tabs.md) | Showcase·导航 |
| Tag 标记 | [文档](docs/components/tag.md) | Showcase·数据展示 |
| TextArea 多行输入 | — | — |
| TimePicker 时间选择 | [文档](docs/components/timepicker.md) | Showcase·表单 |
| Timeline 时间线 | [文档](docs/components/timeline.md) | Showcase·数据展示 |
| Tooltip 文字提示 | — | Showcase·反馈 |
| Transfer 穿梭框 | — | — |
| Tree 树形控件 | — | — |
| Treemap 矩形树图 | [文档](docs/components/treemap.md) | Showcase·图表 |
| Upload 附件上传面板 | [文档](docs/components/upload.md) | — |
| WaferMap 晶圆图 | [文档](docs/components/wafermap.md) | Showcase·图表 |
| WaterfallChart 瀑布图 | [文档](docs/components/waterfallchart.md) | Showcase·图表 |
| Wizard 向导 | [文档](docs/components/wizard.md) | — |

## 数据可视化 V5 变更注记

- 新增矩形树图（Treemap：squarify 布局 + 点击下钻）与桑基图（SankeyChart：列分层 + 流量连线）；
  `AstChart` 基类新增框选刷选（`setBrushEnabled` / `addBrushListener`，与 dataZoom 缩放并存，
  散点/折线已消费；柱状等不支持 zoom 的图型 `setZoomEnabled(true)` 抛 IAE）。
- **破坏性收紧**：数值入参对 NaN/±∞ 从静默接受改为拒绝（IAE，消息含 "must be finite"）——
  涉及 Candle（OHLC）、BoxPlotData、ChartZoom、CalendarHeatmapData、HeatmapData（±∞；NaN
  仍为空格语义）、TreemapNode、Squarify、SankeyData、SankeyLayout。完整清单见
  [progress.md](progress.md) V5 段。

## 数据可视化 V6 变更注记

- 色标扩展：新增 `LogColorScale`（对数感知重映射，右偏数据）与 `QuantileColorScale`（分位断点分段线性），
  经 `AstHeatmap.setColorScale` 热切换使用（热力图支持对数色标（`setColorScale`，API 级能力；页内演示入口待 T2 增强））。

## 数据可视化 V7 变更注记

- 图表导出：`ChartExportUtil.writePNG(component, file, scale, background)` 将任意组件（含全部图表）渲染为高分辨率 PNG（EDT 上调用；图表支持导出当前页 PNG（`ChartExportUtil`，API 级能力；页内演示入口待 T2 增强））。

## 文档-代码一致性

`run-checks.bat` 内含 `DocSnippetCheck`：抽取文档中的 ```java 代码块并对照 `out/` 真正编译，
校验 markdown 链接、命令引用真实存在，从机制上防止文档与代码再次漂移。
截图由 `tools/DocScreenshotGen.java` 离屏渲染生成，主题更新后重跑即可刷新。

## 已知限制

- **表格树模式不支持分页**：模型登记树形行后 `setPageSize` 抛 `IllegalArgumentException`（客户端分页切片只对平表，AntD 分页同口径）。V1 边界，树形+分页组合待后续版本评估。
- **AstMessage/AstNotification 全局门面在无活动窗口时抛 `IllegalArgumentException`**：`info/success/warning/error` 无 owner 重载自动解析活动窗口为宿主（活动窗口优先、退焦点窗口），解析不到（尚无窗口显示）即以 IAE 语义拒绝。既定语义——全局用法前确保至少一个窗口已显示，或显式传 owner。
- **i18n 已渲染组件不自动刷新**：`AstMessages.setLocale` 后新取值生效（`get`/`getFmt` 每次现取），已构建组件需重建或等下一次 `rebuild`；全局 LocaleChange 监听与自动刷新属 V2（见[国际化](docs/framework/i18n.md)）。
- **demo 的 CODE_SAMPLE_* 示例代码不随 locale 切换**：示例源码是 `SampleCodeCheck` 编译级校验的真实 Java 代码，属 demo i18n 键化的既定例外。
- **HiDPI 细节与视觉回归基线为备案项**：HiDPI 非整数缩放下的动画脏矩形残影、1px 线条发虚两项防护是条件任务（症状出现时实施，见组件设计规范）；视觉回归目前靠 selfCheck 内联像素断言，跨版本基线文件比对在路线图备案。