syncfusion-winforms-textbox

实现 TextBoxes（TextBoxExt）

适用于 Windows Forms 的增强型文本框控件，提供自定义边框样式、Office 主题、多行文本支持、字符大小写转换、溢出指示器以及全面的外观自定义功能。

何时使用此技能

在以下情况下使用此技能：

• 增强型 TextBox：使用带样式和主题支持的替代控件替换标准 TextBox
• 自定义边框：应用自定义边框颜色、3D 样式和边框边配置
• Office 主题：使文本框外观与 Office 2016/2019 或 Metro 应用主题一致
• 多行文本：显示支持自动换行、滚动条和溢出指示器的多行文本
• 文本格式：控制字符大小写（大写/小写）、文本对齐方式和 RTL 布局
• 只读显示：为标签或不可编辑的显示内容创建带样式的只读文本字段
• 溢出工具提示：当文本超出文本框边界时显示工具提示
• 尺寸约束：限制文本框的最小或最大尺寸

组件概览

TextBoxExt 是一个基于标准 TextBox 的高级文本框控件，提供：

• 自定义边框颜色和 3D 边框样式
• 八种内置视觉主题（Office2016、Office2019、Metro、Office2007、Office2010、Default）
• 与 SkinManager 集成主题程序集
• 支持自动换行和可配置滚动条的多行文本
• 字符大小写转换（Upper、Lower、Normal）
• 文本对齐方式（Left、Center、Right）
• 支持国际化应用的从右到左布局
• 带可自定义工具提示的溢出指示器
• 尺寸约束（MaximumSize/MinimumSize）
• ReadOnly 模式，禁用时仍可主动绘制
• 十二个属性更改事件，便于自定义

主要功能：

• 使用 BorderColor 和 BorderStyle 自定义边框
• 使用 Style 属性选择视觉主题
• 使用 ThemeName 属性在运行时切换主题
• 使用 CharacterCasing 自动转换大小写
• 使用 ShowOverflowIndicator 检测文本溢出
• 使用 MaxLength 限制输入长度
• 使用 DrawActiveWhenDisabled 在禁用时保持活动外观

文档与导航指南

入门

📄 阅读： references/getting-started.md

阅读时机： 开始新的实现、设置依赖项、首次使用、创建基本文本框

涵盖主题：

• 程序集部署（Syncfusion.Shared.Base.dll）
• NuGet 包安装（Syncfusion.Shared.WinForms）
• 命名空间要求（Syncfusion.Windows.Forms.Tools）
• 通过设计器添加 TextBoxExt（拖放）
• 以编程方式添加 TextBoxExt
• TextBoxExt 的基本实例化和配置
• 尺寸配置（MaximumSize/MinimumSize）
• 设置支持自动换行和滚动条的多行文本
• 初始文本显示

---

文本配置

📄 阅读： references/text-configuration.md

阅读时机： 配置文本属性、多行文本、字符大小写、对齐方式、溢出指示器和 RTL 支持

涵盖主题：

• Text 和 SelectedText 属性
• CharacterCasing（Upper、Lower、Normal 大小写转换）
• TextAlign（Left、Center、Right 对齐方式）
• 适用于阿拉伯语/希伯来语应用的 RightToLeft 布局
• DrawActiveWhenDisabled（禁用时保持活动外观）
• 多行文本配置
• 用于换行的 WordWrap 属性
• ScrollBars（Horizontal、Vertical、Both、None）
• 溢出指示器（ShowOverflowIndicator 属性）
• 溢出工具提示自定义（OverflowIndicatorToolTipText）
• 文本操作方法（AppendText、Cut、Copy、Paste、Select、SelectAll）
• 用于定位插入符的 ScrollToCaret() 方法

---

边框设置

📄 阅读： references/border-settings.md

阅读时机： 自定义边框外观、应用边框颜色、配置 3D 边框、选择边框边

涵盖主题：

• BorderStyle 属性（Fixed3D、FixedSingle、None）
• Border3DStyle 属性（Raised、Sunken、Etched 等）
• 使用 Color 值自定义 BorderColor
• 配置 BorderSides（All、Top、Bottom、Left、Right 及其组合）
• 完整的边框代码示例
• 边框自定义模式
• 使边框与应用主题相匹配

---

外观与样式

📄 阅读： references/appearance-styling.md

阅读时机： 应用视觉主题、自定义颜色、选择 Office 样式

涵盖主题：

• 用于自定义背景的 BackColor 属性
• 用于设置文本颜色的 ForeColor 属性
• Style 属性概览
• 八种内置视觉样式：
  • Office2016Colorful
  • Office2016White
  • Office2016Black
  • Office2016DarkGray
  • Office2019Colorful
  • Metro（扁平现代设计）
  • Office2007（经典 Ribbon 样式）
  • Office2010（精致的 Office 外观）
  • Default（标准外观）
• 视觉样式的选择与配置
• 样式对比示例
• 使文本框样式与应用设计相匹配

---

主题配置

📄 阅读： references/themes-configuration.md

阅读时机： 加载主题程序集、配置应用范围的主题、在运行时切换主题、进行高级主题设置

涵盖主题：

• ThemesEnabled 属性（用于 Fixed3D 边框的 XP 主题）
• 用于在运行时选择主题的 ThemeName 属性
• 主题程序集加载要求
  • Syncfusion.Office2016Theme.WinForms（4 种变体）
  • Syncfusion.Office2019Theme.WinForms
  • Syncfusion.HighContrastTheme.WinForms
• SkinManager.LoadAssembly() 方法
• 在 Program.Main() 中加载主题
• Office2016 主题变体（Colorful、White、Black、DarkGray）
• Office2019Colorful 主题
• HighContrastBlack 无障碍主题
• 应用范围的主题设置
• 在运行时切换主题
• 控件间的主题一致性

---

行为与事件

📄 阅读： references/behavior-events.md

阅读时机： 配置行为属性、处理事件、限制输入、响应属性更改

涵盖主题：

• MaxLength 属性（限制输入长度）
• 只读模式（防止编辑文本）
• 布局设置（MaximumSize、MinimumSize）
• 十二个属性更改事件：
  • Border3DStyleChanged
  • BorderColorChanged
  • BorderSidesChanged
  • BorderStyleChanged
  • CharacterCasingChanged
  • HideSelectionChanged
  • MaximumSizeChanged
  • MinimumSizeChanged
  • MultilineChanged
  • ReadOnlyChanged
  • TextAlignChanged
  • ThemesEnabledChanged
• 事件处理程序实现模式
• 事件驱动的自定义
• 验证和输入控制场景
• 动态属性更新

---

快速入门示例

带自定义边框的基本主题化文本框

C#:

using Syncfusion.Windows.Forms.Tools;
using System.Drawing;

// Create TextBoxExt instance
TextBoxExt textBoxExt1 = new TextBoxExt();
textBoxExt1.Location = new Point(50, 50);
textBoxExt1.Size = new Size(300, 25);
textBoxExt1.Text = "Enter your text here";

// Apply Office2016 Colorful theme
textBoxExt1.Style = TextBoxExt.theme.Office2016Colorful;

// Customize border
textBoxExt1.BorderColor = Color.FromArgb(0, 120, 215); // Blue border
textBoxExt1.BorderStyle = System.Windows.Forms.BorderStyle.FixedSingle;

// Add to form
this.Controls.Add(textBoxExt1);

VB.NET:

Imports Syncfusion.Windows.Forms.Tools
Imports System.Drawing

' Create TextBoxExt instance
Dim textBoxExt1 As New TextBoxExt()
textBoxExt1.Location = New Point(50, 50)
textBoxExt1.Size = New Size(300, 25)
textBoxExt1.Text = "Enter your text here"

' Apply Office2016 Colorful theme
textBoxExt1.Style = TextBoxExt.theme.Office2016Colorful

' Customize border
textBoxExt1.BorderColor = Color.FromArgb(0, 120, 215) ' Blue border
textBoxExt1.BorderStyle = System.Windows.Forms.BorderStyle.FixedSingle

' Add to form
Me.Controls.Add(textBoxExt1)

---

常见模式

模式 1：带溢出指示器的多行文本编辑器

场景： 创建用于记录备注或评论的多行文本框，并带有滚动条和溢出工具提示

C#:

using Syncfusion.Windows.Forms.Tools;

TextBoxExt notesTextBox = new TextBoxExt();
notesTextBox.Location = new System.Drawing.Point(20, 20);
notesTextBox.Size = new System.Drawing.Size(400, 200);

// Enable multiline with word wrap
notesTextBox.Multiline = true;
notesTextBox.WordWrap = true;
notesTextBox.ScrollBars = System.Windows.Forms.ScrollBars.Vertical;

// Configure overflow indicator
notesTextBox.ShowOverflowIndicator = true;
notesTextBox.ShowOverflowIndicatorToolTip = true;
notesTextBox.OverflowIndicatorToolTipText = "Text content exceeds visible area. Scroll to view more.";

// Apply Metro theme
notesTextBox.Style = TextBoxExt.theme.Metro;

// Add to form
this.Controls.Add(notesTextBox);

---

模式 2：外观活跃的只读显示字段

场景： 显示只读信息（例如计算结果、状态），即使处于禁用状态，外观仍显得活跃

C#:

using Syncfusion.Windows.Forms.Tools;
using System.Drawing;

TextBoxExt displayField = new TextBoxExt();
displayField.Location = new System.Drawing.Point(150, 100);
displayField.Size = new System.Drawing.Size(250, 25);
displayField.Text = "Total: $1,234.56";

// Make readonly but keep active appearance
displayField.ReadOnly = true;
displayField.DrawActiveWhenDisabled = true;

// Apply custom styling
displayField.BackColor = Color.WhiteSmoke;
displayField.ForeColor = Color.DarkGreen;
displayField.BorderColor = Color.LightGray;
displayField.BorderStyle = System.Windows.Forms.BorderStyle.FixedSingle;

// Align text to right (common for currency)
displayField.TextAlign = System.Windows.Forms.HorizontalAlignment.Right;

// Add to form
this.Controls.Add(displayField);

---

模式 3：限制长度的大写输入字段

场景： 创建会自动将输入转换为大写的输入字段（例如产品代码、许可证密钥）

C#:

using Syncfusion.Windows.Forms.Tools;
using System.Drawing;

TextBoxExt productCodeBox = new TextBoxExt();
productCodeBox.Location = new System.Drawing.Point(120, 80);
productCodeBox.Size = new System.Drawing.Size(200, 25);

// Enforce uppercase and length
productCodeBox.CharacterCasing = System.Windows.Forms.CharacterCasing.Upper;
productCodeBox.MaxLength = 10;

// Apply Office2019 theme
productCodeBox.Style = TextBoxExt.theme.Office2019Colorful;

// Customize border
productCodeBox.BorderColor = Color.SteelBlue;
productCodeBox.BorderStyle = System.Windows.Forms.BorderStyle.FixedSingle;

// Center align for codes
productCodeBox.TextAlign = System.Windows.Forms.HorizontalAlignment.Center;

// Add placeholder behavior
productCodeBox.ForeColor = Color.Gray;
productCodeBox.Text = "ENTER-CODE";

productCodeBox.Enter += (s, e) => {
    if (productCodeBox.Text == "ENTER-CODE")
    {
        productCodeBox.Text = "";
        productCodeBox.ForeColor = Color.Black;
    }
};

productCodeBox.Leave += (s, e) => {
    if (string.IsNullOrWhiteSpace(productCodeBox.Text))
    {
        productCodeBox.Text = "ENTER-CODE";
        productCodeBox.ForeColor = Color.Gray;
    }
};

// Add to form
this.Controls.Add(productCodeBox);

---

关键属性

外观属性

属性	类型	说明
Style	TextBoxExt.theme	视觉主题：Office2016Colorful、Office2016White、Office2016Black、Office2016DarkGray、Office2019Colorful、Metro、Office2007、Office2010、Default
ThemeName	string	运行时主题名称（需要加载主题程序集）
BackColor	Color	文本框的背景色
ForeColor	Color	文本颜色
BorderStyle	BorderStyle	边框样式：Fixed3D、FixedSingle、None
BorderColor	Color	自定义边框颜色
Border3DStyle	Border3DStyle	3D 边框效果：Raised、Sunken、Etched 等
BorderSides	Border3DSide	边框侧面：All、Top、Bottom、Left、Right

文本属性

属性	类型	说明
Text	string	文本框内容
SelectedText	string	当前选中的文本
CharacterCasing	CharacterCasing	大小写转换：Normal、Upper、Lower
TextAlign	HorizontalAlignment	文本对齐方式：Left、Center、Right
RightToLeft	RightToLeft	RTL 布局：Yes、No
DrawActiveWhenDisabled	bool	即使控件已禁用，仍将文本绘制为活动状态

多行属性

属性	类型	说明
Multiline	bool	启用多行文本显示
WordWrap	bool	自动将文本换到下一行
ScrollBars	ScrollBars	滚动条可见性：None、Horizontal、Vertical、Both

溢出指示器属性

属性	类型	说明
ShowOverflowIndicator	bool	文本溢出时显示指示器
ShowOverflowIndicatorToolTip	bool	在溢出指示器上显示工具提示
OverflowIndicatorToolTipText	string	溢出时显示的自定义工具提示文本

行为属性

属性	类型	说明
MaxLength	int	最大字符数（默认值：32767）
ReadOnly	bool	禁止编辑文本
MaximumSize	Size	控件的最大尺寸
MinimumSize	Size	控件的最小尺寸

主题属性

属性	类型	说明
ThemesEnabled	bool	为 Fixed3D 边框启用 XP 主题

---

常见用例

1. 具有主题外观的产品搜索框

用于库存系统中搜索产品的样式化文本框：

TextBoxExt searchBox = new TextBoxExt();
searchBox.Style = TextBoxExt.theme.Office2016Colorful;
searchBox.BorderColor = Color.DodgerBlue;
searchBox.Text = "Search products...";

2. 多行描述字段

用于产品描述或备注的大型文本框：

TextBoxExt descriptionBox = new TextBoxExt();
descriptionBox.Multiline = true;
descriptionBox.WordWrap = true;
descriptionBox.ScrollBars = ScrollBars.Vertical;
descriptionBox.Size = new Size(500, 150);

3. 大写许可证密钥输入框

自动将许可证密钥转换为大写：

TextBoxExt licenseBox = new TextBoxExt();
licenseBox.CharacterCasing = CharacterCasing.Upper;
licenseBox.MaxLength = 25;
licenseBox.TextAlign = HorizontalAlignment.Center;

4. 只读状态显示

用于显示活动外观的只读字段：

TextBoxExt statusBox = new TextBoxExt();
statusBox.ReadOnly = true;
statusBox.DrawActiveWhenDisabled = true;
statusBox.BackColor = Color.LightYellow;
statusBox.Text = "Status: Active";

5. 用于阿拉伯语的 RTL 文本输入

适用于国际化应用的从右向左文本框：

TextBoxExt arabicTextBox = new TextBoxExt();
arabicTextBox.RightToLeft = RightToLeft.Yes;
arabicTextBox.TextAlign = HorizontalAlignment.Right;

6. 自定义边框输入框

边框颜色与品牌相匹配的文本框：

TextBoxExt brandedBox = new TextBoxExt();
brandedBox.BorderStyle = BorderStyle.FixedSingle;
brandedBox.BorderColor = Color.FromArgb(255, 87, 34); // Orange
brandedBox.Style = TextBoxExt.theme.Metro;

7. 尺寸受限的文本框

尺寸受限的文本框：

TextBoxExt constrainedBox = new TextBoxExt();
constrainedBox.MinimumSize = new Size(200, 25);
constrainedBox.MaximumSize = new Size(400, 25);

---

其他资源

程序集： Syncfusion.Shared.Base.dll
命名空间： Syncfusion.Windows.Forms.Tools
NuGet 包： Syncfusion.Shared.WinForms
最低 .NET Framework 版本： 4.5

关键类：

• TextBoxExt - 增强型文本框控件的主类
• SkinManager - 主题程序集加载管理器

相关技能：

• 窗体主题与样式设置
• 输入验证
• 多行文本编辑器
• 只读字段显示