HTML 交互组件是玄武屏第二大类"活的内容"——任意 HTML / JS 实现的交互动画都能嵌入演示。
与 GGB 元素的区别
| 维度 | GGB 元素 | HTML 元素 |
|---|---|---|
| 内核 | GeoGebra Applet | 任意 HTML / JS / Canvas / WebGL |
| 适合 | 几何 / 代数 / 数学动画 | 物理仿真 / 数据可视化 / 自定义工具 |
| 学习曲线 | GGB 学习成本 | 前端开发能力 |
| 沙盒安全 | 同上 | 严格沙盒,禁外发请求 |
典型应用
| 场景 | 例子 |
|---|---|
| 物理仿真 | 弹簧振动、电磁感应、流体模拟 |
| 数据可视化 | D3.js 自定义图表、Three.js 3D 场景 |
| 小工具 | 抽奖器、计时器、互动地图、随机点名 |
| 行业仿真 | 医学:人体 3D;建筑:户型漫游;军事:装备模型 |
| 数字孪生 | 实时数据驱动的 3D 场景 |
嵌入流程
{
"type": "html",
"workId": "BHtml24050001",
"interactable": true
}跟 GGB 一样,前端拿到的是 workId,OSS 真实 URL 由服务端鉴权代理,不会泄露。
创作者上传 HTML 组件
到「玄武屏空间 → 我的动画 → 上传」:
- 提交
.html文件 + 配套静态资源(CSS / JS / 图片) - 平台沙盒检测:
- 无外发 fetch / XHR / WebSocket(除白名单)
- 无危险 API 调用(eval / Function / document.write)
- 无访问父页面 cookie / localStorage
- 通过审核 → 获得 workId → 可被任何 .xwp 引用
沙盒规则
HTML 组件运行在 里,默认禁止:
- 外发 HTTP 请求(除非申请白名单)
- 访问父页面(演示文稿)的 DOM
- 跨域 Cookie / localStorage
- 弹窗 / 跳转
例外允许:
- 父页面 → 子组件:通过
postMessage传参数 - 子组件 → 父页面:通过
postMessage上报变量(用于课堂数据)
双向通信 API
// 子组件内
window.parent.postMessage({
type: 'xwp:var-update',
data: { v0: 12.5, result: 'correct' }
}, '*')
// 父页面(玄武屏播放器)自动监听变量上报后可进入课堂学情数据流,详见「43. 课后回看与学情数据」。
演示模式 vs 交互模式
跟 GGB 元素一样:
| 模式 | 触发 | 行为 |
|---|---|---|
| 演示模式 | 单击 | 触发动画 / 跳转 |
| 交互模式 | 双击 | 进入组件内部,可操作;按 Esc 退出 |
interactable: false 的组件纯展示,不可操作。
性能注意
HTML 组件单页 ≤ 2 个最佳。每个 iframe 都是独立 JS 上下文,开销不小。
低端硬件(教室 PC / 老平板)建议:
- 用 WebP 图片代替 SVG 动画
- 简化 Three.js 场景(< 5 万顶点)
- 避免 60fps 高频动画
详见「28. 动画性能预算」。
行业组件库
平台预置了各行业的 HTML 组件库:
- 教育:物理 / 化学仿真
- 医疗:人体解剖 / 手术模拟
- 建筑:户型漫游 / 户型对比
- 数据:实时大屏 / 表格仪表盘
详见「行业方案」相关章节。
下一节讲数学公式元素。
