Zhouyaowei.ZYWControls 1.0.36

ZYWControls - 增强型WinForm控件库

ZYWControls 是一套基于 .NET 9.0 Windows Forms 的增强型控件库，提供多种高频使用的自定义控件。控件支持可视化设计器配置、丰富的外观自定义和实用的数据处理功能，帮助开发者快速构建美观、高效的WinForm应用。

🔧 安装说明

通过 NuGet 包管理器快速安装：

Install-Package Zhouyaowei.ZYWControls

或通过 .NET CLI 安装：

dotnet add package Zhouyaowei.ZYWControls

环境要求

• .NET 9.0 及以上
• Windows 操作系统（依赖 Windows Forms）
• 支持设计器的 IDE（Visual Studio 2022+ 推荐）

📋 控件清单及核心功能

1. ZYWButton - 圆角呼吸灯按钮

• 支持自定义圆角半径（0-任意整数）
• 三种状态渐变颜色配置（默认/悬停/按下）
• 可选呼吸灯动画（可调节速度、幅度）
• 内置多类型数据绑定（字符串/整型/Action委托等）
• 内置 Material Icons (Google) 图标显示：字体与映射表作为嵌入资源打包，无需安装字体即可显示图标。支持「图标名称」（如 home）或「Unicode 码位」（如 0xE88A）两种方式指定，图标颜色随按钮状态（悬停/按下/禁用）变化，并支持图标与文本的左/右/上/下排版
• 图标可视化选择器：IconName 属性支持下拉选择——搜索中英文名称、记录最近使用、一键打开大窗口浏览全部 2234 个图标，不必记忆图标名或编码（详见 2.1 节）

2. ZYWComboBox - 增强型下拉框

• 支持自定义边框（颜色、粗细、各边可见性）
• 键值对（KeyValueItem）数据绑定，支持附加对象
• 提供DataTable/列表数据加载、选中项快速定位
• 线程安全的Items集合操作，避免UI卡顿

3. ZYWDatePicker - 智能日期选择器

• 自定义边框样式与ZYWTextBox保持视觉统一
• 预设8种默认日期（当天/本周首尾/本月首尾等）
• 支持自定义日期偏移（当前日期±N天）
• 天级时间戳转换（基于指定起始日期）

4. ZYWMemoBox - 多行文本框

• 强制多行模式，支持回车/制表符输入
• 自定义边框+滚动条配置
• 文本插入/追加操作，自动清除超限内容
• 支持TXT/HTML文件读写（自动识别编码）

5. ZYWTabControl - 圆角标签页

• 标签圆角半径、边框颜色/粗细自定义
• 支持标签渐变背景（默认/选中状态分别配置）
• 标签宽高固定设置，避免自适应混乱
• 高质量绘制，无闪烁、无锯齿
• 内置 Material Icons 标签图标：通过 TabIcons 按 TabPages 顺序设置各标签图标（逗号分隔的名称或码位），TabIconSize/TabIconColor 控制大小与颜色，图标显示在文字左侧并整体居中
• 标签 ToolTip 提示：通过 TabToolTips（逗号分隔，按 TabPages 顺序）为每个标签配置鼠标悬停提示

6. ZYWTableView - 高级表格控件

• 奇偶行交替背景色，选中行高亮样式自定义
• 行号显示控制（显示/隐藏、宽度调整）
• 列配置持久化（保存/加载/重置列布局）
• 支持DataTable绑定，选中行数据快速提取
• 列编辑功能（通过配置文件调整表头/可见性/冻结状态）
• 单元格 ToolTip 提示：订阅 CellToolTipTextNeeded 事件设置 e.ToolTipText，即可为不同单元格显示悬停提示

7. ZYWTextBox - 增强型单行文本框

• 支持占位符提示（文本/颜色自定义）
• 四种输入类型限制（整型/小数/正数等）
• 自定义边框样式，支持单独控制各边显示
• 禁止粘贴非法内容，输入实时校验

8. ZYWFormTabControl - 窗体标签控件

• 全方位样式自定义
• 人性化交互功能
• 窗体嵌入核心能力
• 设计器友好性
• 内置 Material Icons 标签图标：同 ZYWTabControl，支持 TabIcons/TabIconSize/TabIconColor 为各窗体标签加图标
• 标签 ToolTip 提示：同 ZYWTabControl，支持 TabToolTips 为各窗体标签配置鼠标悬停提示

9. ZYWPlayPictureBox - 图片播放控件

• 灵活的播放控制
• 状态自动切换
• 高性能与安全性
• 资源友好

10. ZYWToggleSwitch - 开关控件

• 基础交互能力
• 高度可定制化样式
• 开发友好特性
• 事件支持

🎨 快速使用示例

1. ZYWButton 呼吸灯按钮示例

var btn = new ZYWControls.ZYWButton();
btn.Text = "提交";
btn.CornerRadius = 10; // 圆角半径
btn.BreathingEffectActive = true; // 启用呼吸灯
btn.BreathingInterval = 30; // 动画流畅度
btn.BreathingChange = 40; // 颜色变化幅度
btn.Click += (s, e) => MessageBox.Show("按钮点击触发");
this.Controls.Add(btn);

2. ZYWButton 显示 Material Icons 图标示例

var btn = new ZYWControls.ZYWButton();
btn.Text = "首页";
// 方式一：使用图标名称（内置 2234 个图标）。
//         设计器中：选中 IconName 属性，点击右侧下拉箭头即可打开「图标选择器」可视化挑选
btn.IconName = "home";
// 方式二：或直接使用 Unicode 码位（优先级高于 IconName），适合已知编码时快速输入
// btn.IconCode = 0xE88A;
btn.IconSize = 18;                       // 图标字号(pt)
btn.IconColor = Color.White;             // 图标颜色（Color.Transparent 时跟随文字色）
btn.IconPosition = ZYWControls.IconPosition.Left; // 图标位置：Left/Right/Top/Bottom
btn.IconGap = 6;                         // 图标与文本间距(px)
this.Controls.Add(btn);

// 运行时也让用户自己挑图标（返回 null=取消，string.Empty=用户清除图标）
string? picked = ZYWControls.MaterialIconPickerForm.ShowPicker(btn.IconName, this);
if (picked != null) btn.IconName = picked;

2.1 图标选择器（可视化挑选，无需记忆名称）

IconName 属性自带下拉编辑器，无需再手写编码：

• 搜索：支持英文名称（home）与中文关键词（铃铛、通知、购物车），内置 497 条常用中文别名；空格分词，多词需全部命中
• 最近使用：自动记录最近选过的图标，跨项目持久化保存，日常复用基本一次点击完成
• 浏览全部…：打开 1000×700 的大窗口通览全部 2234 个图标，下拉面板本身也可拖动边框放大
• 快捷键：↑↓←→ 移动、Enter 确认、Esc 取消、滚轮翻页
• 属性预览：属性窗口左侧会直接画出该图标的字形预览

工具方法（MaterialIcon）同时也公开了检索能力，可自行扩展 UI：

// 全部图标：MaterialIcon.AllIcons
IReadOnlyList<ZYWControls.MaterialIconItem> icons = ZYWControls.MaterialIcon.Search("齿轮");
foreach (var item in icons)
    Console.WriteLine($"{item.Name} {item.Aliases} 0x{(int)item.Char:X4}");

也可以直接使用工具类 MaterialIcon 在其他控件（如 ZYWTabControl）中绘制图标：

using (var font = ZYWControls.MaterialIcon.CreateFont(20))
using (var brush = new SolidBrush(Color.Black))
{
    e.Graphics.DrawString(ZYWControls.MaterialIcon.ParseIcon("settings").ToString(), font, brush, x, y);
}

3. ZYWTabControl / ZYWFormTabControl 标签图标示例

var tab = new ZYWControls.ZYWTabControl();
tab.TabPages.Add("首页");
tab.TabPages.Add("设置");
tab.TabPages.Add("关于");
// 按 TabPages 顺序指定图标（名称或码位，逗号分隔），空项表示不显示图标
tab.TabIcons = "home,settings,info";
// 或混合使用码位： tab.TabIcons = "home,0xE8B8,info";
tab.TabIconSize = 14;                       // 图标字号(pt)
tab.TabIconColor = Color.Transparent;       // Transparent 时跟随标签文字颜色
this.Controls.Add(tab);

4. ZYWTableView 表格数据绑定示例

// 1. 创建表格控件
var tableView = new ZYWControls.ZYWTableView();
tableView.Dock = DockStyle.Fill;
tableView.RowOddBackColor = Color.White;
tableView.RowEvenBackColor = Color.FromArgb(245, 245, 245);

// 2. 准备测试数据
var dt = new DataTable();
dt.Columns.Add("ID", typeof(int));
dt.Columns.Add("Name", typeof(string));
dt.Rows.Add(1, "测试数据1");
dt.Rows.Add(2, "测试数据2");

// 3. 绑定数据
var result = tableView.LoadData(dt);
if (!result.isok)
{
    MessageBox.Show(result.msg);
}

this.Controls.Add(tableView);

5. 控件 ToolTip 提示信息示例

所有 ZYW 控件均内置 ToolTipText 属性，鼠标悬停即可显示提示信息（无需额外添加 ToolTip 组件）：

var btn = new ZYWControls.ZYWButton();
btn.Text = "保存";
btn.ToolTipText = "点击保存当前修改"; // 鼠标悬停时显示提示

var tab = new ZYWControls.ZYWTabControl();
tab.TabPages.Add("首页");
tab.TabPages.Add("设置");
// 各标签的提示（逗号分隔，按 TabPages 顺序，空项无提示）
tab.TabToolTips = "返回首页,打开系统设置";

this.Controls.Add(btn);
this.Controls.Add(tab);

特殊能力：

• TabControl 系列（ZYWTabControl / ZYWFormTabControl）额外支持 TabToolTips：逗号分隔的标签提示，鼠标移到对应标签时自动切换显示。
• ZYWTableView 额外支持单元格提示：订阅 CellToolTipTextNeeded 事件，在事件中设置 e.ToolTipText 即可按单元格显示提示：

tableView.CellToolTipTextNeeded += (s, e) =>
{
    if (e.RowIndex >= 0 && e.ColumnIndex >= 0)
    {
        e.ToolTipText = $"第 {e.RowIndex + 1} 行，第 {e.ColumnIndex + 1} 列";
    }
};

• 支持 ToolTipText 的控件：ZYWButton、ZYWToggleSwitch、ZYWPicCheckBox、ZYWPlayPictureBox、ZYWTabControl、ZYWFormTabControl、ZYWTextBox、ZYWMemoBox、ZYWRichTextBox、ZYWComboBox、ZYWDatePicker、ZYWTableView。

3. ZYWTextBox 带占位符和输入限制

var txt = new ZYWControls.ZYWTextBox();
txt.Placeholder = "请输入正数（最多2位小数）";
txt.PlaceholderColor = Color.LightGray;
txt.InputType = ZYWControls.ZYWTextBox.InputDataType.正数小数;
txt.BorderBottomVisble = true; // 仅显示底边框
txt.BorderColor = Color.FromArgb(0, 100, 180);
this.Controls.Add(txt);

⚙️ 设计器支持

所有控件的自定义属性均已分类整理，在Visual Studio设计器中可直接配置：

• 外观扩展：边框、颜色、圆角等样式属性
• 数据扩展：默认值、输入限制、数据绑定等
• 动画效果：仅ZYWButton的呼吸灯相关配置

属性修改后实时生效，无需手动编写代码刷新。

📌 版本信息

• 当前版本：1.0.10
• 更新日志：
  • v1.0.10：包含10种核心控件
  • 支持设计器可视化配置
  • 完善的异常处理和资源释放

🤝 反馈与贡献

• 若发现BUG或有功能需求，请提交Issue
• 欢迎Fork仓库，提交Pull Request完善控件功能