# JscmGUI

**Repository Path**: SnailcatMall/JscmGUI

## Basic Information

- **Project Name**: JscmGUI
- **Description**: java炫彩界面库开发例子使用jscm框架开发
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-09-14
- **Last Updated**: 2026-09-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# JscmGUI — 基于炫彩界面库（XCGUI）与 JSCM 框架的桌面应用

> **项目名称**：JscmGUI（JSCM 智能管理平台）
> **GroupID / ArtifactID**：`org.example` / `JscmGUI` · **Version**：`1.0-SNAPSHOT`
> **JDK**：Java 8 · **平台**：Windows 7+（x86 / x64） · **构建**：Maven
> **底层 GUI**：炫彩界面库 XCGUI（Direct2D） · **依赖框架**：Jscm-Core（本地 `Jscm-Core.jar`）

JscmGUI 是一个基于 **炫彩界面库（XCGUI）** 与 **JSCM 框架** 的桌面应用示例，实现了完整的登录认证流程（登录 / 快速登录 / 注册 / 修改密码 / 短信验证码）与登录后的智能管理工作台（可折叠导航菜单 + 多页面切换 + 全局搜索 + 明暗主题），并以此演示「**XML 配置骨架 + Java 管血肉**」的现代化桌面 UI 开发范式。

---

## 界面预览

登录中心（账号登录 / 快速登录 / 注册 / 修改密码 / 短信验证码，左侧品牌区渐变 + 光斑动画）：

<img src="docs/screenshots/login.png" width="640" alt="登录中心" />

智能管理工作台（明色主题）：

<img src="docs/screenshots/main.png" width="680" alt="智能管理工作台明色" />

智能管理工作台（暗色主题，标题栏主题按钮一键切换）：

<img src="docs/screenshots/main_dark.png" width="680" alt="智能管理工作台暗色" />

---

## 一、炫彩界面库（XCGUI）的优势

炫彩界面库是本项目的底层渲染引擎，通过 JSCM 框架以 JNI 方式封装为 Java API。相比传统桌面 UI 方案，其核心优势如下：

| 维度 | 炫彩 XCGUI | 传统方案（Swing / JavaFX） | Electron / Web |
|:---|:---|:---|:---|
| 渲染引擎 | **Direct2D 硬件加速**，GPU 渲染 | CPU 软渲染（Swing） | Chromium，内存占用高 |
| 体积与启动 | 原生 DLL，**轻量、秒级启动** | 随 JRE 打包，偏重 | 动辄数百 MB |
| UI 表现力 | 无边框、透明、圆角、阴影、渐变、动画 | 原生样式陈旧、定制难 | 现代但笨重 |
| 自绘能力 | `XDraw_*` 逐像素自绘，可画任意图形 | 需重写 paint 逻辑 | 依赖 CSS/Canvas |
| 语言栈 | **纯 Java**，无 Web 前端负担 | 纯 Java | 需 HTML/CSS/JS |

### 1.1 Direct2D 硬件加速渲染

- 所有控件由 Direct2D 引擎绘制，**不依赖操作系统原生控件**，视觉风格完全可控。
- 支持透明窗口、圆角窗口、投影阴影、渐变背景、抗锯齿文字，适合现代扁平化 / 深色主题设计。

### 1.2 原生自绘能力（`XDraw_*`）

- `XDraw_*` 系列提供直线、矩形、椭圆、圆角矩形、文本、渐变等底层绘制原语。
- 本项目正是靠它实现了**品牌区动态渐变 + 漂浮光斑动画**、**卡片圆角背景**、**自绘标题栏**、**加载转圈**等效果。

### 1.3 29 个控件类、1,648 个封装方法

- 覆盖窗口、按钮、编辑框、列表、列表视图、树、表格、菜单、标签栏、组合框、滚动视图、字体、形状、动画、背景、布局等完整控件体系。
- 全部以 `XCGUI_*` 静态方法暴露，Java 可直接调用。

### 1.4 XML 声明式布局

- 支持 XML 布局（`<layoutPanel>` / `<windowUI>`）、样式（`style`）、资源（`.res`）、项模板（`<xc_template_list>` 等）。
- **「骨架与皮」用 XML 描述，「肉与血」用 Java 自绘/动画/事件**，两者各司其职（详见 §四）。

---

## 二、开发优势

本项目在实践中沉淀出一套「**高内聚、可复用、易维护**」的桌面 UI 开发范式，这是相对直接裸写 XCGUI 的最大开发优势。

### 2.1 XML 配置化布局 —— 骨架与皮交给声明式配置

- 页面结构、层级、命名、初始位置由 XML 描述，Java 只做「按名取句柄 + 重排 + 套样式」。
- 本项目已落地 `src/main/resources/layout/login.xml`（登录页骨架）与 `main_pages.xml`（主窗口五页骨架）。
- 结构变更无需改 Java 代码，改 XML 即可；命名约定（`登录_`、`页_` 前缀）让按名取句柄清晰可靠。

### 2.2 链式 Fluent API（`XCChainedUI`）

- 97 个 `XC*ComponentUI` 组件以链式（Builder）风格调用，代码简洁、可读性强：

```java
XCChainedUI.app(true)
        .window("登录中心", 984, 714)
        .panel(...).text(...).button(...)
        .show().run();
```

### 2.3 主题令牌 + 一键明暗切换（`ElementTheme`）

- 颜色不写死，统一走 `ElementTheme.textPrimary() / textSecondary() / background()` 等语义令牌。
- 登录窗与主窗口共享同一主题状态，**切到暗色后全局一致**；`shapeText` 等自绘文本通过主题监听器自动跟随重刷。

### 2.4 尺寸令牌集中管理（`UiMetrics`）

- 所有窗口尺寸、圆角、阴影留白、控件尺寸、排版常量集中在 `org.example.core.UiMetrics`，避免同一数值散落多处导致失配。
- 主窗口与登录窗共用 `WindowShell`，仅通过 `setTitleH()` / `setSplitX()` 等差异化。

### 2.5 可复用的无边框窗口外壳（`WindowShell`）

- 封装「无边框 + 圆角 + 投影 + 自绘标题栏 + 拖拽移动 + 边框缩放 + 内容自适应重排」，登录窗与主窗口复用同一套外壳。
- 最大化时自动隐藏阴影、圆角变直角、内容重排，窗口按钮（主题/最小化/最大化/关闭）状态随窗口状态联动。

### 2.6 命名约定 + 按名取句柄 + 缺失即抛

- XML 节点用 `name` 作为全局唯一主键，Java 侧 `XC_GetObjectByName` 按名取句柄。
- 封装 `element(name)` 方法：**缺失立即抛异常**，把「静默白屏」变成「立刻报错」，定位问题快。

### 2.7 资源 classpath 加载

- 布局资源统一放 `src/main/resources/layout/`，通过 `SystemUtils.readResourceToBytes` + `XC_LoadLayoutFromStringUtf8` 加载，不硬编码字符串、不读磁盘路径，便于打包分发。

---

## 三、JSCM 框架的优势

JscmGUI 依赖的 **Jscm-Core** 框架（`com.scm:jscm-core`）是「底层原生 + 高层服务」一体化开发框架，本应用只用到了它的 GUI 部分，但它能提供的远不止这些。

### 3.1 JNI 全量封装（非 JNA）

- 采用 **JNI 静态绑定**，4,963 个 `native` 方法集中声明，相比 JNA 运行时反射映射，调用开销更低、性能更优。
- 双架构自适应（`sun.arch.data.model` 检测 32/64 位），自动加载对应 `Jscm.dll`。

### 3.2 UI 组件引擎（97 个链式组件 + 基础设施）

- 97 个 `XC*ComponentUI` 组件覆盖基础控件、表单输入、数据展示、反馈交互、导航、数据容器、图表、图标库。
- 内置全局事件分发器（`XCUIEventDispatcher`）、全局资源回收系统（`XCUIResourceManager`，类似 Java GC）、动画引擎（`AnimationEngine` / `Easing`）、主题令牌（`ElementTheme`）。

### 3.3 多引擎全家桶

| 领域 | 能力 |
|:---|:---|
| XCGUI 炫彩界面 | 29 类、1,648 方法，Direct2D 硬件加速 |
| JadeView WebView2 | 基于 Chromium，可用 HTML/CSS/JS 构建桌面界面 |
| 锐浪报表 Grid++ | 26 类、2,842 方法，支持设计器 / 打印 / PDF / Excel 导出 |
| AI 集成 | Ollama / Coze / RunningHub / 云端 LLM，流式输出 |
| 现代 Web 服务 | Netty HTTP/WebSocket + RBAC 鉴权 + 阿里云 OSS |
| 系统级能力 | Win32 API、键鼠驱动、内存调试、反汇编等 |

### 3.4 技能库（Skills）—— AI 编码助手知识库

框架内置 `src/main/resources/skills/` 技能文档（含全栈总纲 `SKILL.md`、链式组件、JadeView、报表、AI、Lucene 等），供 AI 编码助手按提问命中加载，实现「一次写对、贴合项目约定」。

---

## 四、项目功能特性

### 4.1 登录中心（`LoginScreen`）

- **五种模式**：账号登录 / 快速登录 / 注册 / 修改密码 / 短信验证码，由顶部选项卡切换，切换时带淡入滑入过渡。
- **品牌区**：左侧动态渐变背景 + 漂浮光斑动画（`XDraw_*` 自绘 + 帧定时器）。
- **表单区**：右侧圆角卡片，输入框、按钮、返回链接均由链式组件构建。
- **登录加载遮罩**：登录成功时盖住全窗，切换到主窗口。

### 4.2 智能管理工作台（`MainWindow`）

- **顶部头部菜单**：软件名 + 搜索栏（关键词输入框 + 「搜索 | 倒三角」分体下拉）+ 用户名下拉，横跨整条。
- **左侧折叠导航菜单**：汉堡按钮折叠为图标窄栏，展开/折叠丝滑过渡，标题淡入。
- **五个正文页**：工作台 / 实时监控 / 报表统计 / 订单管理 / 系统设置，点击菜单叶子项即切换。
- **窗口最大化**：内容自适应重排，全部块位置尺寸随窗口实时变化。

### 4.3 明暗主题

- 登录窗与主窗口共用 `ElementTheme` 主题令牌，标题栏主题按钮一键切换明暗，全局一致。

---

## 五、项目结构

```
JscmGUI/
├── pom.xml                                     # Maven 构建（依赖本地 Jscm-Core.jar）
└── src/main/
    ├── java/org/example/
    │   ├── App.java                            # 程序入口（生命周期编排）
    │   ├── core/
    │   │   ├── SdkLoader.java                  # 运行库路径准备
    │   │   ├── UiMetrics.java                  # 尺寸 / 排版令牌集中管理
    │   │   └── AuthService.java                # 账号校验
    │   └── ui/
    │       ├── WindowShell.java                # 无边框圆角窗口外壳（复用）
    │       ├── LoginScreen.java                # 登录中心装配根
    │       ├── MainWindow.java                 # 智能管理工作台
    │       ├── BrandPane.java                  # 品牌区（渐变 + 光斑）
    │       ├── UiUtils.java                    # 通用件（透明 / 重排 / 圆角卡片）
    │       ├── Modes.java                      # 登录模式枚举
    │       └── form/                           # 五个独立表单模块
    │           ├── FormModule.java
    │           ├── LoginForm.java
    │           ├── QuickLoginForm.java
    │           ├── RegisterForm.java
    │           ├── ChangePasswordForm.java
    │           └── SmsCodeForm.java
    └── resources/
        └── layout/
            ├── login.xml                       # 登录页 XML 骨架
            └── main_pages.xml                  # 主窗口五页 XML 骨架
```

---

## 六、快速开始

### 6.1 前置条件

- **JDK 8**（运行库 `Jscm.dll` 依赖 JDK 8，编译产物为 Java 8 字节码）。
- 已构建 **Jscm-Core** 框架产物：`../scmJnaApi/out/artifacts/Jscm_Core_jar/Jscm-Core.jar`。

### 6.2 编译

```bash
mvn clean compile
```

### 6.3 运行

应用入口为 `org.example.App`，运行前需显式指定 `Jscm-Core.jar` 到 classpath：

```bash
java -cp "target/classes;../scmJnaApi/out/artifacts/Jscm_Core_jar/Jscm-Core.jar" org.example.App
```

> **说明**：`SdkLoader.setup()` 会准备运行库路径；`Jscm.dll` 需位于可被加载的目录（参考 Jscm-Core 框架的原生库部署说明）。

---

## 七、XML 布局与开发规范

本项目严格遵循 JSCM 框架技能库中的 GUI 规范：

- 布局资源放 `src/main/resources/layout/`，classpath 读取 + `XC_LoadLayoutFromStringUtf8` 加载。
- `<layoutPanel>` 根下**只放一个内容容器** `<layoutEleUI>`，再在其中并排多个页面。
- 全部节点 `layoutControl="false"`，位置尺寸由 Java 重排；字号与主题色由 Java 套用（XML 的 `font` 只能引用 `.res` 注册字体）。
- 详细规范与 20 个可复用案例见框架技能库 `src/main/resources/skills/SKILL.md` 第 43、44 章。

---

## 八、代码示例

以下示例均摘自本项目真实源码，展示「XML 配置骨架 + Java 管血肉」的完整开发范式。

### 8.1 程序入口（生命周期编排）

```java
public static void main(String[] args) {
    SdkLoader.setup();              // 准备 Jscm.dll 运行库路径（任何原生调用前必须先执行）
    XC_EnableResMonitor(true);      // 开启资源监控，元素句柄自动回收

    XCChainedUI.App app = XCChainedUI.app(true);   // true = 开启 Direct2D 硬件加速

    LoginScreen screen = new LoginScreen(app);
    screen.assemble();              // 装配界面（XML 骨架 + Java 血肉）
    screen.show();                  // 居中显示

    app.run();                      // 进入消息循环
    app.exit();
    System.exit(0);
}
```

### 8.2 登录表单的链式（Fluent）构建

```java
public void build(XCChainedUI.Window p, Context ctx) {
    user = p.input(0, 0, UiMetrics.CONTENT_W, UiMetrics.INPUT_H, "请输入账号 / 手机号");
    user.end();

    password = p.password(0, 56, UiMetrics.CONTENT_W, UiMetrics.INPUT_H, "请输入密码");
    password.end();

    remember = p.checkbox(0, 112, 120, 24, "记住我").checked(true).end();

    p.link(280, 112, 80, 24, "忘记密码？")
            .type(ElementTheme.Type.PRIMARY)
            .onClick(() -> ctx.switchTo(Modes.CHANGE_PASSWORD))
            .end();

    p.button(0, 154, UiMetrics.CONTENT_W, UiMetrics.BTN_H, "登 录")
            .type(XCButtonComponentUI.Type.PRIMARY)
            .onClick(handle -> submit(ctx))
            .end();
}
```

### 8.3 XML 布局骨架（`src/main/resources/layout/login.xml`）

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!--炫彩界面库-布局面板文件-->
<head />
<layoutPanel name="登录页容器" rect="0,0,984,714" widthT="984" heightT="714"
             showT="true" transparent="true" layoutControl="false">
    <layoutEleUI name="登录页内容" rect="0,0,984,714" showT="true"
                 transparent="true" layoutControl="false">
        <layoutEleUI name="登录_品牌区" rect="12,12,400,690" showT="true"
                     transparent="true" layoutControl="false">
            <layoutEleUI name="登录_品牌文案块" rect="0,180,400,330" showT="true"
                         transparent="true" layoutControl="false" />
        </layoutEleUI>
        <layoutEleUI name="登录_表单区" rect="412,12,560,690" showT="true"
                     transparent="true" layoutControl="false">
            <layoutEleUI name="登录_表单列" rect="100,48,360,642" showT="true"
                         transparent="true" layoutControl="false">
                <shapeText name="登录_标题" content="欢迎回来" rect="0,44,360,34"
                           textColor="#FF1F2329" textAlign="DT_LEFT,DT_VCENTER,DT_SINGLELINE" layoutControl="false" />
                <shapeText name="登录_副标题" content="请使用您的账号与密码登录系统" rect="0,82,360,22"
                           textColor="#FF646A73" textAlign="DT_LEFT,DT_VCENTER,DT_SINGLELINE" layoutControl="false" />
            </layoutEleUI>
        </layoutEleUI>
    </layoutEleUI>
</layoutPanel>
```

### 8.4 按名取句柄 + 缺失即抛（`name` 为全局主键）

```java
private void loadLayout(int parent) {
    loginRoot = XCGUI_Core.XC_LoadLayoutFromStringUtf8(readLayoutXml(LOGIN_XML), parent, 0);
    if (loginRoot <= 0) throw new IllegalStateException("登录页 XML 布局加载失败");

    brandPanelH = element("登录_品牌区");
    formPanelH  = element("登录_表单区");
    titleText   = element("登录_标题");
}

/** 按名取 XML 节点句柄，未命中立即抛异常——静默拿到 0 会让页面白屏且难定位。 */
private static int element(String name) {
    int h = XCGUI_Core.XC_GetObjectByName(name);
    if (h <= 0) throw new IllegalStateException("XML 布局缺少节点（name=" + name + "）");
    return h;
}

/** 从 classpath 读取 UTF-8 布局资源，缺失即抛。 */
private static String readLayoutXml(String path) {
    byte[] data = SystemUtils.readResourceToBytes(path);
    if (data == null) throw new IllegalStateException("找不到布局资源：" + path);
    return new String(data, StandardCharsets.UTF_8);
}
```

### 8.5 主题令牌 + 明暗切换监听

```java
// shapeText 不参与 ElementTheme 的自动刷新，主题切换时手动重刷 + 重绘
ElementTheme.addThemeListener(mode -> {
    XCGUI_Shape.XShapeText_SetTextColor(titleText, ElementTheme.textPrimary());
    XCGUI_Shape.XShapeText_SetTextColor(subtitleText, ElementTheme.textSecondary());
    XCGUI_Window.XWnd_Redraw(window.handle(), true);
});
```

### 8.6 自绘转圈动画（`XDraw_*` 逐帧绘制）

```java
private static void paintSpinner(long hDraw, int w, int h) {
    long accent = ElementTheme.palette(ElementTheme.Type.PRIMARY).base;
    // 库内颜色按 0xAABBGGRR 存放：低字节才是红，拆分量必须按这个顺序
    int red = (int) (accent & 0xFF);
    int green = (int) ((accent >> 8) & 0xFF);
    int blue = (int) ((accent >> 16) & 0xFF);
    int cx = w / 2, cy = h / 2 + SPIN_CENTER_DY;
    float turn = (System.currentTimeMillis() % SPIN_PERIOD_MS) / (float) SPIN_PERIOD_MS;
    XDraw_EnableSmoothingMode(hDraw, true);
    for (int i = 0; i < SPIN_DOTS; i++) {
        double angle = (i / (double) SPIN_DOTS + turn) * Math.PI * 2;
        int dx = (int) Math.round(Math.cos(angle) * SPIN_RADIUS);
        int dy = (int) Math.round(Math.sin(angle) * SPIN_RADIUS);
        int alpha = Math.round(255 * (1f - (float) i / SPIN_DOTS));
        XDraw_SetBrushColor(hDraw, ColorUtils.RGBA(red, green, blue, alpha));
        XDraw_FillEllipse(hDraw, new TagRect(cx + dx - SPIN_DOT_R, cy + dy - SPIN_DOT_R,
                cx + dx + SPIN_DOT_R, cy + dy + SPIN_DOT_R));
    }
}
```

---

## 九、许可

依赖框架 Jscm-Core 的许可见其 `LICENSE` 文件。