KinloControls 1.3.2

KinloControls 使用说明书

KinloControls 是面向 .NET 8 WPF 的自定义控件库，适用于自动化设备、生产看板和桌面管理软件，包含选择器、导航、页面动画、仪表盘、时间轴及常用绑定工具。

1. 引用与命名空间

• 目标框架：net8.0-windows
• UI 框架：WPF
• 控件命名空间：KinloControls
• 工具命名空间：KinloControls.Tools

<ProjectReference Include="..\KinloControls\KinloControls.csproj" />

xmlns:kc="clr-namespace:KinloControls;assembly=KinloControls"
xmlns:kct="clr-namespace:KinloControls.Tools;assembly=KinloControls"

默认样式已通过 Themes/Generic.xaml 注册，正常引用程序集后无需手动合并主题字典。

2. 控件总览

3. ClockPicker 时间选择器

Time 默认双向绑定，有效范围为 00:00:00～23:59:59。

<kc:ClockPicker Width="260"
                Title="启动时间"
                TitleWidth="90"
                Time="{Binding StartTime, Mode=TwoWay}"
                CornerRadius="6"
                IconBackground="#326CF3" />

4. SliderControl 滑块选择器

用于工序、页面或数据分类选择。SelectedIndex 和 SelectedItem 默认双向绑定；没有绑定选择项时，有数据会默认选中第一项。

<kc:SliderControl ItemsSource="{Binding Processes}"
                  DisplayMemberPath="Description"
                  SelectedIndex="{Binding SelectedProcessIndex, Mode=TwoWay}"
                  SliderBackground="{StaticResource PrimaryBrush}"
                  SliderCornerRadius="5"
                  TabHorizontalAlignment="Left"
                  TabWidth="105" />

选择事件：

<kc:SliderControl SelectionChanged="Slider_SelectionChanged" />

private void Slider_SelectionChanged(object sender, KinloControls.SelectionChangedEventArgs e)
{
    var oldItem = e.OldItem;
    var newItem = e.NewItem;
}

固定时长动画（兼容旧版本的默认模式）：

<kc:SliderControl AnimationDurationMode="Fixed"
                  AnimationDuration="0:0:0.3" />

按距离计算动画，近距离快、远距离慢：

<kc:SliderControl AnimationDurationMode="ByDistance"
                  AnimationPixelsPerSecond="800"
                  MinimumAnimationDuration="0:0:0.08"
                  MaximumAnimationDuration="0:0:0.5" />

连续快速切换时，新动画从滑块当前视觉位置转向新目标，不会跳回旧起点。

5. VerticalNav 垂直导航

支持图标、文字、选中项、页头页脚，以及鼠标移入展开、移出收缩。

<kc:VerticalNav ItemsSource="{Binding Menus}"
                DisplayMemberPath="Title"
                IconMemberPath="Icon"
                SelectedIndex="{Binding SelectedMenuIndex, Mode=TwoWay}"
                ItemHeight="44"
                ItemMargin="4,2"
                ItemCornerRadius="6"
                ShrinkWidth="64"
                ExpandWidth="220"
                ShrinkDelay="300" />

SelectionChanged 事件用法与 SliderControl 相同。

6. SlidingContentControl 页面切换

内容改变时保留上一页并播放过渡动画，适合绑定当前页面或视图模型。

<kc:SlidingContentControl Content="{Binding CurrentPage}"
                          Slide="Up"
                          ShakeMode="Rebound"
                          TransitionDuration="0:0:0.42"
                          ShakeAmplitude="8"
                          ShakeDelayRatio="0.72" />

快速切页时控件会停止旧动画，并忽略已经过期的延迟动画任务。

7. HourlyTimeAxis 小时时间轴

展示小时产量，自动识别并定位当前小时。支持鼠标拖动和滚轮浏览；用户空闲约 10 秒后重新定位当前小时。

<kc:HourlyTimeAxis ItemsSource="{Binding HourlyItems}" />

public ObservableCollection<HourlyData> HourlyItems { get; } =
[
    new HourlyData
    {
        Time = DateTime.Today.AddHours(8),
        Subtitle = "08时",
        InputCount = 120,
        ProductionCount = 116,
        InputPrefix = "进 ",
        ValuePrefix = "出 "
    }
];

HourlyData 包含：

• Time、只读 Hour、IsCurrentHour
• InputCount、InputPrefix、InputSuffix、只读 InputDisplayValue
• ProductionCount、ValuePrefix、ValueSuffix、只读 DisplayValue
• Subtitle

IsCurrentHour 由控件自动维护。

8. TimelineChart 普通时间轴

适合展示设备运行、报警、待机等状态区间，支持悬浮提示、缩放、拖动及图例统计。

<kc:TimelineChart Header="设备状态"
                  CornerRadius="8"
                  TimelineItems="{Binding TimelineItems}" />

public ObservableCollection<TimelineItem> TimelineItems { get; } =
[
    new TimelineItem
    {
        Id = 1,
        Label = "运行",
        StartTime = DateTime.Today.AddHours(8),
        EndTime = DateTime.Today.AddHours(9),
        Color = Brushes.LimeGreen,
        Message = "正常生产",
        IsFinish = true
    }
];

TimelineItem 包含 Id、Value、Label、StartTime、EndTime、Color、Message 和 IsFinish。

9. OverlappingStateTimelineChart 重叠时间轴

用于同一时间点可能存在多个状态的场景，通过时间切片避免状态互相覆盖，并提供缩放、拖动、悬浮明细和底部统计。

<kc:OverlappingStateTimelineChart Header="并行状态"
                                  CornerRadius="8"
                                  Items="{Binding TimelineItems}" />

数据模型同样使用 TimelineItem。同一时间段有多条记录时会按重叠状态绘制。

10. NeonGauge 霓虹仪表盘

<kc:NeonGauge Width="260" Height="260"
              Minimum="0" Maximum="100"
              Value="{Binding Pressure}"
              UnitText="kPa"
              OuterStartAngle="135"
              OuterSweepAngle="270"
              ProgressWidth="20"
              TickLength="15"
              TextColor="White" />

默认值：Value=0、Minimum=0、Maximum=100、OuterStartAngle=135、OuterSweepAngle=270、ProgressWidth=20、TickLength=15、UnitText=Kpa、UnitFontSize=11。

ProgressBrush 类型为 LinearGradientBrush，NeedleColor 类型为 Color。应保证 Maximum > Minimum。

11. MinimalGauge 精简仪表盘

<kc:MinimalGauge Width="220" Height="160"
                 Minimum="0" Maximum="10"
                 Value="{Binding Flow}"
                 UnitText="L/min"
                 OuterStartAngle="150"
                 OuterSweepAngle="240"
                 ProgressWidth="16"
                 NeedleThickess="3" />

默认值：Value=0、Minimum=0、Maximum=100、OuterStartAngle=150、OuterSweepAngle=240、ProgressWidth=16、NeedleThickess=3、UnitText=Kpa、UnitFontSize=11。

注意：公开属性当前名为 NeedleThickess，这是为兼容现有调用保留的拼写。

12. 公共工具

ObservableRangeCollection

位于 KinloControls.Tools，批量操作只发送一次集合重置通知：

var items = new ObservableRangeCollection<DeviceModel>();
items.AddRange(deviceList);
items.RemoveRange(disabledDevices);
items.ReplaceRange(newList);
items.SortBy(x => x.Index);

提供 AddRange、RemoveRange、RemoveAtRange、ReplaceRange、Sort 和 SortBy。

LanguageResource

根据资源键动态设置文字，资源不存在时显示键本身：

<TextBlock kc:LanguageResource.Key="Home_Title" />
<Button kc:LanguageResource.Key="Save_Button" />

默认支持 TextBlock.Text、TextBox.Text、常用内容控件的 Content、标题控件的 Header 和 Window.Title。

ResourceBinding

将普通绑定值解释为动态资源键；资源不存在时尝试直接使用原值：

<Border Background="{kc:ResourceBinding ThemeBrushKey}" />

FuzzyMatcherUniversal

对英文字母、数字和中文字段进行模糊匹配：

var candidates = FuzzyMatcherUniversal.Match(
    "inputcount",
    new List<(string localField, object tag)>
    {
        ("InputCount", "进站数量"),
        ("OutputCount", "出站数量")
    },
    topN: 3,
    threshold: 0.25);

返回的 FieldMatchResult 包含 LocalField、Score 和原样返回的 Tag。

13. 自定义模板

复制对应主题中的默认模板后再修改，并保留代码声明的 PART_ 部件：

缺少模板部件时，对应显示或交互能力不可用。

14. 绑定与线程注意事项

• SelectedIndex、SelectedItem、ClockPicker.Time 默认双向绑定。
• 集合建议使用 ObservableCollection<T> 或 ObservableRangeCollection<T>。
• WPF 集合和绑定对象原则上应在 UI 线程更新。
• 时间轴数据应满足 EndTime >= StartTime。
• 仪表盘应满足 Maximum > Minimum，业务层按需限制 Value 范围。
• 动态增删数据时，ItemsSource 应实现 INotifyCollectionChanged。

15. 构建

dotnet build KinloControls.csproj

Debug 输出：bin\Debug\net8.0-windows\KinloControls.dll。