Known · 元数据驱动的 .NET 全栈框架

说明

基于浏览器 Web MIDI 规范封装的音乐设备通信组件：点击“连接 MIDI 设备”后经 navigator.requestMIDIAccess 取得 MIDI 访问权限（可用 EnableSysEx 申请系统独占消息），组件枚举 MIDIAccess 的输入与输出端口（兼容现代 Map 与旧式类数组两种 MIDIPortList 形态）并给每个输入端口挂 onmidimessage；设备上报的字节流按 MIDI 1.0 状态字节实时解析为音符开 / 关（含音名如 C4）、控制改变、节目改变、通道 / 复音触后、弯音轮与系统消息（SysEx、时钟、走停等），面板展示最近消息的可读摘要与十六进制，并把每条收发记入带方向的日志。发送区可在“发往”里切换输出端口（点击输出端口芯片亦可），按通道 / 音符 / 力度下发音符开 / 关，下发控制改变 / 节目改变 / 弯音轮，或直接输入十六进制原始字节（忽略空格 / 逗号 / 连字符 / 0x 前缀，首字节即状态字节）；“清空输出”调用各输出端口的 clear() 撤回落队消息。对外经 OnConnected / OnDisconnected / OnData / OnError 事件驱动，或用 RequestAsync / RescanAsync / SendNoteOnAsync / SendNoteOffAsync / SendControlChangeAsync / SendProgramChangeAsync / SendPitchBendAsync / SendRawAsync / ClearOutputsAsync / CloseAsync 等公开方法编程式操作；端口以 MidiPorts（含 MidiPort 的 Id / Name / Manufacturer / State）呈现，一次收发以 MidiMessage 携带方向、端口、原始字节、状态字节、通道、Type / NoteName 派生名与 Hex 表示。设备热插拔经 onstatechange 自动刷新端口列表；组件“关闭监听”只摘除本组件的 onmidimessage / onstatechange、保留已获授权，重连不再弹权限。平台限制：Web MIDI 主要经 Chrome / Edge / Opera 提供（Firefox / Safari 默认不支持），须处于安全上下文（HTTPS 或 localhost）、由用户手势首次触发 requestMIDIAccess（浏览器可能弹出授权、授予后记住）；与蓝牙 / 串口不同，桌面浏览器通常可直接联调真实 MIDI 控制器或系统虚拟端口，但 Windows 无内置 MIDI 栈，常需实体 / USB-MIDI 设备或 loopMIDI 等虚拟端口再对接。MIDI 消息为即时无确认的字节流、遵循状态字节协议且消息边界由状态字节（运行状态 / 系统消息）界定；在 Blazor Server 中往返延迟通常使瞬时授权过期，因此推荐在 Blazor WASM 或桌面宿主里使用。

常见能力：

requestMIDIAccess 取得访问并枚举输入 / 输出端口（兼容 Map 与旧式类数组两种端口列表）
onmidimessage 实时解析音符 / 控制 / 节目 / 触后 / 弯音 / 系统消息，给出音名与可读摘要
按通道 / 音符 / 力度下发音符开关，或控制改变 / 节目改变 / 弯音轮
可切换发往的输出端口（下拉或点击端口芯片），并支持十六进制原始字节下发
清空输出（各端口 clear）撤回落队消息；热插拔经 onstatechange 自动刷新端口
关闭监听只摘除监听、保留授权，重连不再弹权限；EnableSysEx 申请系统独占消息
OnConnected / OnDisconnected / OnData / OnError 事件 + 公开方法双驱动
能力检测与安全上下文提示；不支持时给出明确原因

用法

<Midi Name="MIDI 通信" OnConnected="OnConnected" OnData="OnData" OnError="OnError" />

@code {
    // 授权后枚举端口；收到的 MIDI 消息按状态字节解析。
    void OnConnected(MidiPorts p) =>
        Console.WriteLine($"{p.Inputs.Count} 输入 · {p.Outputs.Count} 输出");
    void OnData(MidiMessage m) =>
        Console.WriteLine($"{(m.IsIn ? "IN" : "OUT")} {m.Type} {m.NoteName} {m.Hex}");
    void OnError(string e) => Console.WriteLine("错误：" + e);
}

@* 也可拿到实例编程式下发音符 / 控制 / 节目，或原始字节 *@
<Midi @ref="_midi" />
<Button Text="弹中央 C" OnClick="@(() => _midi.SendNoteOnAsync(0, 60, 100))" />
<Button Text="CC1=64" OnClick="@(() => _midi.SendControlChangeAsync(0, 1, 64))" />
<Button Text="发原始" OnClick="@(() => _midi.SendRawAsync(new byte[] { 0xF0, 0x7E, 0x7F, 0x06, 0x01, 0xF7 }))" />

API 参数

参数	类型	默认值	说明
`ConnectText`	`string`	`"连接 MIDI 设备"`	连接按钮文案（内部已本地化，作为翻译键）。
`EnableSysEx`	`bool`	`false`	是否申请 Sys Ex exclusive 消息权限（requestMIDIAccess()）。
`MaxLog`	`int`	`200`	日志最多保留行数，超出丢弃最旧。
`Name`	`string`	`"MIDI 设备"`	面板标题。
`OnConnected`	`EventCallback<MidiPorts>`	—	事件连接成功（含输入 / 输出端口枚举）。
`OnData`	`EventCallback<MidiMessage>`	—	事件发生一次 MIDI 消息收发（输入上报 / 输出写出）。
`OnDisconnected`	`EventCallback`	—	事件已关闭监听（本组件停止接收上报）。
`OnError`	`EventCallback<string>`	—	事件发生错误，参数为错误说明。
`ShowLog`	`bool`	`true`	是否显示收发日志。
`Visible`	`bool`	`true`	取得或设置组件是否可见，默认为false。
`VisibleChanged`	`EventCallback<bool>`	—	事件取得或设置组件可见性变化时的回调事件。
`Class`	`string`	`null`	取得或设置组件的CSS类名，用于自定义样式。
`Disabled`	`bool`	`false`	取得或设置组件是否禁用，默认为false。
`Style`	`string`	`null`	取得或设置组件的内联样式，用于自定义样式。

所有组件均继承 BaseComponent，除上表参数外还支持 Class、Style、Disabled、Visible。