Model tag

简介

Model tag (<model>)是Apple在WWDC26 2026六月推出的一个基于safari浏览器原生实现的h5标签，可以直接在上面展示模型。本文介绍了一些基础用法。

官方教程: https://developer.apple.com/videos/play/wwdc2026/215/

复现demo: https://gemini2035.github.io/demos/model-tag/index.html

基本使用

<model src="your own model">
    <p>This model tag is only supported in Safari</p>
</model>

这样就能在safari页面中看到渲染完成的模型了。另外，model中包含的元素就是作为当浏览器不支持model标签时的fallback显示

背景颜色

model渲染有内置容器，需要通过样式显式控制背景颜色：

<model class="background-model" src="your own model"></model>
<style>
    .background-model {
        background-color: #fff;
    }
</style>

需要注意的是，就算内外部颜色一致，最后呈现在浏览器中也可能不一致，不太清楚是不是bug：

Mac Safari

IOS Safari

更有趣的是，IOS Safari效果图是手拍的，如果换做截屏同样有底色不一致的情况。很神秘...

加载状态

<h1>Loading Promise</h1>
<div>
    <p class="state-info">Loading model...</p>
    <model id="model-1" src="your own model"></model>
</div>

<script>
const baseBallModel_1 = document.getElementById('model-1');

baseBallModel_1.ready.then(() => {
    document.querySelector('.state-info').style.display = 'none';
}).catch((error) => {
    console.error('Error loading model:', error);
    document.querySelector('.state-info').textContent = 'Error loading model.';
})
</script>

model标签提供了一个ready对象，通过Promise的方法可以让你自定义加载和异常状态，使页面更加对用户友好

官方动效

<model
    src="your own model"
    stagemode="orbit"
>
</model>

官方提供了stagemode="orbit"属性以支持拖动查看模型，在松手后模型会缓缓回归原位。这种内置动画在一般情况已经比较够用，但是如果你想要自定义动画，此属性的可拓展性则完全不足，甚至不利于扩展。

自定义变化

如4所述，如果你想自定义变化，stagemode则完全不够用，在自定义变化之前，请确保这个属性设置为了 none 或直接移除这个属性。

<model id="transformer-model" src="your own model"></model>
<div>
    <button id="button-side">Side</button>
    <button id="button-reset">Reset</button>
</div>

<script>
const TransformerModel = document.getElementById("transformer-model");
let initialTransform;

const rotateFromInitial = (rotationY) => {
    if (!initialTransform) return;

    const transform = new DOMMatrix(initialTransform);
    transform.rotateSelf(0, rotationY, 0);
    TransformerModel.entityTransform = transform;
};

TransformerModel.ready.then(() => {
    initialTransform = new DOMMatrix(TransformerModel.entityTransform);
});

document.getElementById("button-side")
    .addEventListener("click", () => {
        rotateFromInitial(135);
    });

document.getElementById("button-reset")
    .addEventListener("click", () => {
        if (!initialTransform) return;
        
        TransformerModel.entityTransform = new DOMMatrix(initialTransform);
    });
</script>

注意我实现的代码，如果你去官方网站查看实现，会发现我的版本多了很多代码，如果你浏览过视频，会注意到一句话：模型变换中模型可能会有意外缩放或跑出视图外的情况，需要额外处理。官方演示使用的示例没有遇到这种情况，但我在尝试复现的时候遇到了。核心问题如下：

model标签在加载完成后浏览器会生成一个初始矩阵，需要将这个矩阵传入DOMMAtrix后再进行变换，不然就会遇到意外情况。

过渡动画

<model id="animation-model" src="your own model"></model>
<button id="animation-button-side">Side</button>
<button id="animation-button-reset">Reset</button>

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

    animationModel.ready.then(() => {
        animationInitialTransform = new DOMMatrix(animationModel.entityTransform);
    });

    const rotateAnimationFromInitial = (rotationY) => {
        if (!animationInitialTransform) return;

        const transform = new DOMMatrix(animationInitialTransform);
        transform.rotateSelf(0, rotationY, 0);
        animationModel.entityTransform = transform;
    };

    function animateTo(targetAngle) {
        if (!animationInitialTransform) return;
        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;
            rotateAnimationFromInitial(currentAngle);
            if (progress < 1) animationId = requestAnimationFrame(step);
        }

        requestAnimationFrame(step);
    }

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

动画效果没啥好说的，直接使用requestAnimationFrame配合DOMMatrix就可以了，同样需要注意记录模型初始化的矩阵。

其它

官方示例还讲述了如何用polyfill回退、safari的AR功能和分步骤播放，这里由于没找到分步骤的模型，就不单独演示了

总结

这种方式的优点就是实现简单，且为浏览器内置标签。对比WebGL的canvas组合会比较轻量一些。但缺点也很明显，浏览器的局限性使得这个标签只能在Safari中使用。同时社区支持也完全不如后者，只能说未来可期吧。