doc(Select): update documentation (#5638)

* refactor: 重构组件变量改用私有字段

* refactor: 文档注释更改英文

* chore: bump version 9.4.9-beta09

Co-Authored-By: trycatchfinnally <[email protected]>

---------

Co-authored-by: trycatchfinnally <[email protected]>

Author: ArgoZhang

src/BootstrapBlazor/BootstrapBlazor.csproj

@@ -1,7 +1,7 @@
 <Project Sdk="Microsoft.NET.Sdk.Razor">
 
   <PropertyGroup>
-    <Version>9.4.9-beta08</Version>
+    <Version>9.4.9-beta09</Version>
   </PropertyGroup>
 
   <ItemGroup>

src/BootstrapBlazor/Components/Select/Select.razor

@@ -48,7 +48,7 @@
                     }
                     else
                     {
-                        <Virtualize ItemSize="RowHeight" OverscanCount="OverscanCount" ItemsProvider="LoadItems" Placeholder="RenderPlaceHolderRow" ItemContent="RenderRow" @ref="VirtualizeElement" />
+                        <Virtualize ItemSize="RowHeight" OverscanCount="OverscanCount" ItemsProvider="LoadItems" Placeholder="RenderPlaceHolderRow" ItemContent="RenderRow" @ref="_virtualizeElement" />
                     }
                 </div>
             }

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

@@ -144,9 +144,6 @@ public partial class Select<TValue> : ISelect, ILookup
     [Parameter]
     public bool DisableItemChangedWhenFirstRender { get; set; }
 
-    [NotNull]
-    private Virtualize<SelectedItem>? VirtualizeElement { get; set; }
-
     /// <summary>
     /// Gets or sets the bound data set.
     /// </summary>
@@ -247,6 +244,9 @@ public partial class Select<TValue> : ISelect, ILookup
     /// </summary>
     protected override string? RetrieveId() => InputId;
 
+    [NotNull]
+    private Virtualize<SelectedItem>? _virtualizeElement = default;
+
     private string? InputId => $"{Id}_input";
 
     private string _lastSelectedValueString = string.Empty;
@@ -409,7 +409,7 @@ private async Task RefreshVirtualizeElement()
         if (IsVirtualize && OnQueryAsync != null)
         {
             // 通过 ItemProvider 提供数据
-            await VirtualizeElement.RefreshDataAsync();
+            await _virtualizeElement.RefreshDataAsync();
         }
     }
 
@@ -556,7 +556,7 @@ private async Task OnClearValue()
 
         if (OnQueryAsync != null)
         {
-            await VirtualizeElement.RefreshDataAsync();
+            await _virtualizeElement.RefreshDataAsync();
         }
 
         _lastSelectedValueString = string.Empty;

src/BootstrapBlazor/Components/Select/SelectBase.cs

@@ -6,107 +6,108 @@
 namespace BootstrapBlazor.Components;
 
 /// <summary>
-/// SelectBase 组件基类
+/// SelectBase component base class
 /// </summary>
+/// <typeparam name="TValue">The type of the value.</typeparam>
 public abstract class SelectBase<TValue> : PopoverSelectBase<TValue>
 {
     /// <summary>
-    /// 获得/设置 颜色 默认 Color.None 无设置
+    /// Gets or sets the color. The default is <see cref="Color.None"/> (no color).
     /// </summary>
     [Parameter]
     public Color Color { get; set; }
 
     /// <summary>
-    /// 获得/设置 是否显示搜索框 默认为 false 不显示
+    /// Gets or sets a value indicating whether to show the search box. The default is <c>false</c>.
     /// </summary>
     [Parameter]
     public bool ShowSearch { get; set; }
 
     /// <summary>
-    /// 获得/设置 设置搜索图标
+    /// Gets or sets the search icon.
     /// </summary>
     [Parameter]
     public string? SearchIcon { get; set; }
 
     /// <summary>
-    /// 获得/设置 设置正在搜索图标
+    /// Gets or sets the search loading icon.
     /// </summary>
     [Parameter]
     public string? SearchLoadingIcon { get; set; }
 
     /// <summary>
-    /// 获得/设置 搜索框文本
+    /// Gets or sets the search text.
     /// </summary>
     [NotNull]
     protected string? SearchText { get; set; }
 
     /// <summary>
-    /// 获得/设置 无搜索结果时显示文字
+    /// Gets or sets the text to display when no search results are found.
     /// </summary>
     [Parameter]
     public string? NoSearchDataText { get; set; }
 
     /// <summary>
-    /// 获得/设置 右侧下拉箭头图标 默认 fa-solid fa-angle-up
+    /// Gets or sets the dropdown icon. The default is "fa-solid fa-angle-up".
     /// </summary>
     [Parameter]
     [NotNull]
     public string? DropdownIcon { get; set; }
 
     /// <summary>
-    /// 获得/设置 是否为 MarkupString 默认 false
+    /// Gets or sets a value indicating whether the content is a <see cref="MarkupString"/>. The default is <c>false</c>.
     /// </summary>
     [Parameter]
     public bool IsMarkupString { get; set; }
 
     /// <summary>
-    /// 获得/设置 字符串比较规则 默认 StringComparison.OrdinalIgnoreCase 大小写不敏感
+    /// Gets or sets the string comparison rule. The default is <see cref="StringComparison.OrdinalIgnoreCase"/>.
     /// </summary>
     [Parameter]
     public StringComparison StringComparison { get; set; } = StringComparison.OrdinalIgnoreCase;
 
     /// <summary>
-    /// 获得/设置 分组项模板
+    /// Gets or sets the group item template.
     /// </summary>
     [Parameter]
     public RenderFragment<string>? GroupItemTemplate { get; set; }
 
     /// <summary>
-    /// 获得/设置 滚动行为 默认 <see cref="ScrollIntoViewBehavior.Smooth"/>
+    /// Gets or sets the scroll behavior. The default is <see cref="ScrollIntoViewBehavior.Smooth"/>.
     /// </summary>
     [Parameter]
     public ScrollIntoViewBehavior ScrollIntoViewBehavior { get; set; } = ScrollIntoViewBehavior.Smooth;
 
     /// <summary>
-    /// 获得/设置 IIconTheme 服务实例
+    /// Gets or sets the <see cref="IIconTheme"/> service instance.
     /// </summary>
     [Inject]
     [NotNull]
     protected IIconTheme? IconTheme { get; set; }
 
     /// <summary>
-    /// 获得 PlaceHolder 属性
+    /// Gets or sets the placeholder text.
     /// </summary>
     [Parameter]
     public string? PlaceHolder { get; set; }
 
     /// <summary>
-    /// 获得 SearchIcon 图标字符串 默认增加 icon 样式
+    /// Gets the search icon string with default "icon search-icon" class.
     /// </summary>
     protected string? SearchIconString => CssBuilder.Default("icon search-icon")
         .AddClass(SearchIcon)
         .Build();
 
     /// <summary>
-    /// <inheritdoc/>
+    /// Gets the custom class string.
     /// </summary>
     protected override string? CustomClassString => CssBuilder.Default()
         .AddClass("select", IsPopover)
         .AddClass(base.CustomClassString)
         .Build();
 
     /// <summary>
-    /// 获得 样式集合
+    /// Gets the append class string.
     /// </summary>
     protected string? AppendClassString => CssBuilder.Default("form-select-append")
         .AddClass($"text-{Color.ToDescriptionString()}", Color != Color.None && !IsDisabled && !IsValid.HasValue)
@@ -126,14 +127,14 @@ protected override void OnParametersSet()
     }
 
     /// <summary>
-    /// 显示下拉框方法
+    /// Shows the dropdown.
     /// </summary>
-    /// <returns></returns>
+    /// <returns>A <see cref="Task"/> representing the asynchronous operation.</returns>
     public Task Show() => InvokeVoidAsync("show", Id);
 
     /// <summary>
-    /// 关闭下拉框方法
+    /// Hides the dropdown.
     /// </summary>
-    /// <returns></returns>
+    /// <returns>A <see cref="Task"/> representing the asynchronous operation.</returns>
     public Task Hide() => InvokeVoidAsync("hide", Id);
 }

src/BootstrapBlazor/Components/Select/SelectOption.cs

@@ -6,48 +6,45 @@
 namespace BootstrapBlazor.Components;
 
 /// <summary>
-/// SelectOption 组件
+/// SelectOption component
 /// </summary>
 public class SelectOption : ComponentBase
 {
     /// <summary>
-    /// 获得/设置 显示名称
+    /// Gets or sets the display name.
     /// </summary>
     [Parameter]
     public string? Text { get; set; }
 
     /// <summary>
-    /// 获得/设置 选项值
+    /// Gets or sets the option value.
     /// </summary>
     [Parameter]
     public string? Value { get; set; }
 
     /// <summary>
-    /// 获得/设置 是否选中 默认 false
+    /// Gets or sets a value indicating whether the option is selected. Default is <c>false</c>.
     /// </summary>
     [Parameter]
     public bool Active { get; set; }
 
     /// <summary>
-    /// 获得/设置 是否禁用 默认 false
+    /// Gets or sets a value indicating whether the option is disabled. Default is <c>false</c>.
     /// </summary>
     [Parameter]
     public bool IsDisabled { get; set; }
 
     /// <summary>
-    /// 获得/设置 分组名称
+    /// Gets or sets the group name.
     /// </summary>
     [Parameter]
     public string? GroupName { get; set; }
 
-    /// <summary>
-    /// 父组件通过级联参数获得
-    /// </summary>
     [CascadingParameter]
     private ISelect? Container { get; set; }
 
     /// <summary>
-    /// OnInitialized 方法
+    /// <inheritdoc/>
     /// </summary>
     protected override void OnInitialized()
     {
@@ -56,6 +53,10 @@ protected override void OnInitialized()
         Container?.Add(ToSelectedItem());
     }
 
+    /// <summary>
+    /// Converts the current instance to a <see cref="SelectedItem"/>.
+    /// </summary>
+    /// <returns>A <see cref="SelectedItem"/> instance.</returns>
     private SelectedItem ToSelectedItem() => new()
     {
         Active = Active,