product-viewer · 一行标签，把 3D 商品装进详情页

深色 · 自动旋转

background="#141414" auto-rotate

详情页首屏的标准摆法：深色底托住产品，自己慢慢转。点金色圆点，卖点卡从底部浮上来。

浅色 · 手动旋转

background="#e9e6dd"

浅色站点的配法：不自动转，把主动权留给用户。拖一下，阻尼会带着它滑到停——不是硬停。

透明底 · 叠在排版上

background="transparent" rotate-speed="8"

品牌大片式的摆法：背景透明，产品直接站在你的排版上。转速调慢，配大标题一起看。

参数

属性驱动，多实例共存。改属性即改行为，不用碰 JS。

`src`	GLB 模型地址（必填）。支持 gzip，draco 压缩的模型自带解码器，不用配路径。
`auto-rotate`	出现即自动旋转。用户拖动后暂停 2.5 秒再缓缓恢复；卖点卡打开时暂停。
`rotate-speed`	转速，度/秒，默认 14。
`background`	底色，任何 CSS 颜色；填 `transparent` 得到透明底。
`poster`	封面图。无 WebGL 或模型加载失败时降级显示。
`alt` / `exposure`	无障碍描述 / ACES 曝光补偿，默认 1.0。
`data-hotspot`	写在标签里的 `<button data-hotspot data-pos="x,y,z" data-title data-desc>` 即热点。坐标是归一化模型坐标（最长轴为 [-1,1]，中心为原点）。
JS API	`viewer.ready`（Promise，首帧渲染后兑现）、`viewer.addHotspot({pos,title,desc})`、`viewer.setAutoRotate(bool)`，以及模块导出的 `CONFIG` 全局默认。

如何嵌入已有页面

两条路：拿单文件最省事，用源码版最灵活。两种都不需要构建工具。

拿走单文件（推荐）

先打包：python3 ~/workspace/bin/fx-singlefile.py product-viewer-lite，得到单文件 index.html。从里面复制三段进你的页面：<style>（演示样式可删）、importmap 那段、<script type="module">（组件本体）。然后在任意位置放标签：

<!-- 1. head 里放 importmap（整站只需一次） -->
<script type="importmap">{ "imports": { "three": "…" } }</script>
<!-- 2. body 末尾放组件脚本 -->
<script type="module"> /* 单文件里那段 */ </script>
<!-- 3. 想放哪放哪 -->
<product-viewer src="https://你的CDN/耳机.glb" auto-rotate background="#141414">
  <button data-hotspot data-pos="0.48,-0.31,0"
    data-title="40mm 镀钛动圈" data-desc="低频下潜深，人声不闷。">1</button>
</product-viewer>

用源码版

把 src/ 和 vendor/ 两个目录原样拷进你的站点（相对位置保持：src 里引用的是 ../vendor/…）。页面里加三行：

<!-- 样式按需取用，组件自带影子样式，不依赖它 -->
<link rel="stylesheet" href="src/styles.css">
<script type="importmap">{ "imports": { "three": "./vendor/three.module.js" } }</script>
<script type="module" src="src/main.js"></script>

配一张封面图

加 poster="cover.jpg"：老设备没有 WebGL、弱网加载失败时，用户看到的是封面而不是黑屏。这是唯一推荐配的图片资源。

模型地址必须是允许跨域的 CDN（响应头带 Access-Control-Allow-Origin），否则浏览器会拦截模型加载。R2 公开桶记得开 CORS。