WPF数字输入框NumberUpDown：依赖属性、绑定与生产级交互

1. 为什么 WPF 的控件箱里翻不到 NumericUpDown

1.1 从 WinForms 搬过来的人，第一个卡壳点就在这

标题里那串20240302是动手那天随手记的日期，WFP是手滑打成WPF了，不影响内容。数字输入框这个东西，在任何一套 UI 框架里都属于"用得最多、长得最不起眼、出了问题最烦人"的那一档。做过 WinForms 的人切到 WPF 之后，第一次在工具箱里翻找数字输入框，大概率会愣一下——NumericUpDown不在里面。

这不是遗漏，是 WPF 从设计之初就没打算给每个具体业务控件做内置实现。它走的是"组合优先"的路子：TextBox负责文本编辑，RepeatButton负责连击，Grid负责排布，三者用模板拼起来就是一个数字步进框。官方的立场是，这类带强业务语义的控件交给生态去做。于是十几年下来，WPF 的数字输入框一直是"人人都在写，人人都写得不太一样"的状态。

这个现实带来一个很直接的后果：如果你在做一个参数配置面板、一个财务录入界面、一个图形编辑器里的坐标输入，你迟早要自己面对NumberUpDown这个问题。它不是可选项，是必答题。而且这道题的答案，写得好和写得凑合，用户体验差了不止一个档次。

我把这篇文章的目标定得很明确：给出一套可以直接复制到项目里跑起来的实现，同时把每一步背后的取舍讲清楚，尤其是那些只有真在生产环境里跑过才会发现的问题。如果你只是想快速加一个能用的数字框，看完第 3 章就够；如果你曾经被自己的数字框坑过——值跳了、小数点打不进去、绑定不更新——第 6 章的排查实录值得细看。

1.2 原生 TextBox 硬扛业务的三处塌方

很多人的第一版实现是"用 TextBox 加一个PreviewTextInput事件过滤非法字符"，跑起来看着像那么回事，但只要业务稍微复杂一点，就会连着塌三个方面。

第一处塌方是范围约束的时机。假设最小值是 10，用户想输入 100，键入第一个字符1的瞬间，如果你立刻把值夹到区间内，输入框里的内容会瞬间变成10，光标位置也跟着乱掉，用户根本打不出想要的数字。这类 bug 在测试环境里很难复现，因为测试同学往往是直接粘贴一个合法值，而真实用户是一个字符一个字符敲的。约束必须发生在"提交"这个明确的时间点，而不是"每一次内容变化"。

第二处塌方是文本状态和数值状态的错位。用户敲下12.准备继续输小数位，这时候12.并不是一个合法的 decimal。如果代码在TextChanged里无条件解析并回写，那这个小数点会被当场抹掉，用户会觉得自己按了个寂寞。同理还有只按了一个负号的-、正在输入科学计数法中间态的1e。这些中间态都得被允许存在，不能被急着"纠正"。

第三处塌方是步进交互的手感。上下按钮点一下加一，这个好办。但按住不放要连续加、松开要停、鼠标划出按钮区域要停止加速、快速连点不能丢步、按住时不能把输入框的焦点抢走——这些细节凑在一起，才是"好用"和"能用"的分界线。用普通Button配DispatcherTimer能做，但要自己管一堆定时器的启停和边界，RepeatButton内置了这套逻辑，只是有几个默认行为需要手动掰过来。

1.3 先想清楚：你要的是"输入框"还是"步进器"

动手之前有个问题值得先问自己：这个控件的主要使用场景，是"打字输入"还是"微调数值"？

这两个诉求会导向不同的设计重心。以打字为主的场景（比如录入金额、填身份证号、输端口号），重心应该在文本编辑体验上——光标位置要稳、全选要顺手、粘贴要能过滤、输入法不能捣乱，步进按钮只是锦上添花的辅助。以微调为主的场景（比如调音量、调画布缩放、调图表的最大值最小值），重心就完全在按钮和滚轮上，用户可能一辈子都不会用键盘去改这个数字，那按钮的尺寸、连击的加速度曲线、按下时的视觉反馈才是重点。

我在实际项目里最终选择了"一个控件、两个开关"的做法：核心实现是同一套，通过ShowSpinButtons和IsEditable两个属性切换形态。这样既避免了维护两套代码，又能在不同界面里给出贴合场景的交互。后面第 3 章的依赖属性设计里会体现这个思路。

另外要提醒一句，如果你只需要一个"只能输数字、不越界、支持绑定的文本框"，压根不需要步进按钮，那完全没必要上UserControl，一个附加行为（Attached Behavior）挂在原生TextBox上就够了，代码量少一个数量级，样式也更容易跟着现有设计规范走。这个取舍在第 2 章会详细展开。

2. 三条实现路线的取舍：引库、自绘、附加行为

2.1 路线一：引一个现成的开源控件库

最省事的路当然是找现成的。市面上几个主流的 WPF 开源控件库都提供数字输入框，功能覆盖得挺全，主题样式也跟各自的视觉体系绑定得很好。如果你的项目本来就在用某个控件库做整体 UI，顺手把它的数字框也用上，这是性价比最高的选择。

但这条路线有三个隐性成本，得提前掂量。一是包体膨胀，为了一个数字框引入一整套控件库，安装包体积和启动时的资源加载都会受影响，尤其对那些本来只用原生控件的轻量工具类应用来说不划算。二是样式定制成本，控件库的数字框往往和它自己的主题强绑定，你要把它改成跟公司设计规范一致的圆角输入框，改起来比重写一个还费劲，因为得先摸清它的模板结构。三是行为不可控，某些库的实现在滚轮处理上比较激进，鼠标划过就改值，用户滚动页面时会误改参数，而这类行为不一定有开关给你关掉。

我的判断标准很简单：如果项目已经在用这个库，就用；如果为了这一个控件才引，就自己写。一个数字输入框的核心逻辑撑死四百行，自己维护的成本远低于长期跟第三方库的版本兼容问题打交道。

2.2 路线二：自绘一个 UserControl

这是最正统、也最可控的方案。把TextBox和两个RepeatButton塞进一个ControlTemplate，对外暴露Value、Minimum、Maximum、Step等依赖属性，内部处理同步逻辑。好处是全链路自己掌握，样式可以完全贴合设计稿，行为也能按业务需要随便改。

代价是需要对 WPF 的依赖属性、模板、绑定更新时机有基本掌握。特别是依赖属性的值强制转换（Coerce）和双向绑定的更新触发时机这两块，是新手最容易写歪的地方。写歪的表现通常很隐蔽：界面上看着对了，但ViewModel里的值没跟着变，或者反过来的情况。

这套方案我最终用的是"继承Control而不是UserControl"的写法。差别在于UserControl的模板是固定的，样式定制要靠内部元素命名约定；而继承Control可以走完整的Template机制，别人用Style就能换皮，符合 WPF 的惯例。如果你赶时间，UserControl也能出活，先跑通再重构完全没问题。

2.3 路线三：附加行为 + 原生 TextBox

如果需求只是"约束输入 + 范围校验 + 滚轮调值"，没有步进按钮的视觉需求，附加行为是最轻的方案。核心思路是把几个附加属性（IsEnabled、Minimum、Maximum、Step）挂到原生TextBox上，在属性变化时给目标控件挂上事件处理器，在事件里做过滤和提交。

这个方案的最大优势是零侵入。你的TextBox还是那个TextBox，现有的全局样式、字体、主题切换全都自动生效，不需要为数字框单独维护一套视觉。而且因为没有额外的可视化树层级，布局性能也更好——在列表里放几百个数字输入框的场景下，这个差别是能感觉到的。

缺点也很直白：没有按钮、没有连击、没有按钮的禁用态反馈。只能靠键盘和滚轮。所以它适合"参数表格"这种密集排布的场景，不适合"主控面板"这种需要突出可调性的场景。

2.4 三条路线的横向对比

我最终的组合方案是：主控面板用自绘控件，密集列表用附加行为，两者共用同一套校验和格式化的静态工具方法。这样逻辑只有一份，表现层按场景挑，后期改规则只改一处。

3. 动手实现：一个能上生产的 NumberUpDown

3.1 依赖属性设计：把区间约束收敛到 Coerce

属性设计上有一个决定性的选择：范围约束放在CoerceValueCallback里，而不是放在属性变更回调里。这两者的差别很大。放在变更回调里，意味着值先被赋成越界值、再被改回来，中间会经历一次"非法状态"，绑定到它的其他元素会闪一下错误值；放在Coerce里，值在进入属性系统之前就被夹紧了，外界永远看不到越界状态，也不会产生多余的通知。

public class NumberUpDown : Control { static NumberUpDown() { DefaultStyleKeyProperty.OverrideMetadata(typeof(NumberUpDown), new FrameworkPropertyMetadata(typeof(NumberUpDown))); } public static readonly DependencyProperty ValueProperty = DependencyProperty.Register(nameof(Value), typeof(decimal), typeof(NumberUpDown), new FrameworkPropertyMetadata( 0m, FrameworkPropertyMetadataOptions.BindsTwoWayByDefault, OnValueChanged, CoerceValue)); public decimal Value { get => (decimal)GetValue(ValueProperty); set => SetValue(ValueProperty, value); } private static object CoerceValue(DependencyObject d, object baseValue) { var ctl = (NumberUpDown)d; var v = (decimal)baseValue; if (ctl.Minimum > ctl.Maximum) return ctl.Minimum; if (v < ctl.Minimum) return ctl.Minimum; if (v > ctl.Maximum) return ctl.Maximum; return v; } }

注意BindsTwoWayByDefault这个标志。数字输入框的使用者百分之九十九是要双向绑定的，加上这个标志之后，XAML 里写{Binding SomeValue}就够了，不用每次都补Mode=TwoWay。少写一次就少一次忘记的机会，这是降低团队出错率的小手段。

Minimum和Maximum的变更回调里必须重新触发一次CoerceValue(ValueProperty)，否则先设Value再设Minimum的时候，已经存在的值不会被重新夹紧。这个顺序问题在 XAML 里特别容易踩到，因为属性赋值顺序由解析器决定，未必是你想的那个顺序。

public static readonly DependencyProperty MinimumProperty = DependencyProperty.Register(nameof(Minimum), typeof(decimal), typeof(NumberUpDown), new PropertyMetadata(decimal.MinValue, OnRangeChanged)); public static readonly DependencyProperty MaximumProperty = DependencyProperty.Register(nameof(Maximum), typeof(decimal), typeof(NumberUpDown), new PropertyMetadata(decimal.MaxValue, OnRangeChanged)); private static void OnRangeChanged(DependencyObject d, DependencyPropertyChangedEventArgs e) { var ctl = (NumberUpDown)d; ctl.CoerceValue(ValueProperty); ctl.UpdateButtonStates(); ctl.SyncTextFromValue(); }

Step属性额外加一个校验：值必须大于零。步进为 0 或负数会导致按钮按下去毫无反应或者方向反了，这种配置错误在运行时极难排查，直接在Coerce里把它按到最小值上更稳妥。

private static object CoerceStep(DependencyObject d, object baseValue) { var step = (decimal)baseValue; return step <= 0m ? 1m : step; }

还有一组只读依赖属性值得加上：IsAtMaximum和IsAtMinimum。它们的作用是让模板里的按钮能在到达边界时自动变灰。用只读的DependencyPropertyKey注册，外部只能读不能写，安全。

private static readonly DependencyPropertyKey IsAtMaximumPropertyKey = DependencyProperty.RegisterReadOnly(nameof(IsAtMaximum), typeof(bool), typeof(NumberUpDown), new PropertyMetadata(false)); public static readonly DependencyProperty IsAtMaximumProperty = IsAtMaximumPropertyKey.DependencyProperty; public bool IsAtMaximum => (bool)GetValue(IsAtMaximumProperty);

3.2 模板布局：用 Grid 摆一个不抖的骨架

模板这块没什么花哨的，Grid两列，左边TextBox吃剩余空间，右边一列放两个上下堆叠的RepeatButton。用Grid而不是StackPanel的原因是按钮列宽度固定、输入框自适应，Grid的*和Auto组合能精确表达这个意图，窗口拉伸时不会出现按钮被挤压变形的情况。

<Style TargetType="{x:Type local:NumberUpDown}"> <Setter Property="Focusable" Value="True"/> <Setter Property="Template"> <Setter.Value> <ControlTemplate TargetType="{x:Type local:NumberUpDown}"> <Border x:Name="Bd" Background="{TemplateBinding Background}" BorderBrush="{TemplateBinding BorderBrush}" BorderThickness="{TemplateBinding BorderThickness}" CornerRadius="4"> <Grid> <Grid.ColumnDefinitions> <ColumnDefinition Width="*"/> <ColumnDefinition Width="Auto"/> </Grid.ColumnDefinitions> <TextBox x:Name="PART_Editor" Grid.Column="0" BorderThickness="0" Background="Transparent" VerticalContentAlignment="Center" Padding="6,2"/> <Grid Grid.Column="1" Width="20"> <Grid.RowDefinitions> <RowDefinition Height="*"/> <RowDefinition Height="*"/> </Grid.RowDefinitions> <RepeatButton x:Name="PART_Up" Grid.Row="0" Focusable="False" Delay="400" Interval="60" Click="OnSpinUp"/> <RepeatButton x:Name="PART_Down" Grid.Row="1" Focusable="False" Delay="400" Interval="60" Click="OnSpinDown"/> </Grid> </Grid> </Border> <ControlTemplate.Triggers> <Trigger Property="IsAtMaximum" Value="True"> <Setter TargetName="PART_Up" Property="IsEnabled" Value="False"/> </Trigger> <Trigger Property="IsAtMinimum" Value="True"> <Setter TargetName="PART_Down" Property="IsEnabled" Value="False"/> </Trigger> <Trigger Property="IsEditable" Value="False"> <Setter TargetName="PART_Editor" Property="IsReadOnly" Value="True"/> </Trigger> <Trigger Property="ShowSpinButtons" Value="False"> <Setter TargetName="PART_Up" Property="Visibility" Value="Collapsed"/> <Setter TargetName="PART_Down" Property="Visibility" Value="Collapsed"/> </Trigger> </ControlTemplate.Triggers> </ControlTemplate> </Setter.Value> </Setter> </Style>

这段模板里有两个Focusable="False"，是全文最容易被忽略、也最影响手感的一行配置。ButtonBase派生的控件默认是可聚焦的，点按钮的时候焦点会从TextBox转移到按钮上。一旦转移，TextBox触发LostFocus，我精心设计的"失焦时才提交并格式化"的逻辑就会跑一遍，用户正在输入的内容被重新排版，光标位置重置，体验直接崩掉。加上这一行，焦点始终留在输入框里，点击按钮只是单纯的数值操作。

Delay和Interval两个参数决定了按住时的节奏。Delay是首次重复之前的等待，默认 500 毫秒，我压到 400 毫秒，因为现代用户对"按住要等半秒"这件事耐心有限；Interval是之后的重复间隔，默认 33 毫秒相当于每秒三十步，对于步长为 1 的参数来说太快了，几乎是瞬间冲到边界。60 毫秒（约每秒十六步）配合步长 1，从 0 调到 100 大约六秒，手感刚好。如果你的Step更小（比如 0.01），可以把Interval再压到 40 毫秒左右。

3.3 值的校验与归一化：所有入口收敛到一处

越界夹紧在Coerce里做完了，但还有一层没处理：对齐。如果Step是 0.5，用户通过别的途径塞进来一个 3.7，这个值该保留还是该吸附到 3.5？我的处理是：手动输入的值原样保留，只有按钮和滚轮触发的步进才按Step对齐。理由是用户手动输入 3.7 说明他明确要这个数，强行吸附会让他觉得控件不听话；而点击按钮本来就意味着"按步长走"，这时候对齐是符合预期的。

处理步进的核心方法只有一个，所有触发源都走它：

private void StepBy(int direction, bool isLargeStep = false) { if (!IsEditable) return; decimal step = isLargeStep ? Step * 10m : Step; decimal next = Value + direction * step; if (IsLoop) { if (next > Maximum) next = Minimum; else if (next < Minimum) next = Maximum; } SetCurrentValue(ValueProperty, next); SyncTextFromValue(); }

这里用SetCurrentValue而不是直接赋Value，是个关键细节。直接赋值会覆盖绑定——如果Value是双向绑定的，Value = something会把BindingExpression干掉，之后ViewModel再改值界面就不动了。SetCurrentValue只改当前值、保留绑定，是控件内部修改自身依赖属性的正确姿势。这个坑我在早期版本上吃了很久的亏：一开始测试没问题，因为测试时没绑ViewModel；一进真实页面，改一次值绑定就断了。

IsLoop的循环模式在调色板色相、角度、时间这类场景里很实用，转到头能绕回来。但它和IsAtMaximum的按钮禁用逻辑是冲突的，两者不能同时生效，所以模板触发器那里要给IsLoop="True"的情况加一个例外，或者干脆在代码里判断：IsLoop为真时IsAtMaximum恒为false。

3.4 文本与数值的双向同步：什么时候该"纠正"用户

同步逻辑是整块代码里最需要克制的部分。原则就一句话：只在明确的提交时机做解析和格式化，输入过程中一律放行。

private bool _isSyncing; private void SyncTextFromValue() { var editor = GetTemplateChild("PART_Editor") as TextBox; if (editor == null || _isSyncing) return; _isSyncing = true; editor.Text = Value.ToString("F" + DecimalPlaces, CultureInfo.CurrentCulture); _isSyncing = false; }

_isSyncing这个重入标志是必须的。Value变化会触发SyncTextFromValue，设置Text又会触发TextChanged，TextChanged里如果又去解析并回写Value，就形成循环。虽然依赖属性的相等判断能挡住大多数自循环，但在浮点格式化有舍入的情况下，可能碰撞出"值一直在微调"的诡异现象。

提交时机的选择上，LostFocus和Enter键都要处理，Esc键则回滚到上一次的合法值：

private void OnEditorLostFocus(object sender, RoutedEventArgs e) => CommitText(); private void OnEditorKeyDown(object sender, KeyEventArgs e) { if (e.Key == Key.Enter) { CommitText(); e.Handled = true; } else if (e.Key == Key.Escape) { SyncTextFromValue(); e.Handled = true; } else if (e.Key == Key.Up) { StepBy(+1); e.Handled = true; } else if (e.Key == Key.Down) { StepBy(-1); e.Handled = true; } }

private void CommitText() { var editor = GetTemplateChild("PART_Editor") as TextBox; if (editor == null) return; if (TryParse(editor.Text, out var parsed)) SetCurrentValue(ValueProperty, parsed); // 越界由 Coerce 兜底 SyncTextFromValue(); // 无论成功与否都格式化回显 }

即使解析失败（用户输了个abc或者半个小数点），也要执行SyncTextFromValue，把输入框恢复成当前合法值的显示。这个"失败也回显"的动作很重要，否则输入框里会残留一段和Value完全脱节的文本，用户下一次进来看到的还是个错的。

解析方法本身要考虑几句：

private static bool TryParse(string text, out decimal value) { value = 0m; if (string.IsNullOrWhiteSpace(text)) return false; // 全角数字归一化，输入法状态下很容易打进全角 var sb = new StringBuilder(text.Length); foreach (var ch in text.Trim()) sb.Append(ch >= '\uFF10' && ch <= '\uFF19' ? (char)(ch - '\uFF10' + '0') : ch); return decimal.TryParse(sb.ToString(), NumberStyles.Number, CultureInfo.CurrentCulture, out value); }

全角那一行不是过度设计。中文输入法在数字键盘和主键盘切换时很容易打出全角数字，decimal.TryParse会直接返回 false，用户看到的是"我明明输了数字，为什么没生效"。加上这段归一化之后，这个投诉就消失了。

4. 交互细节：把所有手感问题一次性处理掉

4.1 RepeatButton 与长按节奏的调参依据

为什么不用普通Button加DispatcherTimer自己实现连击？答案不是"麻烦"，而是"边界情况太多"。DispatcherTimer方案要自己处理按下启动、松开停止、PreviewMouseUp在按钮外松开（这时候按钮收不到MouseUp）、鼠标捕获丢失、窗口失焦中断等一堆情况。少处理一个，就会出现"按一下之后数字疯了一样一直涨"的经典 bug。RepeatButton内部用的是ButtonBase的点击机制加一个内部定时器，这些边界都帮你兜住了。

调参上我给的默认值是Delay=400, Interval=60。这个组合针对的是步长为 1 的常见场景。如果你的控件被用在需要"慢速精调"的地方（比如偏移量微调，步长 0.1），Interval应该拉长到 100 以上，否则按住两秒就冲出去二十个单位，用户根本对不准。反过来，用于"快速定位"的场景（比如年份选择，范围 1900 到 2100），Interval可以压到 30，配合Step=1能快速扫过。

还有一处细节：按住按钮之后快速把鼠标移开按钮再移回来，RepeatButton会停止再重新开始，节奏会重置为Delay。这个行为是对的，不用管。但如果你的按钮特别小（比如 20 像素宽），用户按住的瞬间手抖一下就会滑出去，体验会很差。这也是我模板里把按钮列宽设成 20 而不是 16 的原因——在 100% DPI 下，20 像素已经是最低可用的宽度了，再窄就得考虑把按钮改成横向排布或者干脆去掉。

4.2 键盘与滚轮：接管哪些、放过哪些

键盘这块，Up/Down改值几乎是所有人的肌肉记忆，必须支持。PageUp/PageDown改大值（我实现为Step * 10）是锦上添花，在参数面板里很实用。

滚轮是个有争议的项。默认接管滚轮的风险在于：如果这个数字框放在一个可滚动页面里，用户滚动页面时鼠标划过数字框，值就被改了，而他完全没意识到。这是那种"用户第二天发现参数被改过，但完全不知道为什么"的隐蔽事故。

我的处理是给滚轮加一个开关WheelEnabled，默认false，只在明确需要微调的独立面板里打开。打开之后也不是简单的PreviewMouseWheel加一减一，而要检查键盘修饰键，只有按住Ctrl时才响应：

private void OnEditorPreviewMouseWheel(object sender, MouseWheelEventArgs e) { if (!WheelEnabled || Keyboard.Modifiers != ModifierKeys.Control) return; StepBy(e.Delta > 0 ? +1 : -1); e.Handled = true; // 阻止滚轮继续冒泡到外层 ScrollViewer }

e.Handled = true不能忘。忘了的话，外层ScrollViewer收到滚轮事件照样会滚动页面，用户会看到"值改了，页面也跟着滚了"的双重反应，非常怪。

4.3 粘贴过滤与输入法：两处容易被漏掉的入口

PreviewTextInput能挡住键盘输入的非数字字符，但挡不住粘贴。用户从 Excel 里复制一个带千分位分隔符的1,234.5，或者从文档里复制一个带单位的50px，粘贴进来就破坏了整个控件的状态。

处理方式是在TextBox上挂DataObject.Pasting：

DataObject.AddPastingHandler(editor, OnPaste); private void OnPaste(object sender, DataObjectPastingEventArgs e) { var formats = e.DataObject.GetFormats(); if (!e.DataObject.GetDataPresent(DataFormats.UnicodeText)) { e.CancelCommand(); return; } var raw = (string)e.DataObject.GetData(DataFormats.UnicodeText) ?? ""; var cleaned = Regex.Replace(raw, @"[^\d\-\.]", ""); if (string.IsNullOrEmpty(cleaned) || !TryParse(cleaned, out _)) { e.CancelCommand(); return; } if (cleaned != raw) { e.CancelCommand(); var editor = (TextBox)sender; var start = editor.SelectionStart; editor.SelectedText = cleaned; editor.SelectionStart = start + cleaned.Length; } }

这段逻辑是"能清洗就清洗，洗不干净就整个取消"。直接取消粘贴虽然保守，但至少不会把控件搞到一个无法解析的状态。清洗后手动插入的那几个游标操作，是为了让粘贴之后光标停在插入内容的末尾，符合用户预期。

至于输入法，中文输入法在数字框里激活时，敲数字键有可能走全角路径。3.4 节里的全角归一化能兜住大部分情况。如果要求更严，可以在InputMethod.IsInputMethodEnabled上直接关掉输入法，代价是用户完全没法在这个框里打中文注释——对纯数字框来说这不是问题。

4.4 焦点与全选：让"点进去就想覆盖"成为默认

用户在参数面板里点一个数字框，最想做的事通常是"全选、重打一个值"。TextBox的默认行为是把光标定位在点击位置，用户得手动Ctrl+A，多此一举。

处理办法是在GotKeyboardFocus里做一次全选，但要注意区分键盘焦点和鼠标焦点：用 Tab 键切进来的时候全选是合理的，用鼠标点进来的时候如果用户点的是中间某个字符，强行全选反而打断了他"改一位数字"的意图。所以正确的做法是只在键盘导航进入时全选：

private void OnEditorGotKeyboardFocus(object sender, KeyboardFocusChangedEventArgs e) { if (e.KeyboardDevice.IsKeyDown(Key.Tab)) { var editor = (TextBox)sender; editor.Dispatcher.BeginInvoke(new Action(() => editor.SelectAll()), DispatcherPriority.Input); } }

BeginInvoke那里是为绕开TextBox内部把选区重置到 0 的时机，直接SelectAll()会被覆盖掉。用DispatcherPriority.Input排在输入处理之后，实测下来稳定。

还有一个反向问题：当Value被ViewModel从外部改变时，如果用户正在这个框里编辑，要不要覆盖他的输入？我的选择是不覆盖。判断条件是editor.IsKeyboardFocused，正在编辑就只更新内部值、不刷新文本，等用户提交时再走正常的校验流程。反过来如果用户没在编辑，就正常刷新文本显示。这个策略避免了"用户正在输一半，后台来条消息把值刷掉了"的尴尬。

5. 绑定、精度与被业务捶打过的场景

5.1 绑定模式与 UpdateSourceTrigger 的取舍

Value属性我默认设成了BindsTwoWayByDefault，但UpdateSourceTrigger保持默认的PropertyChanged——也就是说Value一变就立刻推到ViewModel。这对步进按钮来说是必需的，因为用户点一下就应该看到下游立刻响应（比如滑块的联动）。

但对文本输入来说，如果用户是逐字输入，Value会在每次提交时变化。由于我们把提交点放在了LostFocus和Enter，所以实际发生的频率很低，不会造成ViewModel的抖动。这个设计是刻意的：输入过程中不产生任何Value变化，只在提交时产生一次。

如果你确实需要"边输边更新"的效果（比如实时过滤列表的数值阈值），不要改这个控件的内部逻辑，而是在ViewModel的 setter 里加防抖。控件负责"何时提交"，防抖负责"提交后多久生效"，职责分明，各自改起来互不影响。

5.2 decimal 还是 double：从一次精度事故说起

Value用的是decimal而不是double，这个选择在财务类场景下是硬要求。double的二进制表示无法精确表达 0.1，0.1 + 0.2得到的是0.30000000000000004。如果你用double做步长为 0.1 的步进，连点十下之后，显示出来的值格式化后是 0.9999999999999999，舍入到一位小数还是 1.0，看起来没问题；但如果你把原始值写进配置文件或者发到后端，这个尾数就会暴露出来，引发各种"金额差一分钱"的玄学问题。

代价是decimal的运算比double慢一个数量级。但在"用户点按钮改数值"这个场景里，一秒最多几十次运算，性能完全不是问题。用decimal换来的是"值永远精确"，这笔买卖非常划算。

有一个例外要单独处理：如果这个控件是用来输入图形坐标、缩放比例、物理量这类本身就用浮点表示的值，那用decimal就得在绑定时来回转换，反而麻烦。这种情况我建议单独做一个DoubleUpDown，逻辑一模一样，只把类型换掉，格式化时用"0.###"这种不固定小数位的格式串，避免显示一串无意义的长尾。

5.3 和业务校验框架的配合

控件内部的Coerce只能保证值在Minimum和Maximum之间，但业务规则往往比这个复杂：这个值必须是 5 的倍数、这个值不能和另一个字段相等、这个值在某个状态下不允许修改。这些规则不该塞进控件里，控件保持"我只管范围和格式"的纯粹职责，业务校验交给IDataErrorInfo、INotifyDataErrorInfo或者ValidationRule。

有一个衔接点需要注意：控件的Coerce会悄悄把越界值改掉，用户的输入可能"被纠正"而没有任何提示。这在很多场景下是对的（输入 999 自动变 100，用户看到结果就知道上限是一百），但在严格校验的场景下，用户可能更希望看到一个明确的错误提示而不是静默修正。为此我加了一个ClampMode属性：Silent静默夹紧，Throw抛异常交给校验框架处理。默认Silent，需要严格提示时切到Throw。

Throw模式的实现不能真的在Coerce里抛，那样会把属性系统搞乱。正确做法是在Coerce里返回夹紧值，同时在ValueChanged里判断"原始值是否被改过"，如果改过就通过Validation.MarkInvalid挂一个错误上去：

private static void OnValueChanged(DependencyObject d, DependencyPropertyChangedEventArgs e) { var ctl = (NumberUpDown)d; if (ctl.ClampMode == ClampMode.Throw && (decimal)e.NewValue != (decimal)e.OldValue) { var be = ctl.GetBindingExpression(ValueProperty); if (be != null && ctl.IsLoaded) Validation.MarkInvalid(be, new ValidationError( new ExceptionValidationRule(), be) { ErrorContent = "输入值超出允许范围" }); } ctl.UpdateButtonStates(); ctl.SyncTextFromValue(); }

这段只在真正发生夹紧时才标记无效，正常情况下不留任何痕迹。IsLoaded的判断是为了避免初始化阶段的属性赋值触发误报。

5.4 触摸屏与工业面板：尺寸和节奏要单独调

这类控件在桌面场景下用鼠标操作，尺寸紧凑是优点。但在触摸屏、工控面板、自助终端这些场景里，20 像素宽的按钮基本按不准，手指接触面积远大于鼠标指针。这时需要整套尺寸参数一起放大：按钮列宽到 40 以上，行高到 44 以上（这是手指点击的最小舒适尺寸），Delay拉长到 600 毫秒（防止误触发连击），Interval拉长到 120 毫秒。

这些参数全部做成依赖属性之后，在触摸场景的Style里统一覆盖即可，控件代码一行都不用改：

<Style x:Key="TouchNumberUpDown" TargetType="local:NumberUpDown" BasedOn="{StaticResource {x:Type local:NumberUpDown}}"> <Setter Property="SpinButtonWidth" Value="44"/> <Setter Property="SpinButtonDelay" Value="600"/> <Setter Property="SpinButtonInterval" Value="120"/> <Setter Property="FontSize" Value="20"/> <Setter Property="MinHeight" Value="48"/> </Style>

模板里把这些属性TemplateBinding到对应的元素上，切换风格时只换Style引用。这套做法在同一个应用要同时支持桌面端和触摸端的项目里很有用，避免了维护两份控件。

6. 排查实录：那几次让人想砸键盘的坑

6.1 问题速查表

6.2 三个印象最深的坑

第一个是绑定的静默断裂。表现是：界面刚打开一切正常，用户改一次值之后，ViewModel里的数据再也不更新了，但界面上数字还在变。原因是早期版本里用的是Value = next，这行代码把BindingExpression直接覆盖掉了。控件内部看自己的Value属性是正常的，但它和ViewModel的连接已经断了。这个 bug 特别阴险，因为在没有绑定的测试环境里完全复现不出来。改成SetCurrentValue(ValueProperty, next)之后彻底解决。判断一个 WPF 控件写得专不专业，看它内部改自己的依赖属性用的是SetValue还是SetCurrentValue，基本就能看出来。

第二个是格式化导致的精度丢失。有一版用"F2"固定两位小数显示，测试反馈"输入 0.005 变成 0.00 了"。原因是SyncTextFromValue用两位小数格式化，用户提交 0.005 之后，控件显示 0.01（或 0.00，取决于舍入），下一次任何操作触发重新同步时，显示的文本再被解析回Value，就变成了格式化后的值。显示精度不等于存储精度，这两者一定要分开处理：Value保持原始精度，只在显示时按DecimalPlaces格式化，并且格式化后的文本永远不要反向污染Value，除非用户主动提交。

第三个是**Coerce里的无限递归**。某一版在CoerceValue里调用了CoerceValue(ValueProperty)来重新计算，本意是想让范围变化立刻生效，结果造成了栈溢出。原因是Coerce回调里再触发一次强制转换会重入自身。正确做法是范围属性变化时从外部调用CoerceValue(ValueProperty)，而不是在Coerce回调内部调。这个错误的写法在编译期完全没提示，运行时表现为一改范围就崩，堆栈里全是重复的CoerceValue帧，不看堆栈根本想不到是自己调自己。

6.3 投产前的自检清单

• [ ] 内部修改Value全部用SetCurrentValue，无一处裸赋值
• [ ]Minimum、Maximum、Step的变更回调里都调用了CoerceValue(ValueProperty)
• [ ] 模板里的RepeatButton全部设了Focusable="False"
• [ ] 文本解析只在LostFocus/Enter触发，输入过程中不做任何纠正
• [ ]Step有下限校验，配置为 0 或负数时不会死循环
• [ ]IsLoop为真时，边界按钮的禁用触发器不会误触发
• [ ] 粘贴事件已挂载，带分隔符和单位的内容有清洗策略
• [ ] 全角数字归一化已实现，输入法状态下不会出现"输不进数字"
• [ ] 滚轮默认关闭，开启时检查修饰键并设置e.Handled = true
• [ ] 精度：Value类型与业务精度匹配（金额用decimal），显示格式不反向污染存储值
• [ ] 触摸场景有独立Style，按钮尺寸不小于 44 像素

我个人在实际项目里的体会是，这类"看起来很简单"的输入控件，代码量的八成都在处理各种异常输入和时序边界上，真正的"加一减一"只占两行。写完第一版能跑之后，别急着收工，拿它跟用户的真实操作路径对着走一遍：输一半删掉、输到边界、粘贴一堆脏数据、按住按钮不松手、切到别的窗口再切回来。这些路径走完，剩下的问题基本都是可以在自检清单里对号入座的。

最后分享一个小技巧：给控件加一个隐藏的调试开关，按下Ctrl+Shift+D时在输入框下方显示当前Value的原始精度和绑定状态，出问题时让测试同学截图，比让他们描述"数字不对"效率高太多了。这个调试面板二十行 XAML 就能画出来，但能省下的沟通成本远超那点代码量。