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

说明

Src 给模型地址即可，类型留 Kind="auto" 按地址后缀判定；模型按包围盒自动取景——先挪到原点再按最长边缩放到 2 个单位，所以无论建模时用的是毫米还是米都能正常呈现，无需宿主预调尺度。three.js r147 与 OrbitControls / GLTFLoader / OBJLoader 四个脚本以 RCL 静态资源内置，与 echarts、hls 同一套路：首次真正渲染才注入 <script>，不看 3D 的宿主零加载成本；之所以停在 r147，是因为再往上的版本删掉了全局脚本分发，而本框架的前端层是没有打包器的经典脚本。未给 Src 时用 Primitive 内置几何体（knot / box / sphere / cylinder / cone / torus）兜底，宿主一份模型资产也没有就能跑通全流程。裸 OBJ 常见于 CAD 导出：不带 vn 法线也不跟 mtl 材质，组件会补计算法线并给默认材质、双面渲染，否则这类模型在浏览器里是全黑一片。底部工具条可切换自动旋转、地面网格、坐标轴、线框，并复位视角、导出当前视角 PNG、让终端用户直接选本机模型文件（走 objectURL，不经过服务器）；订阅 OnSnapshot 时快照交回宿主，未订阅则直接落地下载。三条边界：渲染依赖 WebGL，无显卡驱动或被策略禁用时降级为提示；glTF 的 Draco / KTX2 压缩资源需要额外解码器，未内置，这类模型会报解析失败；浏览器安全限制下 .obj 的 mtllib 材质文件不会自动跟随，只有几何体可见。

常见能力：

glTF / GLB / OBJ 三格式
包围盒自动取景
three.js 惰性内置
轨道旋转 / 缩放 / 平移
自动旋转与线框切换
地面网格与坐标轴
复位视角
快照导出 PNG
终端用户本机选模型
内置几何体兜底

用法

<ModelViewer Src="_content/Known.Demo/models/house.obj" Height="320px" />

@* 没有模型资产：用内置几何体兜底 *@
<ModelViewer Primitive="knot" AutoRotate="true" ShowAxes="true" OnLoaded="@Loaded" />

@* 快照交回宿主，宿主决定是存对象存储还是直接下载 *@
<ModelViewer Src="@url" OnSnapshot="@async data => await oss.PutPngAsync(data)" />

API 参数

参数	类型	默认值	说明
`Accept`	`string`	`".glb,.gltf,.obj"`	「打开本地模型文件」的文件选择框 accept，默认三种常见模型格式。
`AutoRotate`	`bool`	`true`	初始是否自动旋转。
`EnablePan`	`bool`	`true`	是否允许右键拖拽平移视角。
`EnableSnapshot`	`bool`	`true`	是否显示快照按钮。宿主未订阅 OnSnapshot 时，快照直接以 PNG 落地下载。
`Height`	`string`	`"320px"`	画布高度，如 320px；宽度跟随容器。
`Id`	`string`	`null`	画布 DOM id，留空自动生成。同页多个查看器时可用于 JS 侧定向取用。
`Kind`	`string`	`"auto"`	模型类型：auto（默认，按地址后缀判定）/ glb / gltf / obj。
`OnError`	`EventCallback<string>`	—	事件出错回调（WebGL 不可用、脚本加载失败、模型解析失败等），参数为可直接展示的中文原因。
`OnLoaded`	`EventCallback<ModelLoadInfo>`	—	事件模型进入场景后回调，附带模型名与三角面数（内置几何体同样会触发）。
`OnSnapshot`	`EventCallback<string>`	—	事件快照回调，参数为 PNG 的 dataURL。
`Primitive`	`string`	`"knot"`	未提供 Src 时使用的内置几何体：knot（默认）/ box / sphere / cylinder / cone / torus。
`RotateSpeed`	`double`	`1.6`	自动旋转速度（越大越快，默认 1.6）。
`ShowAxes`	`bool`	`false`	是否显示 XYZ 坐标轴。
`ShowGrid`	`bool`	`true`	是否显示地面网格。
`ShowOpen`	`bool`	`true`	是否显示「打开本地模型文件」按钮（由终端用户选本机 .glb/.gltf/.obj，不经服务器）。
`ShowToolbar`	`bool`	`true`	是否显示底部工具条（旋转 / 网格 / 坐标轴 / 线框 / 复位 / 快照 / 打开）。
`Src`	`string`	`null`	模型地址（.glb / .gltf / .obj），支持站内相对地址与跨域绝对地址；留空则渲染 Primitive 内置几何体。
`Visible`	`bool`	`true`	取得或设置组件是否可见，默认为false。
`VisibleChanged`	`EventCallback<bool>`	—	事件取得或设置组件可见性变化时的回调事件。
`Wireframe`	`bool`	`false`	是否以线框方式显示模型。
`Class`	`string`	`null`	取得或设置组件的CSS类名，用于自定义样式。
`Disabled`	`bool`	`false`	取得或设置组件是否禁用，默认为false。
`Style`	`string`	`null`	取得或设置组件的内联样式，用于自定义样式。

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