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

说明

以 iframe 承载外部页面的通用内嵌组件，适合地图、BI 面板、视频播放器、合作伙伴小应用等场景。顶部工具条提供重新加载 / 新窗口打开 / 复制链接 / 整卡全屏；状态徽章按加载中 / 已加载 / 加载失败三色即时呈现，Src 变更时用 @key 重建 iframe，Esc 退出全屏后图标自动同步。默认走“通用”安全策略——sandbox 允许脚本 / 同域 / 表单 / 弹窗 / 下载 / 模态，allow 允许全屏 / 自动播放 / 加密媒体 / 摄像头 / 麦克风 / 剪贴板写 / 画中画，可覆盖 Sandbox / Allow 传更严格值或 null 完全省略该属性；Height 与 Aspect 二选一决定预览区尺寸。父 ↔ 子通信：JS 侧注册 window.message，命中 AllowedOrigins 白名单才回推 OnMessage（携带 Origin 与 JSON 化 Data）；业务侧可用 PostToFrameAsync 向 iframe 发送结构化消息，与本地小应用双向协作。由于浏览器同源策略限制，跨域 iframe 的 error 事件不可靠，故失败以 Timeout 兜底。

常见能力：

通用工具条：重新加载 / 新窗口打开 / 复制链接 / 整卡全屏
默认「通用」sandbox + allow 覆盖常见第三方；可切严格或省略
Src 变更自动重建 iframe；Height 与 Aspect 二选一决定预览尺寸
postMessage 桥：AllowedOrigins 白名单 + OnMessage 事件回推 Origin / Data
PostToFrameAsync 主动发消息到子页，实现父 ↔ 子双向协作
全屏目标为整卡容器，工具条与状态提示在全屏下仍可见，Esc 自动同步图标
Timeout 兜底加载失败（跨域 error 事件不可靠），OnLoad / OnError 事件
复制按钮走 navigator.clipboard，http / 无权限时回落 execCommand('copy')

用法

<Embed Src="@externalUrl" Title="合作伙伴看板" Aspect="16 / 9"
      AllowedOrigins="@origins"
      OnLoad="OnReady" OnError="OnFail" OnMessage="OnRecv" />

@code {
    string[] origins = ["https://partner.example.com"];
    Embed _embed; // @ref="_embed"

    void OnRecv(EmbedMessage m) => Console.WriteLine($"{m.Origin}: {m.Data}");

    async Task Push() => await _embed.PostToFrameAsync(new { cmd = "refresh" }, "https://partner.example.com");
}

API 参数

参数	类型	默认值	说明
`Allow`	`string`	`"fullscreen; autoplay; encrypted-media; camera; microphone; clipboard-write; picture-in-picture"`	iframe allow 权限策略；默认允许全屏 / 自动播放 / 加密媒体 / 摄像头 / 麦克风 / 剪贴板写 / 画中画。
`AllowedOrigins`	`IEnumerable<string>`	`null`	postMessage 消息来源白名单；为空 / null 表示不做来源过滤（仍推荐显式列出以防伪造消息）。
`Aspect`	`string`	`null`	CSS aspect-ratio（如 16 / 9）；非空则画面按此比例自适应。
`EnableCopy`	`bool`	`true`	是否显示“复制链接”按钮。
`EnableFullscreen`	`bool`	`true`	是否显示“全屏”按钮（整卡容器进入原生全屏，Esc 退出图标自动同步）。
`EnableOpen`	`bool`	`true`	是否显示“新窗口打开”按钮。
`EnableRefresh`	`bool`	`true`	是否显示“重新加载”按钮。
`Height`	`string`	`"480px"`	预览区高度（CSS 长度，默认 480px）；设置 Aspect 时忽略本项。全屏时自动撑满视口。
`Loading`	`string`	`"eager"`	iframe loading 属性：eager / lazy（默认 eager）。
`OnError`	`EventCallback<string>`	—	事件加载失败（当前仅超时或桥接异常）事件，参数为错误码。
`OnLoad`	`EventCallback`	—	事件 iframe 加载完成事件。
`OnMessage`	`EventCallback<EmbedMessage>`	—	事件收到子 iframe postMessage 事件；已按 AllowedOrigins 白名单过滤。
`ReferrerPolicy`	`string`	`null`	iframe referrerpolicy；为空表示使用浏览器默认。
`Sandbox`	`string`	`"allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox allow-downloads allow-modals"`	iframe sandbox 策略；默认“通用”，传 null 可完全省略该属性（最宽松）。
`ShowToolbar`	`bool`	`true`	是否显示顶部工具条。
`ShowUrl`	`bool`	`true`	是否在工具条上以芯片形式显示当前地址（悬停看全 URL）。
`Src`	`string`	`null`	内嵌地址（同源或允许被框架化的跨域 URL）。
`Timeout`	`int`	`0`	加载超时毫秒（0 表示不做超时判定）；跨域 iframe 无法可靠捕获 error，超时是唯一兜底信号。
`Title`	`string`	`null`	工具条标题；为空时显示“内嵌页面”占位。同时作为 iframe 的 title 属性供可访问性使用。
`Visible`	`bool`	`true`	取得或设置组件是否可见，默认为false。
`VisibleChanged`	`EventCallback<bool>`	—	事件取得或设置组件可见性变化时的回调事件。
`Class`	`string`	`null`	取得或设置组件的CSS类名，用于自定义样式。
`Disabled`	`bool`	`false`	取得或设置组件是否禁用，默认为false。
`Style`	`string`	`null`	取得或设置组件的内联样式，用于自定义样式。

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