feat(Select): support SelectedItem<TValue> generic value (#4512)

* AutoFill改造Select高亮

* refactor: 格式化代码

* Revert "AutoFill改造Select高亮"

This reverts commit b728968.

# Conflicts:
#	src/BootstrapBlazor/Components/AutoFill/AutoFill.razor.cs

* feat: 增加 IModelEqualityComparer 接口

* feat: 增加编辑逻辑

* doc: 更新示例

* doc: 更新示例

* test: 增加 OnChanged 单元测试

* test: 增加 OnSelectedItemChanged 单元测试

* test: 增加单元测试

* test: 更新单元测试

* test: 增加 TextConvertToValueCallback 单元测试

* doc: 增加可编辑功能文档

* doc: 更新文档

---------

Co-authored-by: Argo-AsicoTech <[email protected]>

Author: j4587698

src/BootstrapBlazor.Server/Components/Samples/Selects.razor

@@ -386,17 +386,18 @@
 </DemoBlock>
 
 <DemoBlock Title="@Localizer["SelectsIsEditableTitle"]" Introduction="@Localizer["SelectsIsEditableIntro"]" Name="IsEditable">
+    <section ignore>@((MarkupString)Localizer["SelectsIsEditableDesc"].Value)</section>
     <div class="row">
         <div class="col-12 col-sm-6">
-            <Select TValue="string" Color="Color.Primary" Items="Items" IsEditable="true"></Select>
+            <Select TValue="string" Color="Color.Primary" Items="Items" IsEditable="true" OnInputChangedCallback="OnInputChangedCallback"></Select>
         </div>
     </div>
 </DemoBlock>
 
 <DemoBlock Title="@Localizer["SelectsVirtualizeTitle"]"
            Introduction="@Localizer["SelectsVirtualizeIntro"]"
            Name="IsVirtualize">
-    <p>@((MarkupString)Localizer["SelectsVirtualizeDescription"].Value)</p>
+    <section ignore>@((MarkupString)Localizer["SelectsVirtualizeDescription"].Value)</section>
 
     <div class="row mb-3">
         <div class="col-12 col-sm-6">
@@ -434,6 +435,20 @@
     </div>
 </DemoBlock>
 
+<DemoBlock Title="@Localizer["SelectsGenericTitle"]"
+           Introduction="@Localizer["SelectsGenericIntro"]"
+           Name="Generic">
+    <section ignore>@((MarkupString)Localizer["SelectsGenericDesc"].Value)</section>
+    <div class="row">
+        <div class="col-12 col-sm-6">
+            <Select Items="_genericItems" @bind-Value="_selectedFoo" IsEditable="true"></Select>
+        </div>
+        <div class="col-12 col-sm-6">
+            <Display Value="_selectedFoo?.Address"></Display>
+        </div>
+    </div>
+</DemoBlock>
+
 <AttributeTable Items="@GetAttributes()" />
 
 <EventTable Items="@GetEvents()" />

src/BootstrapBlazor.Server/Components/Samples/Selects.razor.cs

@@ -141,7 +141,7 @@ private async Task OnCascadeBindSelectClick(SelectedItem item)
         }
         else
         {
-            Items2 = Enumerable.Empty<SelectedItem>();
+            Items2 = [];
         }
         StateHasChanged();
     }
@@ -174,6 +174,19 @@ private async Task OnCascadeBindSelectClick(SelectedItem item)
 
     private int? NullableSelectedIntItem { get; set; }
 
+    private Task OnInputChangedCallback(string v)
+    {
+        var item = Items.FirstOrDefault(i => i.Text.Equals(v, StringComparison.OrdinalIgnoreCase));
+        if (item == null)
+        {
+            item = new SelectedItem() { Value = v, Text = v };
+            var items = Items.ToList();
+            items.Insert(0, item);
+            Items = items;
+        }
+        return Task.CompletedTask;
+    }
+
     private string GetSelectedIntItemString()
     {
         return NullableSelectedIntItem.HasValue ? NullableSelectedIntItem.Value.ToString() : "null";
@@ -234,6 +247,15 @@ private Task OnTimeZoneValueChanged(string timeZoneId)
         return Task.CompletedTask;
     }
 
+    private readonly List<SelectedItem<Foo>> _genericItems =
+    [
+        new() { Text = "Foo1", Value = new Foo() { Id = 1, Address = "Address_F001" } },
+        new() { Text = "Foo2", Value = new Foo() { Id = 2, Address = "Address_F002" } },
+        new() { Text = "Foo3", Value = new Foo() { Id = 3, Address = "Address_F003" } }
+    ];
+
+    private Foo? _selectedFoo;
+
     /// <summary>
     /// 获得事件方法
     /// </summary>
@@ -251,6 +273,18 @@ private EventItem[] GetEvents() =>
             Name = "OnBeforeSelectedItemChange",
             Description = Localizer["SelectsOnBeforeSelectedItemChange"],
             Type = "Func<SelectedItem, Task<bool>>"
+        },
+        new()
+        {
+            Name = "OnInputChangedCallback",
+            Description = Localizer["SelectsOnInputChangedCallback"],
+            Type = "Func<string, Task>"
+        },
+        new()
+        {
+            Name = "TextConvertToValueCallback",
+            Description = Localizer["SelectsTextConvertToValueCallback"],
+            Type = "Func<string, Task<TValue>>"
         }
     ];
 
@@ -301,6 +335,14 @@ private AttributeItem[] GetAttributes() =>
             DefaultValue = "Primary"
         },
         new()
+        {
+            Name = "IsEditable",
+            Description = Localizer["SelectsIsEditable"],
+            Type = "boolean",
+            ValueList = "true / false",
+            DefaultValue = "false"
+        },
+        new()
         {
             Name = "IsDisabled",
             Description = Localizer["SelectsIsDisabled"],

src/BootstrapBlazor.Server/Locales/en-US.json

@@ -3177,9 +3177,16 @@
     "SelectsPopoverIntro": "Set <code>IsPopover</code> to <b>true</b>, use <code>popover</code> render UI prevent The dropdown menu cannot be fully displayed because the parent container is set to <code>overflow: hidden</code>",
     "SelectsIsEditableTitle": "Editable",
     "SelectsIsEditableIntro": "By setting <code>IsEditable=\"true\"</code> to make the component editable",
+    "SelectsIsEditableDesc": "After the editable function is enabled, if the input value is not in the candidate items, the new value can be returned through the <code>TextConvertToValueCallback</code> callback method, and the <code>Items</code> data source can be updated through the <code>OnInputChangedCallback</code> callback to prevent the input value from being lost after the page is refreshed.",
     "SelectsVirtualizeTitle": "Virtualize",
     "SelectsVirtualizeIntro": "Set <code>IsVirtualize</code> to <b>true</b> enable virtual scroll for larg data",
-    "SelectsVirtualizeDescription": "Component virtual scrolling supports two ways of providing data through <code>Items</code> or <code>OnQueryAsync</code> callback methods"
+    "SelectsVirtualizeDescription": "Component virtual scrolling supports two ways of providing data through <code>Items</code> or <code>OnQueryAsync</code> callback methods",
+    "SelectsGenericTitle": "Generic",
+    "SelectsGenericIntro": "Data source <code>Items</code> supports generics when using <code>SelectedItem&lt;TValue&gt;</code>",
+    "SelectsGenericDesc": "<p>Please refer to <a href=\"https://github.com/dotnetcore/BootstrapBlazor/issues/4497?wt.mc_id=DT-MVP-5004174\" target=\"_blank\">Design Ideas</a> to understand this feature. In this example, by selecting the drop-down box option, the value obtained is the <code>Foo</code> instance, and the value displayed in the text box on the right is the <code>Address</code> value of the <code>Foo</code> attribute</p><p>In this example, the <code>ValueEqualityComparer</code> and <code>CustomKeyAttribute</code> parameters are not set, and the <code>[Key]</code> tag of the <code>Id</code> attribute of <code>Foo</code> is used for equality judgment</p>",
+    "SelectsOnInputChangedCallback": "Callback method for converting input text into corresponding Value in edit mode",
+    "TextConvertToValueCallback": "Callback method when input text changes in edit mode",
+    "SelectsIsEditable": "Whether editable"
   },
   "BootstrapBlazor.Server.Components.Samples.Sliders": {
     "SlidersTitle": "Slider",

src/BootstrapBlazor.Server/Locales/zh-CN.json

@@ -3177,9 +3177,16 @@
     "SelectsPopoverIntro": "通过设置 <code>IsPopover</code> 参数，组件使用 <code>popover</code> 渲染 <code>UI</code> 防止由于父容器设置 <code>overflow: hidden;</code> 使弹窗无法显示问题",
     "SelectsIsEditableTitle": "可编辑",
     "SelectsIsEditableIntro": "通过设置 <code>IsEditable=\"true\"</code> 使组件可录入",
+    "SelectsIsEditableDesc": "开启可编辑功能后，输入值如果候选项中没有时，可以通过 <code>TextConvertToValueCallback</code> 回调方法返回新值，可以通过 <code>OnInputChangedCallback</code> 回调对 <code>Items</code> 数据源进行更新，防止页面刷新后输入值丢失",
     "SelectsVirtualizeTitle": "虚拟滚动",
     "SelectsVirtualizeIntro": "通过设置 <code>IsVirtualize</code> 参数开启组件虚拟功能特性",
-    "SelectsVirtualizeDescription": "组件虚拟滚动支持两种形式通过 <code>Items</code> 或者 <code>OnQueryAsync</code> 回调方法提供数据"
+    "SelectsVirtualizeDescription": "组件虚拟滚动支持两种形式通过 <code>Items</code> 或者 <code>OnQueryAsync</code> 回调方法提供数据",
+    "SelectsGenericTitle": "泛型支持",
+    "SelectsGenericIntro": "数据源 <code>Items</code> 使用 <code>SelectedItem&lt;TValue&gt;</code> 时即可支持泛型",
+    "SelectsGenericDesc": "<p>请参考 <a href=\"https://github.com/dotnetcore/BootstrapBlazor/issues/4497?wt.mc_id=DT-MVP-5004174\" target=\"_blank\">设计思路</a> 理解此功能。本例中通过选择下拉框选项，得到的值为 <code>Foo</code> 实例，右侧文本框内显示值为 <code>Foo</code> 属性 <code>Address</code> 值</p><p>本例中未设置 <code>ValueEqualityComparer</code> 以及 <code>CustomKeyAttribute</code> 参数，使用 <code>Foo</code> 属性 <code>Id</code> 的 <code>[Key]</code> 标签进行相等判定</p>",
+    "SelectsOnInputChangedCallback": "编辑模式下输入文本转换为对应 Value 回调方法",
+    "TextConvertToValueCallback": "编辑模式下输入文本变化时回调方法",
+    "SelectsIsEditable": "是否可编辑"
   },
   "BootstrapBlazor.Server.Components.Samples.Sliders": {
     "SlidersTitle": "Slider 滑块",

src/BootstrapBlazor/Components/AutoFill/AutoFill.razor.cs

@@ -121,7 +121,7 @@ protected override void OnInitialized()
 
         NoDataTip ??= Localizer[nameof(NoDataTip)];
         PlaceHolder ??= Localizer[nameof(PlaceHolder)];
-        Items ??= Enumerable.Empty<TValue>();
+        Items ??= [];
     }
 
     /// <summary>

src/BootstrapBlazor/Components/Select/Select.razor.cs

@@ -12,7 +12,7 @@ namespace BootstrapBlazor.Components;
 /// Select 组件实现类
 /// </summary>
 /// <typeparam name="TValue"></typeparam>
-public partial class Select<TValue> : ISelect
+public partial class Select<TValue> : ISelect, IModelEqualityComparer<TValue>
 {
     [Inject]
     [NotNull]
@@ -50,7 +50,7 @@ public partial class Select<TValue> : ISelect
     /// <param name="item"></param>
     /// <returns></returns>
     private string? ActiveItem(SelectedItem item) => CssBuilder.Default("dropdown-item")
-        .AddClass("active", () => item.Value == CurrentValueAsString)
+        .AddClass("active", Match(item))
         .AddClass("disabled", item.IsDisabled)
         .Build();
 
@@ -95,6 +95,13 @@ public partial class Select<TValue> : ISelect
     [Parameter]
     public Func<string, Task>? OnInputChangedCallback { get; set; }
 
+    /// <summary>
+    /// 获得/设置 选项输入更新后转换为 Value 回调方法 默认 null
+    /// </summary>
+    /// <remarks>设置 <see cref="IsEditable"/> 后生效</remarks>
+    [Parameter]
+    public Func<string, Task<TValue>>? TextConvertToValueCallback { get; set; }
+
     /// <summary>
     /// 获得/设置 无搜索结果时显示文字
     /// </summary>
@@ -164,6 +171,26 @@ public partial class Select<TValue> : ISelect
     [Parameter]
     public bool DisableItemChangedWhenFirstRender { get; set; }
 
+    /// <summary>
+    /// 获得/设置 比较数据是否相同回调方法 默认为 null
+    /// <para>提供此回调方法时忽略 <see cref="CustomKeyAttribute"/> 属性</para>
+    /// </summary>
+    [Parameter]
+    public Func<TValue, TValue, bool>? ValueEqualityComparer { get; set; }
+
+    Func<TValue, TValue, bool>? IModelEqualityComparer<TValue>.ModelEqualityComparer
+    {
+        get => ValueEqualityComparer;
+        set => ValueEqualityComparer = value;
+    }
+
+    /// <summary>
+    /// 获得/设置 数据主键标识标签 默认为 <see cref="KeyAttribute"/>用于判断数据主键标签，如果模型未设置主键时可使用 <see cref="ValueEqualityComparer"/> 参数自定义判断数据模型支持联合主键
+    /// </summary>
+    [Parameter]
+    [NotNull]
+    public Type? CustomKeyAttribute { get; set; } = typeof(KeyAttribute);
+
     [NotNull]
     private Virtualize<SelectedItem>? VirtualizeElement { get; set; }
 
@@ -300,7 +327,7 @@ private void ResetSelectedItem()
                 _dataSource.AddRange(VirtualItems);
             }
 
-            SelectedItem = _dataSource.Find(i => i.Value.Equals(CurrentValueAsString, StringComparison))
+            SelectedItem = _dataSource.Find(Match)
                 ?? _dataSource.Find(i => i.Active)
                 ?? _dataSource.Where(i => !i.IsDisabled).FirstOrDefault()
                 ?? GetVirtualizeItem();
@@ -337,6 +364,8 @@ private void ResetSelectedItem()
     /// <returns></returns>
     protected override Task InvokeInitAsync() => InvokeVoidAsync("init", Id, Interop, nameof(ConfirmSelectedItem));
 
+    private bool Match(SelectedItem i) => i is SelectedItem<TValue> d ? Equals(d.Value, Value) : i.Value.Equals(CurrentValueAsString, StringComparison);
+
     /// <summary>
     /// 客户端回车回调方法
     /// </summary>
@@ -391,6 +420,27 @@ private async Task OnClickItem(SelectedItem item)
     }
 
     private async Task SelectedItemChanged(SelectedItem item)
+    {
+        if (item is SelectedItem<TValue> d && !Equals(d.Value, Value))
+        {
+            item.Active = true;
+            SelectedItem = item;
+
+            CurrentValue = d.Value;
+
+            // 触发 SelectedItemChanged 事件
+            if (OnSelectedItemChanged != null)
+            {
+                await OnSelectedItemChanged(SelectedItem);
+            }
+        }
+        else
+        {
+            await ValueTypeChanged(item);
+        }
+    }
+
+    private async Task ValueTypeChanged(SelectedItem item)
     {
         if (_lastSelectedValueString != item.Value)
         {
@@ -463,21 +513,54 @@ private async Task OnChange(ChangeEventArgs args)
     {
         if (args.Value is string v)
         {
+            // 判断是否为泛型 SelectedItem
+            var isGeneric = Items.GetType().GetGenericArguments().Length > 0;
+
             // Items 中没有时插入一个 SelectedItem
-            if (Items.FirstOrDefault(i => i.Text == v) == null)
+            var item = Items.FirstOrDefault(i => i.Text == v);
+
+            TValue? val = default;
+            if (item == null)
             {
-                var items = new List<SelectedItem>
+                if (isGeneric)
                 {
-                    new(v, v)
-                };
+                    if (TextConvertToValueCallback != null)
+                    {
+                        val = await TextConvertToValueCallback(v);
+                    }
+                    item = new SelectedItem<TValue>() { Text = v, Value = val };
+                }
+                else
+                {
+                    item = new SelectedItem(v, v);
+                }
+
+                var items = new List<SelectedItem>() { item };
                 items.AddRange(Items);
                 Items = items;
             }
+
+            if (item is SelectedItem<TValue> value)
+            {
+                CurrentValue = value.Value;
+            }
+            else
+            {
+                CurrentValueAsString = v;
+            }
+
             if (OnInputChangedCallback != null)
             {
                 await OnInputChangedCallback(v);
             }
-            CurrentValueAsString = v;
         }
     }
+
+    /// <summary>
+    /// <inheritdoc/>
+    /// </summary>
+    /// <param name="x"></param>
+    /// <param name="y"></param>
+    /// <returns></returns>
+    public bool Equals(TValue? x, TValue? y) => this.Equals<TValue>(x, y);
 }

src/BootstrapBlazor/Misc/IModelEqualityComparer.cs

@@ -11,17 +11,17 @@ namespace BootstrapBlazor.Components;
 public interface IModelEqualityComparer<TItem>
 {
     /// <summary>
-    /// 
+    /// 获得/设置 模型比对回调方法
     /// </summary>
     Func<TItem, TItem, bool>? ModelEqualityComparer { get; set; }
 
     /// <summary>
-    /// 
+    /// 获得/设置 模型键值标签
     /// </summary>
     Type CustomKeyAttribute { get; set; }
 
     /// <summary>
-    /// 
+    /// 相等判定方法
     /// </summary>
     /// <param name="x"></param>
     /// <param name="y"></param>

src/BootstrapBlazor/Misc/SelectedItemOfT.cs

@@ -0,0 +1,17 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the Apache 2.0 License
+// See the LICENSE file in the project root for more information.
+// Maintainer: Argo Zhang([email protected]) Website: https://www.blazor.zone
+
+namespace BootstrapBlazor.Components;
+
+/// <summary>
+/// <see cref="SelectedItem"/> 泛型实现类
+/// </summary>
+public class SelectedItem<T> : SelectedItem
+{
+    /// <summary>
+    /// 获得/设置 泛型值
+    /// </summary>
+    public new T? Value { get; set; }
+}