HTML 模型元素入门

了解模型元素如何将交互式 3D 内容搬上你的网站，这项功能现已登陆 iOS、iPadOS、macOS 和 visionOS。探索用于创建和优化 3D 素材资源的工具。了解模型元素功能，看看各个网页标准如何构筑 3D 网页内容的未来。

章节

资源

相关视频

WWDC26

WWDC25

空间网页的新功能

WWDC24

USD 和 MaterialX 的新功能

大家好我是Aleksei Safari团队的工程师今天我很高兴向你介绍 HTML Model元素以及我们如何让开发者更轻松地将3D内容带到Web上覆盖Apple各平台乃至更广

无论你是首次探索3D的 Web开发者还是希望将作品带上Web的资深3D艺术家我都能为你提供入门所需的一切我们在visionOS中率先引入了Model元素—— 这是一个原生HTML元素让添加3D模型像添加图片一样简单现在Model元素来到了 iOS、iPadOS和macOS！相同的标记相同的元素可在Apple各平台上使用你的3D内容将触达每一位Safari访客无论他们是在外出时使用iPhone

在咖啡馆使用iPad

还是在桌前使用Mac 你可能熟悉"model-viewer" 这是目前主流的3D JavaScript库它为开发者提供了良好的服务但Model元素是原生的无需额外的库直接由平台渲染并在visionOS上内置立体渲染功能它也是一项新兴Web标准因此你的代码具有前瞻性为了覆盖Web上的所有平台我们为浏览器提供了polyfill 这些浏览器尚不原生支持 Model元素稍后我会详细介绍假设我正在开发一个户外探险电商平台而且我已经有了产品图片今天我将带你完成向产品页面添加3D模型的过程首先我将展示如何准备素材然后我们将深入了解Model元素逐步构建体验一次添加一个功能最后我将向你展示命令行工具以优化用于生产环境的模型让我们开始吧如果你一开始就没有3D素材该怎么办？

我们推荐捕获、转换、创建的方法用iPhone扫描真实物体转换现有文件或在Blender等工具中从头创建但生成式AI也迎来了一场革命随之而来的是一种全新方式来创建你想要的内容你可以用图片生成与真实物体匹配的模型或使用文字提示词进行更具创意的生成 Tripo3D和Meshy.ai等App 只是众多选择中的几个我的商店已有几款产品但我想添加一个必备品：一把露营槌我从槌的多张图片开始几分钟后我的模型就可以使用了我将其导出为USDZ文件 Model元素支持USDZ—— 即通用场景描述压缩成一个文件它打包了3D模型所需的一切：几何体材质纹理动画 Safari也支持其他格式但为了获得最佳体验我建议从USDZ开始现在是时候将模型放到页面上了现在槌已作为USDZ文件准备就绪我将介绍呈现Model元素的不同方式我将讲解如何嵌入模型了解何时可以显示以及如何处理降级方案如何使模型与页面设计相匹配让访客交互和探索我将指导你如何实现自定义变换和播放动画以及通过AR Quick Look和空间计算将模型带入现实世界好从加载模型开始就像标签或标签一样你只需将标签的 source属性指向一个文件浏览器会处理剩下的事无需任何插件你也可以使用标签指定mime类型同样与标签的模式相同考虑降级方案同样很重要最简单的方法是：在标签内放置一个标签旧版Safari以及尚不支持Model元素的浏览器将改为渲染图片你的访客仍然能对产品有所了解 3D模型的大小可能达到数十MB甚至更多因此加载可能需要一些时间 ready promise可让你知道模型何时实际加载完成并可以显示在模型加载时提供视觉提示是个好主意例如加载动画当ready promise完成时将其隐藏如果发生意外情况在catch块中处理并显示你的降级内容你也可以对模型功能进行polyfill polyfill通过JavaScript 为新标准的API提供向后兼容让你在所有平台支持之前就能使用现代功能 W3C的Model元素示例展示了这方面的例子如果原生元素在window上未被定义他们会加载polyfill库尽可能填补功能缺口尽量贴近原生API 只需确保测试两者的功能包括polyfill和原生元素并记住某些元素功能无法通过polyfill实现例如Apple Vision Pro等空间平台上的立体显示 Model元素在其自身的虚拟空间中渲染因此不会受到页面背景的影响为了与页面设计相匹配请直接在模型上设置background-color 请注意：背景始终以不透明方式渲染即使你指定了带透明度的颜色也会被转换现在我们已将模型加载并集成到现有页面中让访客可以与其互动是自然而然的下一步让我向你展示这有多简单值为orbit的stagemode属性让访客可以左右自由旋转模型如果他们上下倾斜模型会轻轻弹回到原始角度交互性强同时始终保持最佳外观该属性还会使模型略微缩小—— 模型将被重新缩放以确保旋转时不会有部分被裁剪有时你想为体验添加自定义交互功能 entityTransform属性让你可以通过JavaScript设置精确的视角我将添加两个按钮来演示其工作方式：一个用于侧面视图一个重置按钮将模型恢复到原始方向要使用entityTransform 你需要禁用orbit—— 移除stagemode属性或将其设置为"none"

手动变换模型时部分内容可能会被裁剪甚至会消失如果旋转超出可见区域你可能需要调整位置使其可见

为了实现变换我创建了一个DOMMatrix ——这代表模型在 3D空间中的方向—— 然后调用rotateSelf 来定义旋转这里我们围绕Y轴旋转135度以获得侧面视图最后将其赋值给 model.entityTransform 以应用更改

预先捕获初始变换然后使用它将模型重置回原始方向视图瞬间从一个切换到另一个为了让过渡更流畅你可以使用requestAnimationFrame 为旋转添加动画首先设置状态：当前角度以毫秒为单位的动画时长 ——500代表半秒感觉既敏捷又流畅—— 以及用于取消进行中动画的引用

animateTo首先取消所有正在运行的动画以防过渡冲突捕获当前角度作为起点并标记开始时间

然后我添加step函数在每一帧它计算动画的进度为旋转添加缓动以实现平滑结束并使用新的DOMMatrix 更新entityTransform 当动画仍在运行时它会请求下一帧

最后将animateTo调用分配给按钮侧面视图动画旋转至135度…… 重置为0 让我们看看实际效果当用户点击侧面按钮时模型会平滑旋转以显示侧面视图点击重置后它会滑回到初始位置自定义变换和动画让你拥有完全控制权但它们需要额外的工作：边界框裁剪手动动画代码如果你的使用场景允许 orbit stagemode让你只需一个属性即可实现3D交互选择最适合你产品的方式模型还可以通过内置动画活灵活现这些动画通常在Blender或Maya等 3D工具中创作并烘焙到USDZ文件中 Model元素会播放第一条动画轨道只需几行JavaScript 你就可以控制播放速率甚至通过提供负值让它反向播放为此我实现了一个简单的play函数它在模型上设置playbackRate 并调用模型的play()方法 ——就是这样正值向前播放负值则反向播放这里我使用5和-5 以实现更快的播放速度目前商店访客可以直接在页面上用3D探索产品但如果他们想看看它在自己环境中的样子呢？

用带rel="ar"属性的标签包裹模型指向相同的资源在iOS和iPadOS上你的客户可获得完整的AR Quick Look体验在visionOS上 Model元素已让3D内容成为Web的自然组成部分

通过立体渲染模型呈现出真实的深度感你的客户可以将产品从页面中拉出来仿佛就握在他们手中一样检视它 visionOS还支持沉浸式网站环境这些环境使用Model元素让你将受众直接带入场景中这一切都在Safari中完成

如果你想了解更多关于此功能的信息请务必查看 "探索沉浸式网站环境"专场其中详细介绍了API

素材准备就绪 Model元素也到位后让我们看看整体效果这是我们带有3D模型的目录页面而交互式探索是我个人最喜欢的功能你的客户可以旋转、倾斜并从各个角度查看产品以他们想要的方式探索一切都在Safari中运行我们的产品页面在本地运行效果出色但你可能会发现通过网络加载需要一些时间如果能缩小这些模型的体积就太好了为此我将运行一个命令行工具名为usdcrush 对模型执行压缩在质量不变的情况下文件从7.9 MB 降至1.9 MB！这真是惊人的节省！

在Safari中并排打开两个版本—— 看起来完全一样相同的视觉质量文件却显著缩小

如果你有3D文件但还没有对应的图片你可以使用usdrecord工具生成缩略图或直接生成降级图片指定输出格式或从自定义摄像机渲染如果文件中有的话而且与截图不同你可以编写脚本—— 好吧我就别自欺欺人了你最喜欢的LLM可以编写脚本 ——对整个目录批量运行这两个命令行工具已经安装在你的Mac上它们是用于处理USD内容的更大工具套件的一部分你可以了解更多相关信息以及整个USD生态系统…… 在WWDC24讲座《What's new in USD and MaterialX》中 Model元素从visionOS起步随着iOS、iPadOS和macOS的支持正在扩展至整个Apple生态而且我们希望将其带到更广泛的Web上我们的团队正积极参与 W3C的Model规范制定我们非常希望听到你的反馈如果有你想添加的功能或我们尚未考虑的使用场景现在正是分享反馈的好时机 Web标准由开发者社区塑造你的声音至关重要对于USDZ文件格式的3D内容 OpenUSD联盟已发布完整规范这是一个清晰、供应商中立的参考该联盟还提供转换工具和资源帮助你将USDZ集成到现有的内容流程中这就是Model元素 ——从素材到生产的全流程现在让我告诉你下一步尝试创建你自己的3D模型使用文字提示词或你已有的图片在你的网站中添加标签将其指向USDZ文件看看它在Safari中如何焕发生机使用USD工具优化你的素材在不同平台上尝试它看看元素如何适配加入W3C的沉浸式Web社区小组带上你的使用场景、反馈和想法查看相关专场例如"沉浸式网站环境" 如需深入了解空间Web功能请观看WWDC25的《What's new for the spatial web》我迫不及待地想看看你构建的作品感谢观看祝你WWDC愉快！

4:19 - Load a model

<!-- Using the src attribute -->
<model src="mallet.usdz"></model>

<!-- Using a <source> child for MIME type -->
<model>
    <source src="mallet.usdz" type="model/vnd.usdz+zip">
</model>

4:39 - Image fallback

<model id="mallet" src="mallet.usdz">
    <img src="mallet.png"
         alt="Rubber mallet with wooden handle">
</model>

5:09 - Ready promise

<model id="mallet" src="mallet.usdz"></model>

<script>
    const model = document.getElementById("mallet");
    model.ready.then(result => {
        // Hide the loading indicator
    }).catch(error => {
        // Loading failed, show fallback
    });
</script>

5:39 - Polyfill fallback

<script type="module">
    if (!window.HTMLModelElement) {
        import("model-element-polyfill.js").then(() => {
            // Polyfill ready to use
        });
    }
</script>

6:13 - Model background

<model id="mallet" src="mallet.usdz"></model>
<style>
    model {
        background-color: #f4f1ec;
    }
</style>

6:47 - Stage mode

<model id="mallet"
       src="mallet.usdz"
       stagemode="orbit">
</model>

7:31 - Custom transforms

<model id="boot" src="boot.usdz"></model>
<button id="button-side">Side</button>
<button id="button-reset">Reset</button>

<script>
    const model = document.getElementById("boot");
    const initialTransform = model.entityTransform;

    document.getElementById("button-side")
            .addEventListener("click", () => {
        const transform = new DOMMatrix();
        transform.rotateSelf(0, 135, 0);
        model.entityTransform = transform;
    });

    document.getElementById("button-reset")
            .addEventListener("click", () => {
        model.entityTransform = initialTransform;
    });
</script>

8:35 - Transition animation

<script>
    const model = document.getElementById("boot");
    const duration = 500;
    let currentAngle = 0;
    let animationId = null;

    function animateTo(targetAngle) {
        if (animationId) cancelAnimationFrame(animationId);
        const startAngle = currentAngle;
        const startTime = performance.now();

        function step(now) {
            const progress = Math.min((now - startTime) / duration, 1);
            const ease = 1 - Math.pow(1 - progress, 3);
            currentAngle = startAngle + (targetAngle - startAngle) * ease;
            model.entityTransform = new DOMMatrix().rotateSelf(0, currentAngle, 0);
            if (progress < 1) animationId = requestAnimationFrame(step);
        }

        requestAnimationFrame(step);
    }

    document.getElementById("button-side").addEventListener("click", () => animateTo(135));
    document.getElementById("button-reset").addEventListener("click", () => animateTo(0));
</script>

10:07 - Animation playback

<model id="bottle" src="bottle.usdz"></model>
<button id="button-play" onclick="play(5)">
    Play
</button>
<button id="button-reverse" onclick="play(-5)">
    Reverse
</button>

<script>
    const model = document.getElementById("bottle");

    function play(rate) {
        model.playbackRate = rate;
        model.play();
    }
</script>

11:06 - AR Quick Look

<a rel="ar" href="bottle.usdz">
    <model id="boot" src="bottle.usdz"></model>
</a>

0:00 - Introduction
The HTML model element, which brings 3D content to the web as simply as an image and now extends from visionOS to iOS, iPadOS, and macOS — how it compares to the model-viewer library and where it stands as an emerging web standard.
2:22 - Prepare the USDZ model asset
Approaches for creating 3D content: scanning with iPhone, converting existing files, authoring in tools like Blender, and generating models from images or text prompts. Why USDZ is the recommended format — it bundles geometry, materials, textures, and animations into a single file.
4:18 - Loading and fallbacks
Embed a model with the tag's src attribute or a nested . Use a nested as a fallback for older browsers, await the ready promise to know when the model can be displayed, and load the W3C polyfill so the element works where it isn't supported natively.
6:14 - Model background
Set background-color directly on the model element to match the surrounding page. The model renders in its own virtual space and doesn't inherit page styles, and any background is composited as fully opaque.
6:48 - Interactions
Add stagemode="orbit" to let visitors rotate the model with automatic spring-back and clipping protection. For custom interactivity, disable stagemode and drive the entityTransform property with a DOMMatrix to snap the model to specific viewing angles from JavaScript.
8:26 - Transition animation
Animate between custom orientations by updating entityTransform inside requestAnimationFrame. The pattern captures a starting angle, eases each frame's rotation, and cancels any in-flight animation so successive transitions don't conflict.
10:08 - Animation playback
Play animations baked into a USDZ file using the element's play() method and playbackRate property. Positive rates play forward, negative rates reverse, and the magnitude scales speed.
10:52 - AR and spatial
Wrap the model in an tag to enable AR Quick Look on iOS and iPadOS. On visionOS the model element renders stereoscopically and can power immersive website environments that place visitors inside a 3D scene.

12:29 - Optimize assets for production
Use usdcrush to shrink USDZ files (often by 4x) with no perceived quality loss, and usdrecord to render thumbnails or fallback images from a 3D file. Both ship with macOS as part of the broader USD tool suite.
14:53 - Next steps
Generate a 3D model from images or a prompt, add a tag to your site, optimize assets with usdcrush, and join the W3C Immersive Web Community Group to help shape the spec.

探索“入门汇总”

及时了解最新动态

探索“平台”

精选

探索“技术”

精选

探索“社区”

精选

探索“文档”

发布说明

探索“下载”

精选

探索“支持”

精选

快速链接

HTML 模型元素入门

章节

资源

相关视频

WWDC26

WWDC25

WWDC24