HTML <model> 元素登陆每一个 Apple 操作系统

在 WWDC 2026 上，一位 Safari 工程师只用一个标签 <model>，没有任何 JavaScript 库，就把一柄 3D 露营木槌放到了电商产品页上，并让访客用手指转动它。¹ 让这一切成为可能的元素，早已在 visionOS 上发布了一段时间。2026 年的新闻是：同样的标记现在能在 iPhone、iPad 和 Mac 的 Safari 中渲染，围绕它的 JavaScript API 也成熟了起来。Apple 说得很直白：「我们在 visionOS 中首创了 Model 元素……如今 Model 元素来到了 iOS、iPadOS 和 macOS！同样的标记、同样的元素，在 Apple 各个平台上通用。」¹

下面的演练遵循这场讲座给出的即插即用 3D 路径，从一个静态的 <img> 回退，到轨道交互、脚本化变换、烘焙动画播放，再到 AR Quick Look。这里的所有内容均直接来自 WWDC 2026 第 215 场讲座。

太长不看

• <model> 元素早先在 visionOS 上首次亮相；WWDC 2026 将其扩展到 iOS、iPadOS 和 macOS 的 Safari，并让围绕它的 JavaScript API 趋于成熟。¹
• 嵌入模型就像嵌入媒体一样：把 src 指向一个 USDZ 文件，像 <video> 那样加上带 MIME 类型的 <source> 标签，并在内部嵌套一个 <img> 作为尚不支持该元素的浏览器的回退。¹
• ready promise 会告诉你模型何时加载完成，让你得以撤下加载动画；一个 catch 块会在失败时显示回退内容。¹
• stagemode="orbit" 属性用一个属性就带来交互式旋转；若要做脚本化控制，则将 stagemode="none"，并用通过 rotateSelf 构建的 DOMMatrix 驱动 entityTransform。¹
• 烘焙动画通过 playbackRate 加上 play() 来播放，负速率会让它倒放，而把模型包进 <a rel="ar"> 则为 iOS 和 iPadOS 访客带来完整的 AR Quick Look 体验。¹

实际发布了什么

来自 Safari 团队的 Aleksei 从 0:37 开始介绍这次跨平台扩展。

这里诚实的表述很重要。<model> 元素并非全新事物。Apple 先在 visionOS 上发布了它，在那里它自带立体渲染，使产品在 Apple Vision Pro 上能呈现出真实的纵深感。¹ WWDC 2026 在这一基础之上做了两件事：将该元素带到 iOS、iPadOS 和 macOS 的 Safari，使「无论访客是在外出途中用 iPhone、在咖啡馆用 iPad，还是在办公桌前用 Mac，你的 3D 内容都能触达每一位 Safari 访客」；并充实了将静态查看器变成交互式查看器的那套 JavaScript API。¹

它对现状的主张直截了当。如今网页上的多数 3D 都通过流行的 JavaScript 库 model-viewer 来运行。Apple 的论点是：原生元素无需额外的库，「由平台直接」渲染，而且是「一项正在形成的网页标准，因此你的代码面向未来。」¹ Apple 的 Safari 团队表示，他们正「积极为 W3C 的 model 规范作出贡献」，并通过 Immersive Web Community Group 征集反馈。¹ 对于尚不支持该元素的浏览器，讲座指向了一个 polyfill，它「通过 JavaScript 为新标准的 API 做了后向适配」，其中有一个值得引用的注意点：「该元素的某些特性无法被 polyfill，例如 Apple Vision Pro 等空间平台上的立体显示。」¹

内容格式是 USDZ，即「Universal Scene Description，压缩进单个文件」，它「打包了一个 3D 模型所需的一切：几何体、材质、纹理、动画。」¹ Safari 也支持其他格式，但讲座推荐用 USDZ 以获得最佳体验。¹ 这些资产从何而来则是另一个问题。Apple 推荐采用「捕捉、转换、创建」的方法：用 iPhone 扫描真实物体、转换现有文件，或在 Blender 之类的工具中从零构建。¹ 讲座还指出，生态中已有生成式工具；被点名的应用 Tripo3D 和 Meshy.ai 是第三方服务，而非 Apple 产品。¹

在页面上放置一个模型

这个元素的表现就像每位网页开发者早已熟知的媒体标签。「就像 <img> 标签或 <video> 标签一样，你用 source 属性把 <model> 标签指向一个文件，剩下的交给浏览器处理。无需任何插件。」¹ 你也可以使用嵌套的带 MIME 类型的 <source> 标签，模式与 <video> 相同（讲座展示了这一模式但未点出取值；model/vnd.usdz+zip 是标准的 USDZ 媒体类型）。回退正是让今天采用它变得安全的那一部分：在 <model> 内部放一个 <img>，旧版 Safari 或不支持的浏览器就会改为渲染该图片。¹

<model src="mallet.usdz">
  <source src="mallet.usdz" type="model/vnd.usdz+zip">
  <img src="mallet.jpg" alt="露营木槌" width="480" height="480">
</model>

3D 模型动辄「数十兆字节甚至更大」，因此加载需要时间。¹ ready promise 会在模型真正加载完成、可供显示时兑现。在等待时显示一个加载动画，在 ready 兑现时隐藏它，并在 catch 块中通过展示回退内容来处理任何意外情况：

const model = document.querySelector("model");

try {
  await model.ready;
  spinner.hidden = true;       // model is loaded and ready to display
} catch (error) {
  spinner.hidden = true;
  fallback.hidden = false;     // show fallback content on failure
}

有一个渲染细节常让人栽跟头。<model> 元素「在它自己的虚拟空间中渲染，因此不会沿用页面的背景。」¹ 要与页面设计相匹配，请直接在模型上设置 background-color。讲座补充了一条约束：「背景始终以不透明方式渲染，即便你指定了带透明度的颜色，它也会被转换。」¹

让访客自由探索

最廉价的交互只需一个属性。有了 stagemode="orbit"，访客可以「自由地左右旋转模型，如果他们把它向上或向下倾斜，它会轻柔地回弹到原始角度。」¹ 模型还会略微缩小，以免旋转过程中有部件被裁切。¹ 对大多数产品页而言，这一个属性就是全部功能：「orbit 这种 stagemode 用一个属性就为你带来交互式 3D。」¹

当你需要精确的角度时，就改用 JavaScript 来驱动模型。entityTransform 属性「让你通过 JavaScript 设置精确的观察角度。」¹ 要使用它，先禁用 orbit：要么移除 stagemode 属性，要么把它设为 "none"。¹ 讲座警告：如果旋转到可见区域之外，手动变换可能会裁切或隐藏模型的部件，因此你可能需要调整位置。¹ 你用一个 DOMMatrix 来构建朝向，它「表示模型在 3D 空间中的朝向」，调用 rotateSelf 定义旋转，然后赋值给它：

// disable orbit: <model stagemode="none"> in the markup

// capture the original orientation up front, for Reset
const initialTransform = model.entityTransform;

// Side view: rotate 135 degrees around the Y axis
sideButton.addEventListener("click", () => {
  const matrix = new DOMMatrix();
  matrix.rotateSelf(0, 135, 0);
  model.entityTransform = matrix;
});

// Reset to the original orientation
resetButton.addEventListener("click", () => {
  model.entityTransform = initialTransform;
});

赋值一个变换会让视角瞬间切换。为了让过渡平滑，讲座用 requestAnimationFrame 为旋转添加动画，动画时长为 500 毫秒，「半秒钟，感觉既利落又流畅」，在各帧之间缓动旋转，并在每一帧用一个新的 DOMMatrix 更新 entityTransform。¹ 用 Apple 自己的话说，这是诚实的取舍：自定义变换「给你完全的控制权，但需要额外的工作：包围盒、裁切、手动的动画代码。」¹ 需要时就动用脚本化变换，不需要时就依靠 stagemode="orbit"。

播放烘焙动画，然后进入 AR

模型也可以携带自己的运动。动画「通常在 Blender 或 Maya 等 3D 工具中创作，并烘焙进 USDZ 文件」，而该元素「播放第一条动画轨道。」¹ 两行 JavaScript 即可控制播放：在模型上设置 playbackRate，然后调用它的 play() 方法。正值向前播放，负值倒放，讲座用 5 和 -5 来实现更快的播放：

function play(rate) {
  model.playbackRate = rate;   // positive plays forward, negative reverses
  model.play();
}

play(5);    // fast forward
play(-5);   // fast reverse

最后一步把产品从屏幕中带出来，带进房间里。「把模型包进一个带 rel="ar" 属性的 <a> 标签，指向同一个资源，在 iOS 和 iPadOS 上，你的顾客就能获得完整的 AR Quick Look 体验。」¹

<a rel="ar" href="mallet.usdz">
  <model src="mallet.usdz">
    <img src="mallet.jpg" alt="露营木槌">
  </model>
</a>

在 visionOS 上，该元素早已让 3D「感觉像是网页的自然组成部分」，其立体渲染让顾客能「把产品从页面里拽出来，仿佛它就在手中一般端详」，它还驱动着沉浸式网站环境，把访客直接从 Safari 置身于一个场景之中。¹

把它做得更小再发布

本地文件看起来很棒；同样的文件通过互联网传输则加载缓慢。讲座对模型运行了一个命令行工具 usdcrush：「在画质毫无变化的情况下，文件从 7.9 MB 降到了 1.9 MB」，两个版本在 Safari 中并排打开看起来一模一样。¹ 一个配套工具 usdrecord，能在你还没有缩略图或回退图片时，直接从一个 3D 文件生成一张，并提供诸如输出格式、或从文件中的自定义相机进行渲染等选项。¹ 这两个工具「都已作为更大的 USD 套件的一部分安装在你的 Mac 上」，讲座还指出你可以对整个目录批量运行 usdrecord 脚本。¹ 至于格式本身，Alliance for OpenUSD 发布了完整的 USDZ 规范，作为「一份清晰、厂商中立的参考」，并附带转换工具。¹

实验室在尺寸与加载上补充了什么

WWDC 实验室填补了讲座未尽的若干细节。

在压缩方面，usdcrush 现在将纹理编码为 AVIF；此前它使用的是 JPEG。² Apple 还表示，正与 Alliance for Open Media 讨论一种合适的网格压缩格式。²

在尺寸方面，专家组未给出硬性上限，但建议页内模型的最高视觉质量大约落在 10 MB。沉浸式环境合理地可以更大。²

在加载方面，专家组承认存在一处空白：如今还没有针对模型加载状态的 CSS 伪类，因此前面讲到的 ready promise 才是这项工作的工具。² 专家组还提出了一个值得牢记的两阶段区分：字节已下载并不等同于该资源已被处理并可用。²

关键要点

给网页开发者： - 今天就加上 <model>，并在内部嵌套一个 <img> 回退，这样不支持的浏览器会降级为一张静态图片，而支持的 Safari 会自动升级为交互式 3D。¹ - 让显示取决于 ready promise，并在 catch 中处理失败，因为一个数兆字节的 USDZ 确实需要时间来加载。¹

给 3D 艺术家： - 在 Blender 或 Maya 中把你的第一条动画轨道烘焙进 USDZ；该元素会播放它，并暴露 playbackRate 加上 play() 以实现正向与反向控制。¹ - 发布前运行 usdcrush 以在画质无可见损失的情况下削减文件大小，再用 usdrecord 从模型本身生成 <img> 回退。¹

给产品与电商团队： - 用 stagemode="orbit" 实现一个属性的交互式旋转，并把脚本化的 entityTransform 留给那些需要精确角度或自定义 UI 的情形。¹ - 把模型包进 <a rel="ar">，让 iOS 和 iPadOS 的购物者能通过 AR Quick Look 把产品放进自己的空间。¹

常见问题

HTML <model> 元素在 2026 年是全新的吗？

不是。Apple 先在 visionOS 上发布了 <model> 元素。WWDC 2026 用同样的标记将它扩展到 iOS、iPadOS 和 macOS 的 Safari，并让围绕它的 JavaScript API（ready promise、entityTransform、烘焙动画播放，以及 <a rel="ar">）趋于成熟。¹

我该如何为不支持 <model> 的浏览器添加回退？

在 <model> 标签内部嵌套一个 <img> 标签。旧版 Safari 和尚不支持该元素的浏览器会改为渲染该图片，访客仍能看到产品。此外也有 polyfill 可用，不过某些特性（例如 visionOS 立体显示）无法被 polyfill。¹

<model> 元素使用什么文件格式？

USDZ，即 Universal Scene Description 压缩进单个文件，打包了几何体、材质、纹理和动画。Safari 也支持其他格式，但 Apple 推荐用 USDZ 以获得最佳体验，而 Alliance for OpenUSD 发布了完整规范。¹

我该如何让模型变得可交互？

设置 stagemode="orbit"，用一个属性实现自由的左右旋转。若要精确角度，则将 stagemode="none"，用 rotateSelf 构建一个 DOMMatrix，并把它赋给模型的 entityTransform 属性，如果你想要平滑过渡，就用 requestAnimationFrame 跨帧添加动画。¹

我该如何把一个网页模型带入增强现实？

把 <model> 包进一个带 rel="ar" 属性的 <a> 标签，指向同一个 USDZ 资源。在 iOS 和 iPadOS 上，这会为访客带来完整的 AR Quick Look 体验，让他们把产品放进自己的环境中。¹

<model> 元素依托于 Apple 正在其各平台上推广的同一套 USD 基础：参见 Apple 全新的 Swift 原生 USD 框架 USDKit，以及 visionOS 27 有哪些新变化 中的空间背景。用标签替代库这一论点，契合 无构建宣言 与 HTML 是 agent 想要的格式 中的更宏观论述。完整系列的中心页是 Apple 生态系统系列。

参考资料