用途:在 HyperFrames 中作为 3D 内容轮播动画区块使用,卡片内容随一组圆角倒角长方体从右飞入、错位旋转巡航、减速定格于“主角”卡片后向左退出。间距由长方体尺寸与最大可用 X 半轴长度推导,因此长方体之间不会重叠。
主要能力:40 个变量覆盖几何(宽、高、厚、圆角半径、倒角尺寸与厚度、平滑度)、材质(颜色、粗糙度、金属度)、灯光(环境/顶部/底部/主光强度与颜色)、阴影(软度、贴图尺寸)、背景色、相机(初始与目标 FOV、位置、稳定帧、手持强度)以及各段时长与缓动。卡片来自内置列表或 JSON 变量(cardsJson)。运行时每帧为时间的闭式函数,仅使用带种子的 PRNG,无 rAF 循环、无 Date.now,通过 hf-seek 事件重新同步,注册为 window.__timelines["cuboid-carousel"] 的暂停 GSAP 时间轴。渲染依赖 WebGL、GSAP、Canvas 2D、PMREM 与阴影贴图,外部依赖为 ./assets/three.module.min.js 与 ./assets/addons/,Web 字体使用 Google Fonts 的 Inter。
使用方式:安装用 npx hyperframes add cuboid-carousel,文件默认落在 compositions/cuboid-carousel/ 下。然后在宿主 index.html 中以属性 data-composition-id="cuboid-carousel"、data-composition-src="compositions/cuboid-carousel/cuboid-carousel.html"、data-start="0"、data-duration="6.666666666666667"、data-track-index="1"、data-width="1920"、data-height="1080" 挂载。自定义变量渲染示例:npx --yes hyperframes@0.8.12 render 'compositions/cuboid-carousel/cuboid-carousel.html' --variables '{"cardsJson":"","heroCard":4}'。
适用场景:需要 1080p 3D 卡片轮播的合成或演示画面。
限制:每个实例约占用 350 MB,需一次只运行一个。data-composition-variables 必须保持单引号属性、内部为纯 JSON,且不要通过 Studio 的设计面板保存;<canvas> 不可写入静态标记,须在运行时创建;所有视觉状态必须保持为 t 的函数以保证可定位渲染。其余兼容性、授权与计费细节暂未提供。