我有2个自用的组件，请看一下，能否加入到bootstrapblazor里？

[shakugans]

一个是区域拖拽，一个是轮盘展开，组合起来使用感觉效果还可以
https://gitee.com/qq_connect-623772954/blazor_-area-drag_-roulette

[bb-auto]

@shakugans Thank you for reporting. We will give triage later.

[ice6]

@shakugans 简单看了下你的代码，作者可能太忙，最近都没咋回复，这是我最近学习整理的资料，建议也看一下，提交组件的话，建议保持代码风格与作者的一致性和生产级要求。

文档由本人认真和AI互动讨论产生，我个人认为没有什么大的问题，限于水平有限，仅供参考。

BootstrapBlazor 组件 JavaScript 与 Blazor 状态同步机制

文档版本: 1.0
适用项目: BootstrapBlazor
适用模式: Blazor Server / Blazor WebAssembly / Blazor Auto

---

目录

1. 核心设计原则
2. Blazor Diff 机制详解
3. JavaScript 模块架构
4. C# 与 JavaScript 双向通信
5. 事件监听器与 Blazor Diff
6. 组件生命周期管理
7. 实战案例分析
8. 最佳实践总结

---

1. 核心设计原则

1.1 单向数据流 + 回调通知

BootstrapBlazor 采用 "单向数据流 + 回调通知" 的设计模式来避免 Server/WASM diff 时的状态错乱问题：

┌────────────────┐     ┌────────────────┐     ┌────────────────┐
│   C# 状态层     │────▶│  Blazor 渲染   │────▶│  DOM 结构      │
│  (唯一真相源)   │     │  (声明式模板)   │     │  (data-* 配置) │
└────────────────┘     └────────────────┘     └────────────────┘
        ▲                                            │
        │                                            ▼
        │                                    ┌────────────────┐
        │◀───────── JSInvokable 回调 ────────│  JavaScript    │
        │                                    │  (行为增强层)   │
        └────── InvokeVoidAsync 调用 ───────▶│  添加动画/交互  │
                                             └────────────────┘

1.2 职责分离

层级	职责	示例
C# 状态层	管理业务状态，是唯一数据源	Value, Items, IsOpen
Blazor 渲染层	声明式 UI 结构，属性绑定	class="@ClassString"
JavaScript 层	UI 增强，动画，浏览器 API	动画、拖拽、键盘导航
浏览器层	CSS 渲染，布局计算	offsetWidth, scrollTop

1.3 核心原则总结

┌─────────────────────────────────────────────────────────────┐
│                    五大核心原则                              │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  1️⃣ Blazor 是状态的唯一真实来源                              │
│     - JavaScript 不存储业务状态                              │
│     - 所有状态变更必须通过 C# 进行                            │
│                                                             │
│  2️⃣ JavaScript 只负责 DOM 增强                              │
│     - 动画效果（添加/移除临时 CSS 类）                        │
│     - 事件处理（键盘、拖拽、滚动）                            │
│     - 第三方库集成                                          │
│                                                             │
│  3️⃣ 通过 data-* 属性传递配置                                │
│     - 避免 JS 直接读取 C# 状态                               │
│     - 配置在模板中声明，JS 读取属性                           │
│                                                             │
│  4️⃣ 用户交互通过 JSInvokable 回调 C#                        │
│     - JS 监听事件后通知 C#                                   │
│     - C# 更新状态后调用 StateHasChanged()                   │
│                                                             │
│  5️⃣ 组件销毁时彻底清理                                      │
│     - dispose() 移除事件监听                                │
│     - Data.remove(id) 清理存储                              │
│                                                             │
└─────────────────────────────────────────────────────────────┘

---

2. Blazor Diff 机制详解

2.1 Blazor Diff 管理的内容

┌─────────────────────────────────────────────────────────────┐
│                    Blazor Diff 管理范围                      │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ✅ Blazor 管理（会 Diff）：                                 │
│  ────────────────────────                                   │
│  1. HTML 结构（元素增删改）                                  │
│  2. HTML 属性（id, class, style, data-*, aria-* 等）        │
│  3. 事件绑定（@onclick, @onchange 等）                      │
│  4. 文本内容                                                │
│  5. 组件参数                                                │
│                                                             │
│  ❌ Blazor 不管（不会 Diff）：                               │
│  ────────────────────────                                   │
│  1. DOM 计算属性（offsetWidth, offsetHeight, scrollTop）    │
│  2. 运行时 CSS 计算值（getComputedStyle）                   │
│  3. JS 添加的事件监听器                                     │
│  4. JS 添加但不在模板中的 class（如动画类）                  │
│  5. 浏览器内部状态（焦点、选区、滚动位置）                   │
│                                                             │
└─────────────────────────────────────────────────────────────┘

2.2 属性类型对比表

属性类型	示例	Blazor 管理?	说明
HTML 属性	id, class, disabled	✅ 是	模板中声明的属性
Style 属性	style="width:100px"	✅ 是	模板中声明的样式
Data 属性	data-bb-scroll="true"	✅ 是	模板中声明的数据属性
文本内容	<span>Hello</span>	✅ 是	元素内的文本
事件绑定	@onclick	✅ 是	Blazor 事件
计算尺寸	offsetWidth, clientHeight	❌ 否	浏览器计算的只读属性
滚动位置	scrollTop, scrollLeft	❌ 否	浏览器运行时状态
焦点状态	document.activeElement	❌ 否	浏览器运行时状态
CSS 计算值	getComputedStyle()	❌ 否	浏览器计算的样式
JS 添加的类	element.classList.add('show')	⚠️ 部分	见下文详解

2.3 JS 添加的 class 处理

情况 1：模板中的 class 没变化 → 保留

@* C# 模板 *@
<div class="drawer collapse">  @* 始终是这个值 *@

// JS 添加 show 类
element.classList.add('show');
// DOM 变成: class="drawer collapse show"

Blazor 下次渲染时：
├── 检查模板: class="drawer collapse"
├── 当前 DOM: class="drawer collapse show"  
├── Diff 结果: 模板值没变，不操作 ✅
└── 结果: "show" 类保留

情况 2：模板中的 class 变化了 → 被覆盖

@* C# 模板 - IsActive 从 false 变 true *@
<div class="@(IsActive ? "drawer active" : "drawer")">

Blazor 渲染时：
├── 新模板值: class="drawer active"
├── 当前 DOM: class="drawer show"
├── Diff 结果: 属性值变了，需要更新
└── 操作: setAttribute("class", "drawer active")
└── 结果: "show" 类被覆盖丢失 ⚠️

2.4 渲染树结构

// C# 模板
<div id="@Id" class="@ClassString" style="@StyleString">
    @foreach (var item in Items)
    {
        <span>@item.Name</span>
    }
</div>

Blazor 生成的渲染树：

┌─────────────────────────────────────────────────────────────┐
│                     Blazor 渲染树                            │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Element: div                                               │
│  ├── Attribute: id = "select_001"                          │
│  ├── Attribute: class = "select dropdown"                  │
│  ├── Attribute: style = "width: 200px"                     │
│  └── Children:                                              │
│      ├── Element: span                                      │
│      │   └── Text: "Item 1"                                │
│      ├── Element: span                                      │
│      │   └── Text: "Item 2"                                │
│      └── Element: span                                      │
│          └── Text: "Item 3"                                │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Diff 时只比较这个树的变化，不关心 DOM 的实际运行时状态。

---

3. JavaScript 模块架构

3.1 核心模块

src/BootstrapBlazor/wwwroot/modules/
├── data.js           # 状态存储（独立 Map）
├── event-handler.js  # 事件管理（支持委托）
├── utility.js        # 工具函数
├── input.js          # 输入框处理（中文输入法）
├── drag.js           # 拖拽功能
└── base-popover.js   # 弹出层基类

3.2 Data 模块 - 独立状态存储

// src/BootstrapBlazor/wwwroot/modules/data.js
const elementMap = new Map()

export default {
    set(element, instance) {
        if (!elementMap.has(element)) {
            elementMap.set(element, instance)
        }
    },

    get(element) {
        if (elementMap.has(element)) {
            return elementMap.get(element)
        }
        return null
    },

    remove(element) {
        if (!elementMap.has(element)) {
            return
        }
        elementMap.delete(element)
    }
}

关键点：JavaScript 状态存储在独立的 Map 中，不直接修改 DOM 属性，避免与 Blazor 的 diff 算法冲突。

3.3 EventHandler 模块 - 事件委托

// 事件委托模式
EventHandler.on(el, 'click', '.dropdown-item', e => {
    // el 是父容器（稳定）
    // '.dropdown-item' 是选择器（子元素可动态变化）
    const item = e.delegateTarget;
    // 处理逻辑...
});

3.4 组件 JS 文件标准结构

// ComponentName.razor.js
import Data from "../../modules/data.js"
import EventHandler from "../../modules/event-handler.js"

// 初始化
export function init(id, invoke, options) {
    const el = document.getElementById(id)
    if (el === null) return

    const component = { el, invoke, options }
    Data.set(id, component)

    // 绑定事件（使用事件委托）
    EventHandler.on(el, 'click', '.child-selector', handler)
}

// 更新（可选）
export function update(id, newState) {
    const component = Data.get(id)
    if (component) {
        // 更新逻辑
    }
}

// 销毁
export function dispose(id) {
    const component = Data.get(id)
    Data.remove(id)

    if (component) {
        EventHandler.off(component.el, 'click')
    }
}

---

4. C# 与 JavaScript 双向通信

4.1 基类封装

// src/BootstrapBlazor/Components/BaseComponents/BootstrapModuleComponentBase.cs
public abstract class BootstrapModuleComponentBase : IdComponentBase, IAsyncDisposable
{
    // JS 模块引用
    protected JSModule? Module { get; set; }
    
    // .NET 对象引用（供 JS 回调）
    protected DotNetObjectReference<BootstrapModuleComponentBase>? Interop { get; set; }
    
    // 首次渲染后加载 JS 模块
    protected override async Task OnAfterRenderAsync(bool firstRender)
    {
        if (firstRender && !string.IsNullOrEmpty(ModulePath))
        {
            Module ??= await JSRuntime.LoadModule(ModulePath);
            
            if (AutoInvokeInit)
            {
                await InvokeInitAsync();
            }
        }
    }
    
    // 调用 JS init 方法
    protected virtual Task InvokeInitAsync() 
        => InvokeVoidAsync("init", Id, Interop);
    
    // 销毁时清理
    protected virtual async ValueTask DisposeAsync(bool disposing)
    {
        if (disposing)
        {
            Interop?.Dispose();
            
            if (Module != null)
            {
                if (AutoInvokeDispose)
                {
                    await Module.InvokeVoidAsync("dispose", Id);
                }
                await Module.DisposeAsync();
            }
        }
    }
}

4.2 C# → JavaScript

// 调用 JS 方法
await InvokeVoidAsync("execute", Id, IsOpen);

// 调用 JS 方法并获取返回值
var result = await InvokeAsync<bool>("checkState", Id);

4.3 JavaScript → C#

// C# 端标记回调方法
[JSInvokable]
public async Task OnStateChangedAsync(CheckboxState state)
{
    State = state;           // 更新 C# 状态
    StateHasChanged();       // 触发重新渲染
}

// JavaScript 端调用
await invoke.invokeMethodAsync('OnStateChangedAsync', newState);

4.4 初始化时传递回调方法名

// C# 端
protected override Task InvokeInitAsync() => InvokeVoidAsync("init", Id, Interop, new
{
    ConfirmMethodCallback = nameof(ConfirmSelectedItem),
    SearchMethodCallback = nameof(TriggerOnSearch),
    TriggerCollapsed = nameof(TriggerCollapsed)
});

[JSInvokable]
public async Task ConfirmSelectedItem(int index)
{
    // 处理确认选中
}

[JSInvokable]
public async Task TriggerOnSearch(string searchText)
{
    SearchText = searchText;
    StateHasChanged();
}

// JavaScript 端
export function init(id, invoke, options) {
    const { confirmMethodCallback, searchMethodCallback } = options;
    
    EventHandler.on(el, 'keydown', e => {
        if (e.key === 'Enter') {
            invoke.invokeMethodAsync(confirmMethodCallback, index);
        }
    });
}

---

5. 事件监听器与 Blazor Diff

5.1 核心结论

┌─────────────────────────────────────────────────────────────┐
│                    关键结论                                  │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ✅ 元素不变（只改属性）→ JS 事件监听器保留                  │
│  ❌ 元素被替换/删除重建 → JS 事件监听器丢失                  │
│                                                             │
└─────────────────────────────────────────────────────────────┘

5.2 三种情况分析

情况 1：只修改属性 → 监听器保留 ✅

@* 初始渲染 *@
<div id="box" class="normal">Content</div>

@* 状态变化后 *@
<div id="box" class="active">Content</div>

元素 <div> 保持不变，只更新 class 属性，JS 绑定的事件监听器保留。

情况 2：元素被删除重建 → 监听器丢失 ❌

@if (ShowBox)
{
    <div id="box">Content</div>
}

ShowBox 从 true → false → true 时，元素被删除后重建，需要重新绑定事件。

情况 3：列表重排 → 取决于 @key

@* 使用 @key 时，Blazor 识别为"移动元素"，可能删除重建 *@
@foreach (var item in Items)
{
    <div @key="item.Id">@item.Name</div>
}

5.3 解决方案：事件委托

// ✅ 推荐：绑定到稳定的父容器
EventHandler.on(container, 'click', '.item', handler);

// ❌ 避免：直接绑定到可能变化的子元素
item.addEventListener('click', handler);

┌─────────────────────────────────────────────────────────────┐
│  事件委托原理                                                │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  <div id="container">        ← 事件绑定在这里（稳定）       │
│    <div class="item">A</div>  ← 可以动态增删                │
│    <div class="item">B</div>                                │
│    <div class="item">C</div>                                │
│  </div>                                                     │
│                                                             │
│  EventHandler.on(container, 'click', '.item', handler)     │
│                                                             │
│  子元素被 Blazor 增删重建时，事件仍然有效！                  │
│                                                             │
└─────────────────────────────────────────────────────────────┘

5.4 保持容器稳定的模板设计

@* 外层容器始终存在，ID 稳定 *@
<div id="@Id" class="select">
    @* 内部内容可以动态变化 *@
    <div class="dropdown-menu">
        @foreach (var item in FilteredItems)
        {
            <div class="dropdown-item">@item.Text</div>
        }
    </div>
</div>

---

6. 组件生命周期管理

6.1 完整生命周期流程

┌─────────────────────────────────────────────────────────────┐
│                    组件生命周期                              │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  1. OnInitialized()                                         │
│     └── 加载 JS 模块路径配置                                 │
│                                                             │
│  2. OnParametersSet()                                       │
│     └── 处理参数变化                                        │
│                                                             │
│  3. BuildRenderTree() / Render                              │
│     └── 生成渲染树                                          │
│                                                             │
│  4. OnAfterRenderAsync(firstRender: true)                   │
│     ├── 加载 JS 模块                                        │
│     └── 调用 JS init()                                      │
│                                                             │
│  5. 用户交互 / 状态变化                                      │
│     ├── JS 通过 JSInvokable 回调 C#                         │
│     ├── C# 更新状态                                         │
│     └── StateHasChanged() 触发重新渲染                      │
│                                                             │
│  6. OnAfterRenderAsync(firstRender: false)                  │
│     └── 可选：调用 JS update()                              │
│                                                             │
│  7. DisposeAsync()                                          │
│     ├── 调用 JS dispose()                                   │
│     ├── 清理 DotNetObjectReference                          │
│     └── 释放 JS 模块                                        │
│                                                             │
└─────────────────────────────────────────────────────────────┘

6.2 时序图

┌─────────┐     ┌─────────┐     ┌─────────┐     ┌─────────┐
│  Blazor │     │   C#    │     │   JS    │     │   DOM   │
└────┬────┘     └────┬────┘     └────┬────┘     └────┬────┘
     │               │               │               │
     │ 首次渲染      │               │               │
     │──────────────▶│               │               │
     │               │ 生成 HTML     │               │
     │               │──────────────────────────────▶│
     │               │               │               │
     │ OnAfterRender │               │               │
     │──────────────▶│               │               │
     │               │ init()        │               │
     │               │──────────────▶│               │
     │               │               │ Data.set()    │
     │               │               │──────────────▶│
     │               │               │ EventHandler  │
     │               │               │──────────────▶│
     │               │               │               │
     │ 用户交互      │               │               │
     │               │               │◀──────────────│
     │               │               │ 事件触发      │
     │               │◀──────────────│               │
     │               │ JSInvokable   │               │
     │               │ 更新状态      │               │
     │◀──────────────│               │               │
     │ StateHasChanged               │               │
     │               │               │               │
     │ Diff & Patch  │               │               │
     │──────────────────────────────────────────────▶│
     │               │               │               │
     │ 组件销毁      │               │               │
     │──────────────▶│               │               │
     │               │ dispose()     │               │
     │               │──────────────▶│               │
     │               │               │ Data.remove() │
     │               │               │ EventOff      │
     │               │               │──────────────▶│
     │               │               │               │

---

7. 实战案例分析

7.1 案例：Drawer 抽屉组件

文件结构

Components/Drawer/
├── Drawer.razor          # 模板
├── Drawer.razor.cs       # C# 逻辑
└── Drawer.razor.js       # JavaScript 交互

C# 状态定义

// 核心状态：抽屉是否打开
[Parameter]
public bool IsOpen { get; set; }

// 双向绑定回调
[Parameter]
public EventCallback<bool> IsOpenChanged { get; set; }

Razor 模板

@attribute [BootstrapModuleAutoLoader(JSObjectReference = true)]

<div id="@Id" class="@ClassString" 
     data-bb-keyboard="@KeyboardString"
     data-bb-scroll="@BodyScrollString">
    @if (ShowBackdrop)
    {
        <div class="drawer-backdrop"></div>
    }
    <div class="@DrawerClassString">
        @ChildContent
    </div>
</div>

JavaScript 模块

export function init(id, invoke, method) {
    const el = document.getElementById(id);
    if (el === null) return;

    const dw = { el, body: document.querySelector('body') }
    Data.set(id, dw)

    // 监听 ESC 键
    EventHandler.on(el, 'keyup', async e => {
        if (e.key === 'Escape') {
            const supportESC = el.getAttribute('data-bb-keyboard') === 'true';
            if (supportESC) {
                // 通知 C# 关闭
                await invoke.invokeMethodAsync(method);
            }
        }
    });
}

export function execute(id, open) {
    const dw = Data.get(id)
    const { el } = dw
    const drawerBody = el.querySelector('.drawer-body')

    if (open) {
        el.classList.add('show')
        drawerBody.classList.add('show');  // JS 添加动画类
    } else {
        drawerBody.classList.remove('show');
        // 动画完成后移除
        requestAnimationFrame(() => {
            el.classList.remove('show');
        });
    }
}

export function dispose(id) {
    const dw = Data.get(id)
    Data.remove(id);
    EventHandler.off(dw.el, 'keyup');
}

状态同步流程

用户按 ESC
    ↓
JS 监听到 keyup 事件
    ↓
JS 调用 invoke.invokeMethodAsync('Close')
    ↓
C# Close() 方法执行
    ├── IsOpen = false
    ├── 调用 execute(id, false) 执行动画
    └── StateHasChanged() 触发重新渲染
    ↓
Blazor Diff（结构不变，JS 的 show 类不受影响）

7.2 案例：Select 下拉选择组件

键盘导航的临时状态

// 键盘 ↑↓ 导航时，JS 添加临时 active 类
const keydown = e => {
    if (e.key === 'ArrowDown') {
        // 移除旧的 active
        current.classList.remove('active');
        // 添加新的 active（临时视觉效果）
        nextItem.classList.add('active');
        scrollIntoView(nextItem);
    }
    
    if (e.key === 'Enter') {
        // 确认选中，通知 C#
        invoke.invokeMethodAsync('ConfirmSelectedItem', index);
    }
}

// C# 计算 active 类（最终状态）
private string? ActiveItem(SelectedItem item) => CssBuilder.Default("dropdown-item")
    .AddClass("active", item.Value == CurrentValueAsString)  // C# 决定
    .Build();

[JSInvokable]
public async Task ConfirmSelectedItem(int index)
{
    SelectedItem = Rows[index];
    CurrentValueAsString = SelectedItem.Value;
    StateHasChanged();  // 重新渲染，C# 的 active 覆盖 JS 的临时状态
}

搜索防抖

const onSearch = debounce(async v => {
    await invoke.invokeMethodAsync('TriggerOnSearch', v);
}, 200);

Input.composition(search, onSearch);  // 支持中文输入法

[JSInvokable]
public async Task TriggerOnSearch(string searchText)
{
    SearchText = searchText;
    StateHasChanged();  // 重新渲染过滤后的列表
}

---

8. 最佳实践总结

8.1 状态管理

┌─────────────────────────────────────────────────────────────┐
│                    状态管理最佳实践                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ✅ DO                                                      │
│  ────                                                       │
│  • 业务状态放在 C# 中（Value, Items, IsOpen）               │
│  • 通过 [Parameter] 暴露状态                                │
│  • 状态变更后调用 StateHasChanged()                         │
│  • 使用 EventCallback 实现双向绑定                          │
│                                                             │
│  ❌ DON'T                                                   │
│  ──────                                                     │
│  • 在 JS 中存储业务状态                                     │
│  • JS 直接修改影响 Blazor Diff 的 DOM 属性                  │
│  • 跳过 C# 直接在 JS 中更新 UI 状态                         │
│                                                             │
└─────────────────────────────────────────────────────────────┘

8.2 事件处理

┌─────────────────────────────────────────────────────────────┐
│                    事件处理最佳实践                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  1️⃣ 使用事件委托                                            │
│     EventHandler.on(父容器, 事件, 子选择器, 处理函数)        │
│                                                             │
│  2️⃣ 保持容器元素稳定                                        │
│     - 外层 div 使用固定 id="@Id"                            │
│     - 不要用 @if 包裹整个组件                               │
│                                                             │
│  3️⃣ 动态内容放在稳定容器内部                                │
│     - @foreach 循环的内容可以随意变化                       │
│     - 事件委托会自动处理                                    │
│                                                             │
│  4️⃣ 必要时提供 update 方法                                  │
│     export function update(id) {                            │
│         // 重新获取可能变化的 DOM 引用                      │
│     }                                                       │
│                                                             │
│  5️⃣ dispose 时清理所有事件                                  │
│     export function dispose(id) {                           │
│         EventHandler.off(el, 'click');                      │
│         Data.remove(id);                                    │
│     }                                                       │
│                                                             │
└─────────────────────────────────────────────────────────────┘

8.3 CSS 类管理

┌─────────────────────────────────────────────────────────────┐
│                    CSS 类管理最佳实践                        │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  策略 1：JS 添加的类不与 C# 冲突                            │
│  ─────────────────────────────                              │
│  C# 模板: class="drawer-body left"   (结构类)               │
│  JS 添加: classList.add('show')      (动画类)               │
│  → 两者不冲突，show 会保留                                  │
│                                                             │
│  策略 2：使用 CSS 变量                                       │
│  ────────────────────                                       │
│  JS: style.setProperty('--bb-width', `${width}px`)          │
│  C#: style="--bb-width: @InitialWidth"                      │
│  → Blazor 只 Diff 属性字符串，不关心 CSS 变量运行时值       │
│                                                             │
│  策略 3：状态完全由 C# 控制                                  │
│  ─────────────────────────                                  │
│  C#: class="@(IsActive ? "active" : "")"                    │
│  JS: 只做临时视觉效果，确认后 C# 重新渲染覆盖                │
│                                                             │
└─────────────────────────────────────────────────────────────┘

8.4 配置传递

┌─────────────────────────────────────────────────────────────┐
│                    配置传递最佳实践                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  方式 1：data-* 属性（推荐）                                │
│  ──────────────────────────                                 │
│  <div data-bb-keyboard="@IsKeyboard"                        │
│       data-bb-scroll="@BodyScroll">                         │
│                                                             │
│  JS: el.getAttribute('data-bb-keyboard') === 'true'         │
│                                                             │
│  方式 2：init 参数                                          │
│  ─────────────────                                          │
│  await InvokeVoidAsync("init", Id, Interop, new {           │
│      Callback = nameof(OnCallback),                         │
│      Option = "value"                                       │
│  });                                                        │
│                                                             │
│  JS: const { callback, option } = options;                  │
│                                                             │
└─────────────────────────────────────────────────────────────┘

8.5 错误处理

// JSModule 中的错误处理
public virtual async ValueTask InvokeVoidAsync(string identifier, ...)
{
    try
    {
        await jSObjectReference.InvokeVoidAsync(identifier, ...);
    }
    catch (JSException)
    {
#if DEBUG
        throw;  // 开发时抛出
#endif
    }
    catch (JSDisconnectedException) { }  // 连接断开，忽略
    catch (OperationCanceledException) { }  // 操作取消，忽略
    catch (ObjectDisposedException) { }  // 对象已销毁，忽略
}

---

附录

A. 常用工具函数

// 防抖
const debounce = (fn, duration = 200) => {
    let handler = null;
    return function() {
        if (handler) clearTimeout(handler);
        handler = setTimeout(() => fn.apply(this, arguments), duration);
    }
}

// 滚动到可见区域
const scrollIntoView = (el, item) => {
    const behavior = el.getAttribute('data-bb-scroll-behavior') ?? 'smooth';
    item.scrollIntoView({ behavior, block: "nearest" });
}

// 获取元素索引
const indexOf = (container, element) => {
    const items = container.querySelectorAll('.dropdown-item');
    return Array.prototype.indexOf.call(items, element);
}

B. 组件属性命名约定

前缀	用途	示例
data-bb-	BootstrapBlazor 配置	data-bb-keyboard
data-bs-	Bootstrap 配置	data-bs-toggle
aria-	无障碍访问	aria-label

C. 相关文件位置

src/BootstrapBlazor/
├── Components/
│   └── BaseComponents/
│       └── BootstrapModuleComponentBase.cs  # 基类
├── Utils/
│   └── JSModule.cs                          # JS 模块封装
└── wwwroot/modules/
    ├── data.js                              # 状态存储
    ├── event-handler.js                     # 事件管理
    └── utility.js                           # 工具函数

---

文档维护: 如有更新，请同步修改此文档。

[ArgoZhang]

@ice6 这总结的真好啊，花了不少时间吧，也都非常准确与正确
@shakugans 我 fork 一下你的工程先学习一下，你看看是你自己提交 PR 给我还是自己集成过来，都可以的，太感谢了

[ArgoZhang]

@shakugans 工程打开都是乱码，能否重新整理一下文档编码格式 uft-8

[ice6]

@ice6 这总结的真好啊，花了不少时间吧，也都非常准确与正确 @shakugans 我 fork 一下你的工程先学习一下，你看看是你自己提交 PR 给我还是自己集成过来，都可以的，太感谢了

是呢，重仓blazor server，架构设计良好的情况下，开发企业系统太便利了。回头看以前用前后端分离(vue/react)方案做的企业内部系统（几十人到几百人这种），纯属浪费开发资源。前后端分离方案在用户体验层把"用户惯坏"了，所以必须把js互操作的原理搞清楚，提供良好用户体验的同时，提供良好的开发体验。所以花了些时间整理了下，向你致敬！

[shakugans]

工程打开都是乱码，能否重新整理一下文档编码格式uft-8

重新编辑了

这总结的真好啊，花了不少时间吧，也都非常准确与正确 我 fork 一下你的工程先学习一下，你看看是你自己提交 PR 给我还是自己集成过来，都可以的，太感谢了

我没什么经验。能大佬搞就最好了