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

说明

基于浏览器 Web NFC 规范封装的标签读写组件：点击“开始扫描”后经 NDEFReader.scan 持续监听（默认 disableTimeout，用 AbortController 停止），把 NFC / 触碰标签靠近设备即触发 onreading，面板展示标签序列号与其 NDEF 记录，逐条给出记录类型（text / url / mime 等）、媒体类型、id、文本内容与十六进制原始字节；无法解析时经 onreadingerror 报错。写入区支持文本 / URL / MIME 三种记录：文本走 text 记录、链接走 url 记录、MIME 需填媒体类型并把内容按 UTF-8 编码为原始字节，写入与 makeReadOnly（把标签一次性锁定为只读）都须在设备贴合可写标签时由用户手势触发，且对标签是破坏性的一次性操作。对外经 OnRead / OnWrite / OnError 事件驱动，或用 ScanAsync / StopScanAsync / WriteTextAsync / WriteUrlAsync / WriteMimeAsync / MakeReadOnlyAsync 等公开方法编程式操作；读取以 NfcTag（序列号 + NfcRecord 列表，记录含 Text / Data 与 Hex / DataText 派生表示）呈现。平台限制：Web NFC 目前仅 Android Chrome / ChromeOS 提供后端，桌面 Chrome / Edge 通常检测不到 NDEFReader（面板据能力检测显示“不支持”）；且必须处于安全上下文（HTTPS 或 localhost）、由用户手势发起扫描或写入，在 Blazor Server 中往返延迟通常使瞬时授权过期，因此推荐在 Blazor WASM 或桌面宿主里使用，真机联调需要一张 NDEF 格式的可读写标签与一台支持 NFC 的 Android 设备。

常见能力：

开始扫描：NDEFReader.scan 持续监听（disableTimeout + AbortController 停止）
读取标签序列号与全部 NDEF 记录，逐条给出类型 / 媒体类型 / id / 文本 / 十六进制
写入支持文本 / URL / MIME 三种记录，MIME 内容按 UTF-8 编码为字节
可将标签锁定为一次性只读（makeReadOnly）
读取失败（onreadingerror）与写入 / 锁定失败均有明确提示
OnRead / OnWrite / OnError 事件 + 公开方法双驱动
能力检测与安全上下文提示；桌面浏览器通常不支持时给出明确原因

用法

<Nfc Name="NFC 标签" OnRead="OnRead" OnWrite="OnWrite" OnError="OnError" />

@code {
    void OnRead(NfcTag t) =>
        Console.WriteLine($"{t.Display} 共 {t.Count} 条记录：{t.Records.FirstOrDefault()?.Summary}");
    void OnWrite(NfcTag t) => Console.WriteLine("写入完成");
    void OnError(string m) => Console.WriteLine("错误：" + m);
}

@* 也可拿到实例编程式写入 / 只读锁定 *@
<Nfc @ref="_nfc" />
<Button Text="写网址" OnClick="@(() => _nfc.WriteUrlAsync("https://known.org.cn"))" />
<Button Text="锁定只读" OnClick="@(() => _nfc.MakeReadOnlyAsync())" />

API 参数

参数	类型	默认值	说明
`AutoScan`	`bool`	`false`	是否在首次渲染后自动开始扫描（仍须在安全上下文且浏览器支持；用户手势限制依宿主而定）。
`DisableTimeout`	`bool`	`true`	是否持续扫描而不自动超时（对应 disableTimeout）。
`MaxLog`	`int`	`200`	日志最多保留行数，超出丢弃最旧。
`Name`	`string`	`"NFC 标签"`	面板标题。
`OnError`	`EventCallback<string>`	—	事件发生错误，参数为错误说明。
`OnRead`	`EventCallback<NfcTag>`	—	事件成功读取到一张标签（序列号 + NDEF 记录）。
`OnWrite`	`EventCallback<NfcTag>`	—	事件成功写入标签后回显的记录。
`ScanText`	`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。