# ELEControls

**Repository Path**: jinyutou/elecontrols

## Basic Information

- **Project Name**: ELEControls
- **Description**: 基于 Element UI Plus 设计体系的 WinForms 自定义组件库，采用纯 GDI+ 绘制，提供 123 个开箱即用的主题化控件，覆盖基础、表单、数据展示、导航、反馈、布局、图表、工业控制八大类。
- **Primary Language**: C#
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-23
- **Last Updated**: 2026-06-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ELEControls

基于 **Element UI Plus** 设计体系的 **WinForms 自定义组件库**，采用纯 GDI+ 绘制，提供 **123 个**开箱即用的主题化控件，覆盖基础、表单、数据展示、导航、反馈、布局、图表、工业控制八大类。

> 免费开源 | .NET 8 + .NET Framework 4.8 | 纯 GDI+ | VS 设计器友好 | 12 套内置主题

---

## 特性

- **Element UI Plus 风格** — 完整移植 Web 端设计令牌（色彩、圆角、间距、阴影）到桌面端
- **纯 GDI+ 渲染** — 不依赖第三方绘图库，双缓冲 + 抗锯齿，流畅无闪烁
- **主题系统** — 内置 12 套配色方案，支持运行时一键切换，可自定义扩展
- **DPI 自适应** — 内置 `ELEDPIScale` 缩放因子，高分屏下自动适配
- **VS 设计器支持** — 所有控件均可在 Visual Studio 可视化设计器中拖放使用
- **统一命名空间** — 所有类型统一在 `ELE.UI` 命名空间下，引用即用
- **工业控件** — 提供仪表盘、液位罐、风机、泵、阀门等 SCADA 级工控组件

---

## 环境要求

| 项目 | 要求 |
|------|------|
| 框架 | .NET 8.0 (net8.0-windows) **或** .NET Framework 4.8 (net48) |
| IDE | Visual Studio 2022 17.8+ |
| 系统 | Windows 10 / 11 |
| 许可 | MulanPSL-2.0 |

---

## 快速开始

### 1. 引用项目

将 `src\ELEControls` 项目添加到你的解决方案中，然后在 WinForms 项目里添加项目引用：

```xml
<ProjectReference Include="..\ELEControls\ELEControls.csproj" />
```

### 2. 引入命名空间

```csharp
using ELE.UI;
```

### 3. 使用控件

**代码方式：**

```csharp
var btn = new ELEButton
{
    Text = "主要按钮",
    Type = ELEComponentType.Primary,
    Size = ELEComponentSize.Default,
    Location = new Point(20, 20)
};
this.Controls.Add(btn);
```

**设计器方式：**

编译项目后，所有 ELE 控件会自动出现在 VS 工具箱的 **ELEControls** 分类中，直接拖放到窗体即可。

### 4. 切换主题

```csharp
// 设置全局主题
ELEStyles.SetStyle(ELEStyle.Blue);   // 内置主题
ELEStyles.SetStyle(ELEStyle.Dark);   // 暗色主题

// 可选主题: Blue, Green, Red, Orange, Purple, Dark, Gray,
//           Cyan, Pink, Brown, Black, White
```

---

## 项目结构

```
src/ELEControls/
├── Core/                    # 核心基础
│   ├── ELEControl.cs        # 主基类 (继承 Control)
│   ├── ELEUserControl.cs    # 复合基类 (继承 UserControl)
│   ├── ELEEnums.cs          # 枚举定义
│   ├── ELEGlobal.cs         # 全局常量
│   └── IELEStyle.cs         # 主题接口
├── Style/                   # 主题样式
│   ├── ELEColor.cs          # 颜色常量
│   ├── ELEBaseStyle.cs      # 基础样式 (150+ 虚属性)
│   ├── ELEStyleColor.cs     # 12 套主题实现
│   ├── ELEStyles.cs         # 全局主题管理器
│   └── ELEDPIScale.cs       # DPI 缩放
├── Common/                  # 公共工具
│   └── ELEGDI.cs            # GDI+ 扩展方法
├── Forms/                   # 窗体
│   ├── ELEBaseForm.cs       # 基础窗体 (自定义标题栏)
│   ├── ELEForm.cs           # 标准窗体
│   ├── ELEMessageForm.cs    # 消息弹窗
│   ├── ELEDialog.cs         # 对话框
│   └── ELEDrawer.cs         # 抽屉面板
└── Controls/                # 控件 (按分类)
    ├── Basic/               # 基础控件
    ├── Form/                # 表单控件
    ├── Data/                # 数据展示
    ├── Navigation/          # 导航控件
    ├── Feedback/            # 反馈控件
    ├── Layout/              # 布局容器
    ├── Chart/               # 图表控件
    └── Industrial/          # 工业控件
```

---

## 组件一览

### 基础控件 (5)

| 控件 | 类名 | 说明 |
|------|------|------|
| 按钮 | `ELEButton` | 支持 Primary/Success/Warning/Danger/Info 五种语义类型，Round/Circle 形状 |
| 图片按钮 | `ELEImageButton` | 支持图标+文字组合按钮 |
| 标签 | `ELELabel` | 主题化文本标签 |
| 分割线 | `ELELine` | 水平/垂直分割线 |
| 链接 | `ELELink` | 主题化超链接文本 |

### 表单控件 (29)

| 控件 | 类名 | 说明 |
|------|------|------|
| 文本框 | `ELETextBox` | 带图标、清除按钮的输入框 |
| 多行文本 | `ELETextArea` | 多行输入框，支持字数统计 |
| 密码框 | `ELEPasswordBox` | 密码输入，支持显示/隐藏切换 |
| 搜索框 | `ELESearchBox` | 带搜索图标和清除按钮 |
| 数字文本框 | `ELENumericTextBox` | 支持格式验证的数字输入 |
| 数字输入 | `ELEInputNumber` | 带 +/- 按钮的数字调节器 |
| 复选框 | `ELECheckBox` | 主题化复选框 |
| 复选框组 | `ELECheckBoxGroup` | 复选框组容器 |
| 单选按钮 | `ELERadioButton` | 主题化单选按钮 |
| 单选组 | `ELERadioGroup` | 单选按钮组容器 |
| 开关 | `ELESwitch` | 滑动开关，支持自定义文字 |
| 下拉框 | `ELEComboBox` | 主题化下拉选择框 |
| 级联选择 | `ELECascader` | 多级联动选择器 |
| 树选择 | `ELETreeSelect` | 下拉树形选择器 |
| 日期选择 | `ELEDatePicker` | 日期选择器，带日历弹窗 |
| 时间选择 | `ELETimePicker` | 时间选择器 |
| 滑块 | `ELETrackBar` | 基础滑块 |
| 高级滑块 | `ELESlider` | 带刻度标记的滑块 |
| 范围滑块 | `ELERangeSlider` | 双滑块范围选择 |
| 评分 | `ELERate` | 星级评分 |
| 颜色选择 | `ELEColorPicker` | 颜色选择器 |
| 色轮 | `ELEColorWheel` | HSV 色轮选色器 |
| 文件上传 | `ELEUpload` | 文件上传，支持拖放 |
| 自动补全 | `ELEAutoComplete` | 输入自动补全建议 |
| 标签输入 | `ELETagInput` | 标签式多值输入 |
| 提及输入 | `ELEMention` | @提及输入框 |
| 分段器 | `ELESegmented` | iOS 风格分段选择 |
| 虚拟键盘 | `ELEKeyboard` | 数字/全键盘虚拟键盘 |
| 富文本 | `ELERichTextBox` | 主题化富文本编辑器 |

### 数据展示控件 (29)

| 控件 | 类名 | 说明 |
|------|------|------|
| 标签 | `ELETag` | 语义标签，支持 Light/Dark/Plain 效果 |
| 徽章 | `ELEBadge` | 数字/圆点徽章 |
| 头像 | `ELEAvatar` | 图片/文字头像 |
| 卡片 | `ELECard` | 信息卡片容器 |
| 数据表格 | `ELEDataGridView` | 主题化数据网格 |
| 树视图 | `ELETreeView` | 主题化树形控件 |
| 列表框 | `ELEListBox` | 主题化列表选择 |
| 分页 | `ELEPagination` | 分页导航 |
| 进度条 | `ELEProgressBar` | 线性进度条 |
| 环形进度 | `ELECircleProgressBar` | 环形/仪表盘进度条 |
| 滚动条 | `ELEScrollBar` | 主题化滚动条 |
| 时间线 | `ELETimeline` | 垂直时间线 |
| 描述列表 | `ELEDescriptions` | 键值对描述列表 |
| 空状态 | `ELEEmpty` | 空数据占位提示 |
| 结果页 | `ELEResult` | 操作结果反馈页 |
| 统计值 | `ELEStatistic` | 数值统计展示 |
| 水印 | `ELEWatermark` | 页面水印覆盖 |
| 骨架屏 | `ELESkeleton` | 加载占位骨架 |
| 折叠面板 | `ELECollapse` | 手风琴折叠面板 |
| 穿梭框 | `ELETransfer` | 双列表穿梭选择 |
| 日历 | `ELECalendar` | 月份日历视图 |
| 图片 | `ELEImage` | 图片展示，支持 Fit 模式与预览 |
| 走马灯 | `ELECarousel` | 轮播图，支持自动播放 |
| 分割线 | `ELEDivider` | 带文字内容的分割线 |
| 滚动文字 | `ELEScrollingText` | 跑马灯文字效果 |
| 时钟 | `ELEClock` | 模拟时钟 |
| 倒计时 | `ELECountDown` | 倒计时计时器 |
| 无限滚动 | `ELEInfiniteScroll` | 滚动加载容器 |
| 虚拟滚动 | `ELEVirtualScroll` | 大数据虚拟列表 |

### 导航控件 (13)

| 控件 | 类名 | 说明 |
|------|------|------|
| 选项卡 | `ELETabControl` | 主题化选项卡 |
| 面包屑 | `ELEBreadcrumb` | 面包屑导航 |
| 导航菜单 | `ELENavMenu` | 侧边/顶部导航菜单 |
| 下拉菜单 | `ELEDropdown` | 下拉菜单，支持分割按钮 |
| 步骤条 | `ELESteps` | 步骤进度导航 |
| 工具栏 | `ELEToolStrip` | 主题化工具栏 |
| 菜单栏 | `ELEMenuStrip` | 主题化菜单栏 |
| 状态栏 | `ELEStatusStrip` | 主题化状态栏 |
| 右键菜单 | `ELEContextMenuStrip` | 主题化上下文菜单 |
| 页头 | `ELEHeaderPanel` | 带返回按钮的页面头部 |
| 回到顶部 | `ELEBackTop` | 浮动回到顶部按钮 |
| 锚点导航 | `ELEAnchor` | 锚点定位导航 |
| 小地图 | `ELEMiniMap` | 可滚动容器缩略导航 |

### 反馈控件 (7)

| 控件 | 类名 | 说明 |
|------|------|------|
| 提示 | `ELEAlert` | 内联警告/提示条 |
| 通知 | `ELENotification` | 桌面通知弹窗 (静态方法调用) |
| 加载 | `ELELoading` | 全屏/局部加载遮罩 |
| 消息条 | `ELEMessageBar` | 顶部消息提示条 |
| 气泡提示 | `ELEPopover` | 气泡卡片弹出层 |
| 文字提示 | `ELEToolTip` | 悬浮文字提示 |
| 固钉 | `ELEAffix` | 元素固定定位 |

### 布局控件 (14)

| 控件 | 类名 | 说明 |
|------|------|------|
| 面板 | `ELEPanel` | 基础面板容器 |
| 标题面板 | `ELETitlePanel` | 带标题的面板 |
| 分组框 | `ELEGroupBox` | 主题化分组框 |
| 主框架 | `ELEMainFrame` | 侧栏+顶栏+内容区布局 |
| 栅格行 | `ELERow` | 栅格系统行容器 |
| 间距容器 | `ELESpace` | 自动间距布局 |
| 布局容器 | `ELEContainer` | Element 风格布局容器 |
| 页脚 | `ELEFooter` | 页面底部容器 |
| 侧栏 | `ELEAside` | 可折叠侧边栏 |
| 仪表盘 | `ELEDashboard` | 卡片网格仪表盘布局 |
| 分割面板 | `ELESplitContainer` | 主题化分割面板 |
| 流式布局 | `ELEFlowLayoutPanel` | 主题化流式布局 |
| 表格布局 | `ELETableLayoutPanel` | 主题化表格布局 |
| 分页容器 | `ELEPage` | 多页面切换容器 |

### 窗体 (5)

| 控件 | 类名 | 说明 |
|------|------|------|
| 基础窗体 | `ELEBaseForm` | 自定义标题栏窗体基类 |
| 标准窗体 | `ELEForm` | 通用主题窗体 |
| 消息窗体 | `ELEMessageForm` | 消息弹窗 (替代 MessageBox) |
| 对话框 | `ELEDialog` | 模态对话框 |
| 抽屉 | `ELEDrawer` | 侧滑抽屉面板 |

### 图表控件 (8)

| 控件 | 类名 | 说明 |
|------|------|------|
| 折线图 | `ELELineChart` | 多系列折线图，支持平滑曲线 |
| 柱状图 | `ELEBarChart` | 多系列柱状图，支持堆叠 |
| 饼图 | `ELEPieChart` | 饼图/环形图 |
| 面积图 | `ELEAreaChart` | 面积填充图 |
| 散点图 | `ELEScatterChart` | 散点图 |
| 雷达图 | `ELERadarChart` | 雷达/蛛网图 |
| 漏斗图 | `ELEFunnelChart` | 漏斗图 |
| 甘特图 | `ELEGanttBar` | 甘特图，支持滚动 |

### 工业控件 (13)

| 控件 | 类名 | 说明 |
|------|------|------|
| 仪表盘 | `ELEMeter` | 指针式仪表 |
| 高级仪表 | `ELEGauge` | 多段彩色仪表 |
| LED 标签 | `ELELedLabel` | LED 数码管显示 |
| 管道 | `ELEPipe` | 工业管道，支持流向动画 |
| 阀门 | `ELEValve` | 工业阀门，开/关状态 |
| 温度计 | `ELEThermometer` | 温度计显示 |
| 波形图 | `ELEWaveChart` | 实时波形/趋势图 |
| 液位罐 | `ELETank` | 液位显示，带波纹动画 |
| 风机 | `ELEFan` | 旋转风机，带叶片动画 |
| 水泵 | `ELEPump` | 工业水泵，带叶轮动画 |
| 设备块 | `ELEProcessDevice` | 工艺流程设备块 |
| 信号灯 | `ELESignalLight` | 多色信号灯，支持闪烁 |
| 电池 | `ELEBattery` | 电池电量显示 |

---

## 色彩体系

ELEControls 完整移植了 Element UI Plus 的语义色彩系统：

| 语义 | 色值 | 用途 |
|------|------|------|
| Primary | `#409EFF` | 主操作、链接、选中态 |
| Success | `#67C23A` | 成功状态、确认操作 |
| Warning | `#E6A23C` | 警告信息、需要注意 |
| Danger  | `#F56C6C` | 危险操作、错误状态 |
| Info    | `#909399` | 辅助信息、次要文本 |

每个主色调自动生成 16 级渐变色阶（Light-1 到 Light-9、Dark-2），用于悬停、按下、禁用等状态。

---

## 主题切换

### 内置主题

```csharp
// 在应用启动时设置全局主题
ELEStyles.SetStyle(ELEStyle.Blue);
```

支持 12 套主题：`Blue` `Green` `Red` `Orange` `Purple` `Dark` `Gray` `Cyan` `Pink` `Brown` `Black` `White`

### 自定义主题

继承 `ELEBaseStyle` 覆盖颜色属性即可创建自定义主题：

```csharp
public class MyCustomStyle : ELEBaseStyle
{
    public override Color PrimaryColor => ColorTranslator.FromHtml("#6366F1");
    public override Color SuccessColor => ColorTranslator.FromHtml("#22C55E");
    // 覆盖需要自定义的属性 (共 150+ 可覆盖属性)
}

// 应用自定义主题
ELEStyles.SetStyle(new MyCustomStyle());
```

---

## 渲染架构

所有控件采用**模板方法模式**渲染管线，继承自 `ELEControl` 或 `ELEUserControl`：

```
OnPaint
  ├── OnPaintFill()    → 填充背景
  ├── OnPaintRect()    → 绘制边框
  └── OnPaintFore()    → 绘制前景内容
```

自定义控件只需继承基类并覆盖对应方法：

```csharp
public class MyControl : ELEControl
{
    protected override void OnPaintFill(Graphics g, GraphicsPath path)
    {
        // 自定义背景绘制
    }

    protected override void OnPaintFore(Graphics g, GraphicsPath path)
    {
        // 自定义前景绘制
    }
}
```

### 状态管理

控件自动管理以下交互状态，每种状态对应独立的颜色组（FillColor / RectColor / ForeColor）：

| 状态 | 说明 |
|------|------|
| Normal | 默认状态 |
| Hover | 鼠标悬停 |
| Press | 鼠标按下 |
| Selected | 选中状态 |
| Disabled | 禁用状态 |
| ReadOnly | 只读状态 |
| Focused | 获得焦点 |

---

## 枚举类型参考

### ELEComponentType — 语义类型

```csharp
Default | Primary | Success | Warning | Danger | Info
```

### ELEComponentSize — 组件尺寸

```csharp
Large (40px) | Default (32px) | Small (24px)
```

### ELEButtonShape — 按钮形状

```csharp
Default | Round | Circle
```

### ELEPlacement — 弹出位置

```csharp
Top | TopStart | TopEnd | Bottom | BottomStart | BottomEnd
Left | LeftStart | LeftEnd | Right | RightStart | RightEnd
```

### ELEDirection — 方向

```csharp
Up | Down | Left | Right
```

---

## 使用示例

### 主题按钮组

```csharp
var btnPrimary = new ELEButton { Text = "主要", Type = ELEComponentType.Primary };
var btnSuccess = new ELEButton { Text = "成功", Type = ELEComponentType.Success };
var btnWarning = new ELEButton { Text = "警告", Type = ELEComponentType.Warning };
var btnDanger  = new ELEButton { Text = "危险", Type = ELEComponentType.Danger };
var btnInfo    = new ELEButton { Text = "信息", Type = ELEComponentType.Info };
```

### 表单输入

```csharp
var txtName = new ELETextBox
{
    PlaceholderText = "请输入姓名",
    Size = ELEComponentSize.Default,
    Width = 240
};

var cboCity = new ELEComboBox
{
    PlaceholderText = "请选择城市",
    Size = ELEComponentSize.Default
};
cboCity.Items.AddRange(new[] { "北京", "上海", "广州", "深圳" });
```

### 数据表格

```csharp
var grid = new ELEDataGridView
{
    Dock = DockStyle.Fill,
    ShowCheckBoxes = true
};
grid.Columns.Add("Name", "姓名");
grid.Columns.Add("Age", "年龄");
grid.Rows.Add("张三", 28);
```

### 消息通知

```csharp
// 顶部消息条
ELEMessageBar.Show("操作成功！", ELEComponentType.Success);

// 右下角通知
ELENotification.Show("系统通知", "您有新的消息，请及时查看。");

// 模态消息框
ELEMessageForm.Show("确定删除？", "提示", MessageBoxButtons.YesNo);
```

### 图表

```csharp
var chart = new ELELineChart { Dock = DockStyle.Fill };
chart.Series.Add(new ELEChartSeries
{
    Name = "销售额",
    Data = new List<double> { 120, 200, 150, 80, 70, 110, 130 }
});
chart.Categories = new List<string>
{
    "周一", "周二", "周三", "周四", "周五", "周六", "周日"
};
```

### 工业控件

```csharp
// 仪表盘
var meter = new ELEMeter
{
    Value = 75.5,
    MinValue = 0,
    MaxValue = 100,
    Unit = "℃"
};

// 液位罐
var tank = new ELETank
{
    Value = 65,
    MaxValue = 100,
    ShowWave = true
};

// 阀门
var valve = new ELEValve
{
    IsOpen = true,
    Direction = ELEDirection.Right
};
```

---

## 构建

```bash
dotnet build src\ELEControls\ELEControls.csproj -c Release
```

输出程序集位于：
- `src\ELEControls\bin\Release\net8.0-windows\ELEControls.dll` (.NET 8.0)
- `src\ELEControls\bin\Release\net48\ELEControls.dll` (.NET Framework 4.8)

---

## NuGet 包

本项目已发布到 NuGet，你可以直接通过 NuGet 包管理器安装：

### 安装方式

**Package Manager:**
```powershell
Install-Package ELEControls
```

**.NET CLI:**
```bash
dotnet add package ELEControls
```

**PackageReference:**
```xml
<PackageReference Include="ELEControls" Version="1.1.6" />
```

### 发布 NuGet 包

如果你想自己构建和发布 NuGet 包，请参考 [NuGet 发布指南](./NUGET.md)

快速开始：
```powershell
# 获取 API Key 后，一行命令完成发布
.\nuget-publish.ps1 -ApiKey "your-api-key"
```

---

## 许可证

本项目基于 [木兰宽松许可证 第2版 (MulanPSL-2.0)](http://license.coscl.org.cn/MulanPSL2) 开源。