自定义控件：三色灯与状态指示
这是「从零搭建灌装监控系统」系列第18篇。界面上的红绿圆点、状态标签、液位指示，一开始都是复制粘贴出来的。这篇把它们做成可复用的自定义控件，用依赖属性和值转换器驱动，并讲清一个特别容易踩的 WPF 规则：本地值为什么会盖掉触发器。
改一次配色，翻了十四个文件
界面做到第八个页面的时候，我决定把状态灯的绿色调深一点------现在这个绿在车间的强光下有点发白。
结果我改了十四处。每个页面都有一份自己的 <Ellipse Fill="Green"/>，有的用 #2ECC71，有的用 #27AE60，还有两处是 Lime。改完之后，我甚至不确定有没有漏。
这已经不是审美问题了。状态灯是语义元素------绿灯代表正常、红灯代表故障，这个语义必须在整个软件里一致。散落在各个页面的硬编码颜色，迟早会出现"这个页面的绿灯跟那个页面的绿灯不是一个绿"的情况。
所以要把它们收成控件。
先定义状态，再定义外观
第一步不是写 XAML，是把"灯有几种状态"这件事固化成枚举：
csharp
public enum LightState
{
Off = 0,
Green = 1,
Yellow = 2,
Red = 3
}四个状态对应工业现场的四种语义：熄灭（未启用）、绿（正常）、黄（警告）、红（故障）。
枚举用颜色名还是语义名？ 这是个值得想一秒的问题。用 Green/Red 的坏处是，以后想把"正常"从绿色改成蓝色，枚举就得跟着改，所有绑定点全废。用 Normal/Fault 就没这个问题。
这个项目选了颜色名，因为它就是给三色灯用的，物理灯珠的颜色是固定的，语义和颜色一一对应，不会变。但如果是一个通用的状态指示器，我会用语义名。判断依据是：颜色本身是不是业务的一部分。 三色灯是，通用指示器不是。
依赖属性：控件的对外接口
控件要能被绑定，就得用依赖属性：
csharp
public partial class StatusLight : UserControl
{
public LightState State
{
get { return (LightState)GetValue(StateProperty); }
set { SetValue(StateProperty, value); }
}
public static readonly DependencyProperty StateProperty =
DependencyProperty.Register(
nameof(State),
typeof(LightState),
typeof(StatusLight),
new PropertyMetadata(LightState.Off));
public StatusLight()
{
InitializeComponent();
}
}PropertyMetadata(LightState.Off) 是默认值------没绑定时灯是熄灭的，而不是某种未定义状态。
注册依赖属性时把类型写成 typeof(LightState) 而不是 typeof(int)，WPF 才能在 XAML 里做类型检查和设计器提示。
调用方用起来就很干净：
xml
<uc:StatusLight State="{Binding PlcState}"/>值转换器：一个枚举，三种灯珠
三色灯有三个灯珠，每个灯珠只在对应状态下亮。同一个 State 属性要驱动三个不同的画刷，怎么区分？
用 ConverterParameter：
csharp
public class LightStateToBrushConverter : IValueConverter
{
public object Convert(object value, Type targetType,
object parameter, CultureInfo culture)
{
if (value is not LightState state)
return Brushes.DimGray;
var target = parameter as string;
// 只点亮与目标灯位匹配的那一颗
return state.ToString() == target
? GetLitBrush(target)
: GetDimBrush(target);
}
public object ConvertBack(object value, Type targetType,
object parameter, CultureInfo culture)
=> throw new NotSupportedException();
}XAML 里三个灯珠各自传不同的参数：
xml
<cv:LightStateToBrushConverter x:Key="LightStateToBrushConverter"/>
<!-- 绿灯 -->
<Ellipse x:Name="GreenEllipse" Stroke="#111" StrokeThickness="1.5">
<Ellipse.Fill>
<LinearGradientBrush StartPoint="0.2,0" EndPoint="0.8,1">
<GradientStop Color="White" Offset="0"/>
<GradientStop Color="{Binding State,
RelativeSource={RelativeSource AncestorType=UserControl},
Converter={StaticResource LightStateToBrushConverter},
ConverterParameter=Green}" Offset="0.4"/>
<GradientStop Color="#88000000" Offset="1"/>
</LinearGradientBrush>
</Ellipse.Fill>
</Ellipse>RelativeSource AncestorType=UserControl 是关键------灯珠在控件模板内部，要往外找到宿主控件的 State 属性。这是自定义控件里绑定自己属性的标准写法。
灯珠的视觉：三层叠加
工业界面的灯珠如果只是一个纯色圆，看起来像贴纸。稍微加三层就有质感：
xml
<!-- 第一层：外圈高光（径向渐变） -->
<Ellipse>
<Ellipse.Fill>
<RadialGradientBrush>
<GradientStop Color="#00000000" Offset="0"/>
<GradientStop Color="#22000000" Offset="1"/>
</RadialGradientBrush>
</Ellipse.Fill>
</Ellipse>
<!-- 第二层：灯珠本体（线性渐变 + 模糊光晕） -->
<Ellipse x:Name="GreenEllipse" Stroke="#111" StrokeThickness="1.5">
<Ellipse.Effect>
<BlurEffect Radius="2" KernelType="Gaussian"/>
</Ellipse.Effect>
</Ellipse>
<!-- 外层：灯座（深色圆角矩形 + 投影） -->
<Border CornerRadius="10" Background="#222"
BorderBrush="#111" BorderThickness="2">
<Border.Effect>
<DropShadowEffect ShadowDepth="3" BlurRadius="8" Opacity="0.3"/>
</Border.Effect>
</Border>线性渐变里的三个 GradientStop 分工明确：White 在左上角做高光，中间 40% 位置是实际灯色，#88000000 在右下角压暗做体积感。BlurEffect 让亮起的灯珠有轻微光晕，DropShadowEffect 让整个灯座有立体感。
这些都是纯视觉的，但工业界面恰恰需要这个------操作员在几米外扫一眼，有光晕的灯比纯色圆更容易被注意到。
数据流：
#mermaid-svg-mMnHWfiBZY65NtCi{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-mMnHWfiBZY65NtCi .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-mMnHWfiBZY65NtCi .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-mMnHWfiBZY65NtCi .error-icon{fill:#552222;}#mermaid-svg-mMnHWfiBZY65NtCi .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-mMnHWfiBZY65NtCi .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-mMnHWfiBZY65NtCi .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-mMnHWfiBZY65NtCi .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-mMnHWfiBZY65NtCi .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-mMnHWfiBZY65NtCi .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-mMnHWfiBZY65NtCi .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-mMnHWfiBZY65NtCi .marker{fill:#333333;stroke:#333333;}#mermaid-svg-mMnHWfiBZY65NtCi .marker.cross{stroke:#333333;}#mermaid-svg-mMnHWfiBZY65NtCi svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-mMnHWfiBZY65NtCi p{margin:0;}#mermaid-svg-mMnHWfiBZY65NtCi .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-mMnHWfiBZY65NtCi .cluster-label text{fill:#333;}#mermaid-svg-mMnHWfiBZY65NtCi .cluster-label span{color:#333;}#mermaid-svg-mMnHWfiBZY65NtCi .cluster-label span p{background-color:transparent;}#mermaid-svg-mMnHWfiBZY65NtCi .label text,#mermaid-svg-mMnHWfiBZY65NtCi span{fill:#333;color:#333;}#mermaid-svg-mMnHWfiBZY65NtCi .node rect,#mermaid-svg-mMnHWfiBZY65NtCi .node circle,#mermaid-svg-mMnHWfiBZY65NtCi .node ellipse,#mermaid-svg-mMnHWfiBZY65NtCi .node polygon,#mermaid-svg-mMnHWfiBZY65NtCi .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-mMnHWfiBZY65NtCi .rough-node .label text,#mermaid-svg-mMnHWfiBZY65NtCi .node .label text,#mermaid-svg-mMnHWfiBZY65NtCi .image-shape .label,#mermaid-svg-mMnHWfiBZY65NtCi .icon-shape .label{text-anchor:middle;}#mermaid-svg-mMnHWfiBZY65NtCi .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-mMnHWfiBZY65NtCi .rough-node .label,#mermaid-svg-mMnHWfiBZY65NtCi .node .label,#mermaid-svg-mMnHWfiBZY65NtCi .image-shape .label,#mermaid-svg-mMnHWfiBZY65NtCi .icon-shape .label{text-align:center;}#mermaid-svg-mMnHWfiBZY65NtCi .node.clickable{cursor:pointer;}#mermaid-svg-mMnHWfiBZY65NtCi .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-mMnHWfiBZY65NtCi .arrowheadPath{fill:#333333;}#mermaid-svg-mMnHWfiBZY65NtCi .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-mMnHWfiBZY65NtCi .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-mMnHWfiBZY65NtCi .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-mMnHWfiBZY65NtCi .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-mMnHWfiBZY65NtCi .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-mMnHWfiBZY65NtCi .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-mMnHWfiBZY65NtCi .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-mMnHWfiBZY65NtCi .cluster text{fill:#333;}#mermaid-svg-mMnHWfiBZY65NtCi .cluster span{color:#333;}#mermaid-svg-mMnHWfiBZY65NtCi div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-mMnHWfiBZY65NtCi .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-mMnHWfiBZY65NtCi rect.text{fill:none;stroke-width:0;}#mermaid-svg-mMnHWfiBZY65NtCi .icon-shape,#mermaid-svg-mMnHWfiBZY65NtCi .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-mMnHWfiBZY65NtCi .icon-shape p,#mermaid-svg-mMnHWfiBZY65NtCi .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-mMnHWfiBZY65NtCi .icon-shape rect,#mermaid-svg-mMnHWfiBZY65NtCi .image-shape rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-mMnHWfiBZY65NtCi .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-mMnHWfiBZY65NtCi .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-mMnHWfiBZY65NtCi :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 绑定 State
ConverterParameter=Green
ConverterParameter=Yellow
ConverterParameter=Red
ViewModel 状态
StatusLight 依赖属性
值转换器
绿灯画刷
黄灯画刷
红灯画刷
灯珠渐变 + 光晕
StatusIndicator：多属性组合的状态指示
三色灯是纯视觉的，但界面上还需要"在线/离线 + 状态文字"这种组合指示。做法一样，只是属性多了几个：
csharp
public partial class StatusIndicator : UserControl
{
public bool IsOnline
{
get => (bool)GetValue(IsOnlineProperty);
set => SetValue(IsOnlineProperty, value);
}
public bool IsWarning
{
get => (bool)GetValue(IsWarningProperty);
set => SetValue(IsWarningProperty, value);
}
public string StatusText
{
get => (string)GetValue(StatusTextProperty);
set => SetValue(StatusTextProperty, value);
}
public static readonly DependencyProperty IsOnlineProperty =
DependencyProperty.Register(nameof(IsOnline), typeof(bool),
typeof(StatusIndicator), new PropertyMetadata(false));
public static readonly DependencyProperty IsWarningProperty =
DependencyProperty.Register(nameof(IsWarning), typeof(bool),
typeof(StatusIndicator), new PropertyMetadata(false));
public static readonly DependencyProperty StatusTextProperty =
DependencyProperty.Register(nameof(StatusText), typeof(string),
typeof(StatusIndicator), new PropertyMetadata(string.Empty));
}为什么拆成 IsOnline + IsWarning 两个布尔，而不是一个三态枚举？因为这两个维度是独立的：设备可能在线但处于警告状态（温度偏高），也可能离线（此时警告与否没意义）。用两个布尔，组合语义更清楚。
那个特别容易踩的坑：本地值压过触发器
这个坑我在别处栽过一次，值得单独说。
在 StatusLight 里，我想让红灯亮的时候有一个呼吸动画，就写了 DataTrigger。但怎么都不生效------灯色变了，动画不动。
原因是 WPF 的属性值优先级：
本地值（Local Value） > 触发器（Trigger） > 样式 Setter（Style Setter） > 默认值如果我在元素上直接写了 Opacity="1.0"，这是本地值 ，优先级最高。之后不管 DataTrigger 怎么设置，都改不动它。
正确做法是把默认值写进 Style 的 Setter：
xml
<Ellipse x:Name="ValueEllipse" Width="10" Height="10">
<Ellipse.Style>
<Style TargetType="Ellipse">
<!-- 默认值写在 Setter 里，而不是元素属性上 -->
<Setter Property="Fill" Value="{StaticResource AppTextMuted}"/>
<Setter Property="Opacity" Value="1.0"/>
<Style.Triggers>
<DataTrigger Binding="{Binding ValueOpen}" Value="True">
<Setter Property="Fill" Value="{StaticResource AppSuccess}"/>
<DataTrigger.EnterActions>
<BeginStoryboard>
<Storyboard RepeatBehavior="Forever" AutoReverse="True">
<DoubleAnimation Storyboard.TargetProperty="Opacity"
From="1.0" To="0.3" Duration="0:0:1"/>
</Storyboard>
</BeginStoryboard>
</DataTrigger.EnterActions>
</DataTrigger>
</Style.Triggers>
</Style>
</Ellipse.Style>
</Ellipse>现在 Opacity 的初始值是 Style Setter（优先级低），触发器就能盖过它，动画生效。
记法 ：只要你想让某个属性被触发器或动画改变，它的初始值就不能写成元素上的属性，必须写进 Style 的 Setter。
控件里不要塞业务
做自定义控件时有个诱惑：既然控件要显示"PLC 在线状态"，干脆在里面直接调 PlcService 好了。
不要这么做。UserControl 应该是纯展示 的------数据从 DataContext 或依赖属性进来，控件自己不知道数据从哪来。
理由很实际：
- 控件能在设计器里预览（没有服务也能渲染）
- 控件能被单元测试
- 同一个控件能在不同数据源下复用
这个项目里 HMI 那套控件就是这么约束的------控件内不允许引用任何 Service。约束看起来麻烦，但它让控件的复用边界非常清晰。
踩坑记录
本地值让触发器失效
元素上写死的属性优先级最高，DataTrigger 和动画都盖不过。默认值必须写进 Style 的 Setter。
在控件内部直接改依赖属性
用 SetValue 覆盖绑定值，会让外部的绑定失效。控件内部只读不写自己的依赖属性。
控件里引用 Service
设计器打不开、测试写不了、复用不了。数据一律从属性进。
枚举用颜色名还是语义名没想清楚
三色灯可以用颜色名，通用指示器应该用语义名。判断标准是颜色本身是不是业务的一部分。
本篇小结
| 目标 | 做法 |
|---|---|
| 状态语义统一 | LightState 枚举集中定义 |
| 可绑定 | 依赖属性 + PropertyMetadata 默认值 |
| 一个状态驱动多个视觉 | ConverterParameter 区分灯位 |
| 控件内绑定自身属性 | RelativeSource AncestorType=UserControl |
| 触发器生效 | 默认值写 Style Setter，不写元素属性 |
| 控件可复用 | 纯展示，不引用 Service |
到这里界面部分基本成型了。但每次改完代码，我都得手动跑一遍软件、点几个按钮、扫一次条码，才能确认没改坏。下一步该让机器替我干这件事了。
下期预告
第19篇：单元测试实战：xUnit + 内存SQLite + 反射测试私有方法
下一篇搭起测试工程，用临时 SQLite 文件做数据隔离，再用反射把私有方法拉出来测------包括一个方法名拼错的真实案例。