@hyperframes/玩家 - HyperFrames

播放器包提供了一个 <hyperframes-player> 自定义元素，该元素将 HyperFrames 组合嵌入到任何位置（任何框架或纯 HTML 中）。零依赖性，3KB gzip 压缩。

npm install @hyperframes/player

何时使用

当您需要时使用 @hyperframes/player：

将渲染的合成嵌入网站、仪表板或应用程序中
将类似视频的播放器添加到着陆页或产品演示中
显示文档或博客文章中的成分

如果您愿意，请使用不同的包：

交互式编辑作品 — 使用 studio
开发期间预览 - 使用 CLI (npx hyperframes preview)
渲染为 MP4 — 使用 CLI 或生产者

快速入门

通过CDN

<script type="module" src="https://cdn.jsdelivr.net/npm/@hyperframes/player"></script>

<hyperframes-player
  src="./my-composition/index.html"
  controls
  autoplay
  muted
  style="width: 100%; max-width: 800px; aspect-ratio: 16/9"
></hyperframes-player>

如果您需要经典的 <script> 标签而不是 ESM，请使用显式全局构建：

<script src="https://cdn.jsdelivr.net/npm/@hyperframes/player/dist/hyperframes-player.global.js"></script>

通过npm

import '@hyperframes/player';

<hyperframes-player src="/compositions/intro.html" controls></hyperframes-player>

HTML 属性

属性	类型	默认	描述
`src`	细绳	必需的	URL 或合成 HTML 的相对路径
`width`	数字	1920	构图宽度（以像素为单位）
`height`	数字	1080	构图高度（以像素为单位）
`controls`	布尔值	错误的	显示播放控件叠加层
`autoplay`	布尔值	错误的	开始加载播放
`loop`	布尔值	错误的	循环播放
`muted`	布尔值	真的	静音音频（大多数浏览器中自动播放所需）
`poster`	细绳	—	首次播放前显示的图像 URL
`playback-rate`	数字	1	播放速度倍增器

JavaScript API

播放器镜像原生 <video> 元素 API：

const player = document.querySelector('hyperframes-player');

// Playback
player.play();
player.pause();
player.seek(2.5); // seek to 2.5 seconds

// Properties
player.currentTime;     // number — current position in seconds
player.currentTime = 5; // seek to 5 seconds
player.duration;        // number — total duration
player.paused;          // boolean
player.ready;           // boolean — true after composition loads
player.playbackRate;    // number — get/set speed
player.muted;           // boolean — get/set mute
player.loop;            // boolean — get/set loop

活动

const player = document.querySelector('hyperframes-player');

player.addEventListener('ready', (e) => {
  console.log('Duration:', e.detail.duration);
});

player.addEventListener('timeupdate', (e) => {
  console.log('Time:', e.detail.currentTime);
});

player.addEventListener('play', () => console.log('Playing'));
player.addEventListener('pause', () => console.log('Paused'));
player.addEventListener('ended', () => console.log('Ended'));
player.addEventListener('error', (e) => console.error(e.detail.message));

事件	细节	描述
`ready`	`{ duration }`	已加载合成并发现时间线
`timeupdate`	`{ currentTime }`	播放期间触发 (~30fps)
`play`	—	播放开始
`pause`	—	播放暂停
`ended`	—	播放已结束
`error`	`{ message }`	加载或运行时错误

框架示例

反应

import '@hyperframes/player';

function VideoPreview({ src }) {
  return (
    <hyperframes-player
      src={src}
      controls
      style={{ width: '100%', maxWidth: 800 }}
    />
  );
}

维埃

<template>
  <hyperframes-player :src="compositionUrl" controls />
</template>

<script setup>
import '@hyperframes/player';
const compositionUrl = './compositions/intro.html';
</script>

程序化

import '@hyperframes/player';

const player = document.createElement('hyperframes-player');
player.src = './my-composition/index.html';
player.controls = true;
player.addEventListener('ready', () => player.play());
document.getElementById('player-container').appendChild(player);

高级：iframe 访问

该组合在玩家 Shadow DOM 的沙盒 <iframe> 内运行。对于大多数用例，您不需要直接访问 - JavaScript API 和上面的事件就足够了。但是，如果您要在播放器之上构建编辑器、记录器或自定义时间线，则需要检查合成的 DOM 或读取其 __player / __timelines 运行时对象。 iframeElement getter 为这些消费者公开内部 iframe：

const player = document.querySelector('hyperframes-player');
const iframe = player.iframeElement;

// Reach into the composition's DOM
iframe.contentDocument.querySelectorAll('[data-composition-id]');

// Read the runtime (GSAP timelines, element registry, etc.)
iframe.contentWindow.__timelines;

这是将玩家桥接到 @hyperframes/studio 等编辑器工具的规范方法。工作室导出一个 resolveIframe 帮助器，用于处理直接 iframe 引用和 Web 组件引用：

import { useTimelinePlayer, resolveIframe } from '@hyperframes/studio';

const { iframeRef } = useTimelinePlayer();
const player = document.createElement('hyperframes-player');
player.setAttribute('src', src);
container.appendChild(player);

// Forward the inner iframe so useTimelinePlayer can drive play/pause/seek.
iframeRef.current = resolveIframe(player);

React：声明性引用模式

如果您更喜欢 JSX 而不是命令式元素创建，请将引用附加到 Web 组件并解析效果内的 iframe：

import '@hyperframes/player';
import type { HyperframesPlayer } from '@hyperframes/player';
import { useTimelinePlayer, resolveIframe } from '@hyperframes/studio';

function StudioPreview({ src }: { src: string }) {
  const { iframeRef, onIframeLoad } = useTimelinePlayer();
  const playerRef = useRef<HyperframesPlayer>(null);

  useEffect(() => {
    iframeRef.current = resolveIframe(playerRef.current);
  });

  return (
    <hyperframes-player
      ref={playerRef}
      src={src}
      onLoad={onIframeLoad}
    />
  );
}

常见问题 — 如果将 <hyperframes-player> 元素本身（不是 iframeElement）传递到需要 <iframe> 的挂钩或 API 中，则每个 .contentWindow / .contentDocument 访问都会返回 null，因为 iframe 位于玩家的 Shadow DOM 内部。时间轴搜索、播放、暂停和 DOM 检查都是静默无操作的。 始终首先提取 iframeElement，或使用 @hyperframes/studio 中的 resolveIframe 来透明地处理 iframe 和 Web 组件主机。

建筑学

播放器在 Shadow DOM 容器内使用 iframe。这提供了：

隔离 — 组合 CSS/JS 不会泄漏到您的页面或与您的页面发生冲突
安全性 — iframe 沙箱限制组合功能
缩放 — 通过 CSS 转换自动缩放合成以适合玩家的容器

播放器通过 HyperFrames 运行时桥接协议 (postMessage) 与合成进行通信。现有的组合物无需修改即可工作。

控制

当存在 controls 属性时，底部会出现最小覆盖层：

播放/暂停按钮（左）
滑动条 支持拖动（鼠标+触摸）
时间显示 显示当前/总持续时间（右）
3 秒不活动后自动隐藏，悬停时重新显示

​何时使用

​快速入门

​通过CDN

​通过npm

​HTML 属性

​JavaScript API

​活动

​框架示例

​反应

​维埃

​程序化

​高级：iframe 访问

​React：声明性引用模式

​建筑学

​控制

何时使用

快速入门

通过CDN

通过npm

HTML 属性

JavaScript API

活动

框架示例

反应

维埃

程序化

高级：iframe 访问

React：声明性引用模式

建筑学

控制