author-component

编写 Blazor 组件

核心规则

• 数据通过 [Parameter] 向下传递。事件通过 EventCallback<T> 向上传递（绝不使用 Action/Func）。
• 绝不修改 [Parameter] 属性。在 OnParametersSet 中将其复制到私有字段。
• 使用 [Parameter] public T Prop { get; set; } — 绝不使用 required 或 init（会触发 BL0007）。
• 对必需参数使用 [EditorRequired]。
• 处理所有状态：加载中、空、已加载、错误 — 每种状态都使用 @if/@else。
• 在循环的重复元素上使用 @key，以提高差异比对效率。
• 集合参数使用 IReadOnlyList<T>（而不是 IEnumerable<T>）。

RenderFragment 与泛型

[Parameter] public RenderFragment? ChildContent { get; set; }
[Parameter] public RenderFragment<TItem>? RowTemplate { get; set; }  // generic template

对泛型组件使用 @typeparam TItem。

文件模式

• 单文件： 当逻辑少于约 50 行时，使用带 @code 块的 .razor。
• 代码隐藏： 当逻辑超过约 50 行时，使用 .razor + .razor.cs 和 partial class。

释放

当组件拥有订阅、计时器或 CTS 时，实现 IAsyncDisposable（而不是 IDisposable）。 在 DisposeAsync 中：取消订阅（-=）、取消 CTS、释放资源。绝不调用 StateHasChanged。

异步模式

• 对每个异步操作都使用 await。绝不使用 .Result、.Wait()、Task.Run、ContinueWith、Thread.Start。
• 防抖： 使用 Task.Delay + CancellationTokenSource。取消旧 CTS，创建新的 CTS，等待延迟，然后执行操作。绝不使用 System.Threading.Timer 或 System.Timers.Timer。
• 轮询： 在 OnInitializedAsync 中使用带 await Task.Delay(interval, token) 的循环 — 这样会留在同步上下文中。
• 外部事件（Action<T>）：使用 async void 处理程序 + await InvokeAsync(() => { state++; StateHasChanged(); }) + catch → DispatchExceptionAsync。绝不使用 _ = InvokeAsync(...)。
• 在 DisposeAsync 中取消 CTS。不要捕获 ObjectDisposedException — 使用 CTS 取消。

禁止事项

• [Parameter] 上使用 required/init — 会导致运行时故障
• 修改 [Parameter] — 在 OnParametersSet 中复制到私有字段
• 用 Action/Func 处理事件 — 使用 EventCallback<T>
• 使用 Task.Run/.Result/.Wait()/Timer 实现防抖 — 会导致死锁或逃逸到线程池
• 内联 style 属性 — 使用 CSS 类或 data-* 属性
• catch { throw; } — 使用 when 守卫，或让异常继续传播
• 过度设计：未被要求的 ARIA、包装 div、无障碍功能
• _ = InvokeAsync(...) — 会吞掉异常；使用 async void + DispatchExceptionAsync