HyperFrames 레지스트리
레지스트리는 hyperframes add <name> 명령으로 설치할 수 있는 재사용 가능한 블록과 컴포넌트를 제공합니다.
- 블록 — 독립적인 하위 구성(자체 크기, 지속 시간, 타임라인). 호스트 구성에서
data-composition-src를 통해 포함됩니다. - 컴포넌트 — 효과 스니펫(자체 크기 없음). 호스트 구성의 HTML에 직접 붙여넣습니다.
빠른 참조
hyperframes add data-chart # 블록 설치
hyperframes add grain-overlay # 컴포넌트 설치
hyperframes add shimmer-sweep --dir . # 특정 프로젝트 대상
hyperframes add data-chart --json # 기계 판독 가능 출력
hyperframes add data-chart --no-clipboard # 클립보드 건너뛰기 (CI/헤드리스)
설치 후 CLI는 작성된 파일과 호스트 구성에 붙여넣을 스니펫을 출력합니다. 스니펫은 시작점일 뿐이며, 블록을 연결할 때 data-composition-id(블록의 내부 구성 ID와 일치해야 함), data-start, data-track-index 속성을 추가해야 합니다.
참고: hyperframes add는 블록과 컴포넌트에만 작동합니다. 예제의 경우 hyperframes init <dir> --example <name>을 대신 사용하세요.
설치 위치
블록은 기본적으로 compositions/<name>.html에 설치됩니다.
컴포넌트는 기본적으로 compositions/components/<name>.html에 설치됩니다.
이 경로는 hyperframes.json에서 구성할 수 있습니다:
{
"registry": "https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry",
"paths": {
"blocks": "compositions",
"components": "compositions/components",
"assets": "assets"
}
}
자세한 내용은 install-locations.md를 참조하세요.
블록 연결하기
블록은 독립적인 구성입니다. 호스트 index.html에서 data-composition-src를 통해 포함합니다:
<div
data-composition-id="data-chart"
data-composition-src="compositions/data-chart.html"
data-start="2"
data-duration="15"
data-track-index="1"
data-width="1920"
data-height="1080"
></div>
주요 속성:
data-composition-src— 블록 HTML 파일 경로data-composition-id— 블록의 내부 ID와 일치해야 함data-start— 블록이 호스트 타임라인에 나타나는 시간(초)data-duration— 블록 재생 시간data-width/data-height— 블록 캔버스 크기data-track-index— 레이어 순서(숫자가 높을수록 앞쪽)
자세한 내용은 wiring-blocks.md를 참조하세요.
컴포넌트 연결하기
컴포넌트는 스니펫입니다. 해당 HTML을 구성 마크업에, CSS를 스타일 블록에, JS(있는 경우)를 스크립트에 붙여넣습니다:
- 설치된 파일(예:
compositions/components/grain-overlay.html)을 읽습니다. - HTML 요소를 구성의
<div data-composition-id="...">에 복사합니다. <style>블록을 구성의 스타일에 복사합니다.<script>내용을 구성의 스크립트(타임라인 코드 앞)에 복사합니다.- 컴포넌트가 GSAP 타임라인 통합을 제공하는 경우(스니펫의 주석 블록 참조), 해당 호출을 타임라인에 추가합니다.
자세한 내용은 wiring-components.md를 참조하세요.
탐색
사용 가능한 항목을 찾아보세요:
# 레지스트리 매니페스트 읽기
curl -s https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry/registry.json
각 항목의 registry-item.json에는 다음이 포함됩니다: 이름, 유형, 제목, 설명, 태그, 크기(블록만), 지속 시간(블록만), 파일 목록.
유형 및 태그별 필터링에 대한 자세한 내용은 discovery.md를 참조하세요.
새 블록 또는 컴포넌트 기여하기
새로운 레지스트리 항목(캡션 스타일, VFX 블록, 전환, 하단 써드, 또는 재사용 가능한 컴포넌트)을 제작하여 업스트림 PR로 제출하려면(기존 항목 설치가 아님) contributing.md의 전체 아이디어→스캐폴드→빌드→검증→미리보기→배포 워크플로를 따르세요. 스타터 템플릿(캡션/VFX/컴포넌트/registry-item.json)은 templates.md에 있습니다.