# @hyperframes/core 中文文档

规范地址：https://npmcn.com/package/%40hyperframes/core/

版本：0\.8\.226
npm 元数据更新时间：2026-11-01T06:32:57.547Z
中文译文更新时间：2026-11-01T10:55:06.021Z
软件包许可：未声明

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40hyperframes/core
原文对照：https://npmcn.com/package/%40hyperframes/core/?lang=original
项目主页：https://github.com/heygen-com/hyperframes#readme
源码仓库：https://github.com/heygen-com/hyperframes

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：4.1 MB，454 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：8 个
- 首次发布：2026-03-23T01:09:05.497Z
- 最新版本发布：2026-11-01T06:32:57.215Z
- 已发布版本数：581（近 12 个月 581 个）

## 中文简介

用于超帧视频框架的类型、解析器、生成器、编译器、筛选器、运行时和帧适配器。

## 安装

```sh
npm install @hyperframes/core
```

也可以使用：`pnpm add @hyperframes/core`、`yarn add @hyperframes/core`、`bun add @hyperframes/core`

## README

# @hyperframes /核心

用于超帧视频框架的类型、解析器、生成器、编译器、筛选器、运行时和帧适配器。

## 安装

```bash
npm install @hyperframes/core
```

> 大多数用户不需要直接安装core [命令行界面](https://npmcn.com/package/%40hyperframes/cli)， [生产商](https://npmcn.com/package/%40hyperframes/producer), [工作室](https://npmcn.com/package/%40hyperframes/studio) 包在内部依赖于它。

## 里面有什么

| 模块 | 描述 |
| --- | --- |
| **类型** | `TimelineElement`， `CompositionSpec`， `Asset`，画布尺寸，默认值 |
| **解析器** | `parseHtml` -从HTML中提取时间轴元素； `parseGsapScript` -解析GSAP动画 |
| **发电机** | `generateHyperframesHtml` -从组合规范中生成有效的超框架HTML |
| **编译器** | `compileTimingAttrs` ——解决 `data-start` / `data-duration` 变成绝对时间 |
| **剥绒机** | `lintHyperframeHtml` -验证超帧HTML（缺少属性，重叠轨道等） |
| **运行时** | IIFE脚本注入到浏览器-管理查找，媒体播放，和 `window.__hf` 协议 |
| **帧适配器** | 可插入的动画驱动程序（GSAP、Lottie、CSS或自定义） |

## 生成的组合信任

组合生成器需要受信任的作者提供承载代码的输入。 `styles` 和 `generateHyperframesStyles` 保留可加载外部资源的编写CSS。 `animations` 可能包含 `__raw:` 作为JavaScript发出的值； `includeScripts: true` 包括可执行的时间线代码。 `serializeGsapAnimations` 也接受raw `preamble`， `postamble`，以及密码方位 `timelineVar`。永远不要把 这些输入包含不可信的数据。属性编码和结束标记包含 不是沙盒；以适当隔离的方式呈现不可信的组合 执行环境，永远不要在特权源上为它们提供服务。

文本内容保留支持的内联格式清理程序契约。的剪辑 Parser有意将内部格式扁平化为文本，因此parse/generate不会 编辑源HTML的无损替代品。

## 帧适配器

帧适配器告诉引擎如何将你的动画寻找到一个特定的帧：

```typescript
import { createGSAPFrameAdapter } from "@hyperframes/core";

const adapter = createGSAPFrameAdapter({
  getTimeline: () => gsap.timeline(),
  compositionId: "my-video",
});
```

实现 `FrameAdapter` 对于自定义动画运行时：

```typescript
import type { FrameAdapter } from "@hyperframes/core";

const myAdapter: FrameAdapter = {
  id: "my-adapter",
  getDurationFrames: () => 300,
  seekFrame: (frame) => {
    /* seek your animation */
  },
};
```

## 解析和生成HTML

```typescript
import { parseHtml, generateHyperframesHtml } from "@hyperframes/core";

const { elements, metadata } = parseHtml(htmlString);
const html = generateHyperframesHtml(spec);
```

## 产品毛羽

```typescript
import { lintHyperframeHtml } from "@hyperframes/core/lint";

const result = lintHyperframeHtml(htmlString);
// result.findings: { severity, message, elementId }[]
```

## 文档

完整的文档: [hyperframes.heygen.com/packages/core](https://hyperframes.heygen.com/packages/core)

## 相关的包

-   [`@hyperframes/engine`](https://npmcn.com/package/%40hyperframes/engine) -驱动浏览器的渲染引擎
-   [`@hyperframes/producer`](https://npmcn.com/package/%40hyperframes/producer) -完整的渲染管道（捕获+编码）
-   [`hyperframes`](https://npmcn.com/package/%40hyperframes/cli) - - - - - - CLI

## 常见问题

### @hyperframes/core 是什么？

用于超帧视频框架的类型、解析器、生成器、编译器、筛选器、运行时和帧适配器。

### 如何安装 @hyperframes/core？

在项目目录运行 npm install @hyperframes/core，或使用 pnpm add / yarn add / bun add。

### @hyperframes/core 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @hyperframes/core 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @hyperframes/core 可以商用吗？

@hyperframes/core 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @hyperframes/core 还在维护吗？

最新版本 0\.8\.226 发布于 2026/11/01（2 天前）；至今共发布 581 个版本，其中过去 12 个月发布了 581 个；首次发布于 2026/03/23。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。