HyperFrames 行动型片尾 CTA 组件（cta-close）完全解读：逐词落地、留白排版与静止收束的动效原语-开发者社区

HyperFrames 行动型片尾 CTA 组件（cta-close）完全解读：逐词落地、留白排版与静止收束的动效原语

【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes

导读：cta-close是 HyperFrames 组件目录中用于"收束影片"的动作型结尾原语（action-only close）。它以大字标题逐词落地填满 70%～85% 画幅、胶囊 CTA 按钮以单次克制过冲弹出，随后整组版式完全静止直至画面切换。读完本文，你将掌握其变量契约、时间编排内核、挂载 HTML 契约，并能在自己的 composition 中复用它或理解其源码级实现细节。

一、组件定位：它解决影片"最后一帧"的什么问题

在 HyperFrames 里，一段视频由若干 composition 拼装而成，每一段 HTML 都是"会变成帧"的文档（见 compositions 概念）。影片接近尾声时，通常需要给观众一个明确的行动指引或品牌落点。HyperFrames 在 registry/components 目录下收录了一批*-close结尾组件，cta-close与logo-brand-close相邻而居，两者的分工在源码 README 中写得很清楚：

cta-close：动作型结尾（action），只有一个行动标题与一个按钮胶囊，"close films"；
logo-brand-close：身份型结尾（identity），wordmark + tagline + URL，"end on who made it"。

如果影片要以"让观众去做什么"收场，就用cta-close；如果要以"这是谁做的"收场，就用logo-brand-close。两者的区分同时记录在 logo-brand-close/README.md 中。

cta-close在 registry-item.json 中把这种定位写成机器可读的元数据：

family: "ui-props"、jobs: ["ask"]、tags含cta、end-card、close、ask；
profile: "holdable"——表征它是一种"入点后可长时间静止保持"的原语；
syncPoints声明了close-settled同步点（位于入点相位末端 1.32s），供编排系统对齐其他素材。

二、视觉规则与文案策略

组件源码注释 cta-close.html（第 1~27 行）与 README 一起定义了它的视觉语法：

行动标题（action line）：display 级字号，2～4 个英文单词的收束动作。通过"字符感知的字号拟合"把整行宽度填到画幅的70%～85%，上下留出"真实的呼吸感"，短行则以高度上限封顶，避免双词结尾显得单薄或顶到画框边缘。
按钮胶囊（button capsule）：位于标题下方，是整组里唯一的彩色元素，以单次"克制过冲"（restrained overshoot）弹出。
单调配色（monotone）："墨色文字压在地面上"（ink on ground），accent 色只出现在胶囊上。
静止收束（dead-still hold）：编排完成后的整个 HOLD 阶段绝对静止，不漂移、不脉动，直到画面被切换（cut）。

这套"行动 + 静止"的设计哲学正是它作为影片收束原语的存在意义——观众读完诉求后，画面已不再有任何干扰动作，等待下一个场景接管。

三、变量契约与默认值

组件的可调输入全部集中在 HTML<html>标签的data-composition-variables声明里，也同步镜像到 README 的变量表和 registry-item.json 的variables数组。每个变量都有默认值，因此组件"不做任何配置即可工作"：

id	类型	默认值	说明（含源码级补充）
`action_line`	string	`Make it happen`	2～4 个单词的收束行动标题；字符感知拟合把整行宽度定到画幅 70%～85%，短行以高度上限（`30cqh`）封顶
`button_label`	string	`Start now`	胶囊内文案，正文 face 呈现，标签同样参与字符感知自动适配字号
`accent`	enum	`green`	胶囊配色：`green`走`--brand`、`blue`走`--accent`、`violet`走`--accent-2`（带逐一的兜底色值）
`exit`	enum	`none`	出点行为：`none`保持到画面切换；`fade`/`up`让整组版式在最后 0.45s 内离场

从 cta-close.html 的声明可以看到完整 schema 字段：除id/type/default外，还带role（content/style/timing）和面向人/Agent 的label、description。这套结构是 HyperFrames 变量体系的标准形态——variables 概念文档指出，label与description的意义在于让编辑 Agent "不需要打开 HTML 就能正确填写插槽"。

变量在脚本内的安全取值逻辑

源码 cta-close.html 展示了组件如何容错地消费变量：

var vars = window.__hyperframes && window.__hyperframes.getVariables ? window.__hyperframes.getVariables() : {}; var actionText = vars.action_line == null ? "Make it happen" : String(vars.action_line).trim().replace(/\s+/g, " "); var accentColors = { green: "var(--brand, #71f5a7)", blue: "var(--accent, #61a8ff)", violet: "var(--accent-2, #c5a3ff)", }; var accent = Object.prototype.hasOwnProperty.call(accentColors, vars.accent) ? vars.accent : "green"; var exit = vars.exit === "fade" || vars.exit === "up" ? vars.exit : "none";

要点有三：

通过window.__hyperframes.getVariables()读取，该 API 会把挂载宿主传来的值逐层叠加在声明默认值之上（见 variables 概念文档）；
文本类变量做.trim()与连续空白归一（\s+→ 单个空格），避免多余空白破坏排版与宽度估算；
enum 类变量走白名单校验：非法值回落到安全默认，exit只有精确命中fade/up才开启出点逻辑，保证默认情况下组件一定以静止收束。

四、时间编排（Choreography / Envelope）

README 的 Choreography 三步骤与源码时间线一一对应，全部以秒为单位、不受宿主时间缩放影响（"timeline is never time-scaled"，短于固定相位的时长按比例压缩入/出相位，见 cta-close.html 注释）。

组件默认以3.5s 时长创制（3.5s authored）：

行动标题逐词落地（约 0.06s 起）：每个词被切分成独立<span class="cc-w">，以rise + fade（opacity:0, y:8cqh→ 归位）在power3.out缓动下**以 0.10s 错峰（stagger）**依次进入。切词逻辑保留词间自然空格（cta-close.htmlL162-L174），使 display 级 tracking 不会被挤压。
胶囊按钮单次克制弹出（0.72s 起）：从scale: 0.85、y: 3cqh用back.out(1.5)弹到scale: 1——恰一次过冲；同时 0.22s 内做透明度渐入（power2.out）。1.32s 时整组编排完成。
静止保持到结尾：时间线通过一个铺满全长的空tl.set({}, {}, duration)（见 L242）"钉住"HOLD 相位，保证在保持期内任意 seek 都落在同一静态姿态上——这正是"确定性渲染、可寻址"的关键实现手段（可对照 determinism 概念）。

入点相关相位常量在 cta-close.html 中可查：IN_BASE = 1.32、单词出现WORDS_AT = 0.06*scale、词动画0.62*scale、词错峰0.1*scale、按钮出现BUTTON_AT = 0.72*scale、按钮动画0.6*scale。缩放系数envelopeScale = min(1, duration / (IN_BASE + OUT_BASE))，保证较短的挂载时长里相位整体等比压缩而不越界。

出点（exit）分支位于 L246-L254：fade让整组opacity归零，up额外叠加y: -5cqh上移，均用power2.in在最后OUT=0.45s完成。默认none时OUT_BASE = 0，画面一直静止到切换。

五、字符感知的字号拟合：确定性优先的布局

排版系统与"宽度 70%～85%"是如何实现的？这是本组件最有技术含量的部分。源码注释（L178-L194）说明：字号拟和在模板布局之前就确定性地完成——它不依赖运行时测量文本宽度，而是用字符数与估算的每字符宽度直接算出字号，再把结果写为 CSS 变量：

var actionCharacters = Math.max(1, Array.from(actionText).length); var actionSize = Math.min(24, 76 / (actionCharacters * 0.47)); var buttonCharacters = Math.max(1, Array.from(buttonText).length); var buttonSize = Math.min(3.5, 50 / (buttonCharacters * 0.5)); root.style.setProperty("--cc-action-size", "min(" + actionSize.toFixed(3) + "cqw, 30cqh)"); root.style.setProperty("--cc-button-size", "min(" + buttonSize.toFixed(3) + "cqw, 6cqh)");

76 / (字符数 × 0.47)：以0.47em作为常见 display 字体的平均字宽估计，把整行推到画幅宽度的 70%～85% 区间（分子 76 ≈ 0.76 画幅 × 100/0.47 的合并表达）；
Math.min(24, ...)限制字号上限，min(…, 30cqh)再以高度兜底——双词短行因此保持"纪念碑感"而不触碰边缘；
按钮字号同理（50/(n×0.5)封顶3.5cqw，高度限6cqh），保证胶囊内文案自动适配且始终醒目。

布局层面用容器查询单位cqw/cqh（容器为container-type: size的#root），文本元素white-space: nowrap单行呈现。单位尺寸在样式表（L86-L114）有兜底：--cc-action-size缺省min(10.4cqw, 30cqh)、--cc-button-size缺省min(3.4cqw, 6cqh)。由于字号只依赖字符数，相同文案在任何分辨率/任意宿主盒子上都会产生相同的相对排版结果，这也是它可安全用于确定性渲染的原因。

六、挂载（Mount）契约：把组件放进你的 composition

安装到项目

组件目录页（docs/catalog/components/cta-close.mdx）给出安装方式：

npx hyperframes add cta-close

该命令只写一个文件：compositions/components/cta-close.html。

在宿主 composition 中引用

README 提供的标准挂载片段如下（一个"弹性根"，宿主 clip 给它什么盒子它就填满什么盒子）：

<div class="clip" ><div id="cta-close-mount" class="mount-stage clip" contenteditable="false">【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考