AI 正在生成这个界面 transitions-ui-generation

什么时候适合用生成动画

当 AI 返回一张摘要卡片、一幅图表或一个组件时，结果通常会直接出现在页面上。想让这次展示更有过程感，可以先描出结果的点阵线框，再逐步展示真实界面。Transitions UI Generation 就是给已经渲染好的元素加上这段动画。

先分清两个时机：请求还没完成时，用常规加载提示；结果到达、元素完成排版后，再播放生成动画。它读取现有界面来绘制线框，动画本身不会生成内容，也不表示 AI 的真实计算进度。

适合把它用在一次性的结果展示或产品演示中。单个按钮、徽标、高度不足约 120px 的小元素，以及频繁切换的页面和列表行，都不适合反复播放这段效果。

点阵线框如何变成真实界面

运行时先测量目标元素的外轮廓、内部盒子、文字行和图标路径，再按这些位置绘制覆盖层。我们改动组件结构后，线框会根据新的布局重新测量，无需为每个组件手画一份动画。

阶段	画面变化
点阵场	点阵从中心展开，带下落的点和横向探测线
构建参考	显示参考线、四角手柄与尺寸标签
外轮廓	点沿着目标元素的轮廓逐步描出
内部结构	按文档顺序描绘盒子、文字行与图标路径
真实界面	扫描线自上而下揭示元素，线框退出

默认绘制时长是 2400ms，加上揭示阶段，整段约为 2.6 秒。运行时会临时接管目标元素的 opacity、clip-path 和 filter，结束后恢复原有内联值；不要在同一个元素上叠加另一套入场动画。

从安装到首次播放

下面先让 AI 编程工具接入技能，再用一个不依赖框架的小页面验证运行时。示例需要支持 ES module 的现代浏览器；安装技能需要能运行 npx 的 Node.js/npm 环境。上游技能没有声明最低 Node.js 版本，具体要求以安装工具提示为准。

1. 在终端安装技能。 在你的项目中运行以下命令，并按安装器提示选择使用的编程工具。若需要选择技能，确保包含 transitions-ui-generation。

   # 在终端运行：安装供 AI 编程工具读取的技能
   npx skills add Jakubantalik/transitions.dev

2. 向 AI 编程工具说明目标和触发时机。 下面这段是对话指令，发给 AI，不能当作终端命令执行。技能会先确认目标、模式和触发方式，再接入运行时。

   transitions generate
   给 ResultCard 加 skeleton 生成动画。
   等接口结果渲染完成、字体加载完毕后播放，每次新结果只播放一次。
   使用技能自带的 ui-generation.js 和 ui-generation.css，并全局引入 CSS。
   组件卸载时取消动画，保留减少动效支持。

   想先看两种模式，可以给 AI 发送 transitions generate preview；想加文字面板，发送 transitions generate texts，并说明目标元素周围有哪些留白。

3. 准备完整的浏览器示例。 从官方运行时目录取出 ui-generation.js 和 ui-generation.css，与下面的 index.html 放在同一目录。安装技能是让 AI 学会使用它；页面仍需要加载这两个文件。

   <!doctype html>
   <html lang="zh-CN">
     <meta charset="utf-8">
     <meta name="viewport" content="width=device-width, initial-scale=1">
     <title>生成动画示例</title>
     <link rel="stylesheet" href="./ui-generation.css">
     <style>
       body { margin: 0; padding: 80px 24px; background: #f6f6f6; }
       #result { max-width: 360px; margin: auto; padding: 32px;
         border-radius: 20px; background: white; font-family: sans-serif; }
     </style>
     <body>
       <article id="result" aria-label="摘要卡片">
         <h2>本周摘要</h2>
         <p>已整理 12 条笔记，发现 3 个待办事项。</p>
         <button type="button">查看结果</button>
       </article>
       <script type="module">
         import { generate } from "./ui-generation.js";
         // 等字体与布局稳定后再测量目标元素
         await document.fonts.ready;
         const element = document.querySelector("#result");
         const run = generate(element, { mode: "skeleton" });
         await run.finished;
         // 此时真实界面已完成揭示
         console.log("动画完成");
       </script>
     </body>
   </html>

4. 通过 HTTP 打开页面。 在示例目录运行下列命令，然后访问 http://localhost:8765。这个预览命令需要 Python 3；它只是本地静态服务器，并非运行时依赖。

   # 避免直接双击 HTML 导致 ES module 加载失败
   python3 -m http.server 8765

   你应当看到卡片结构先以点阵出现，随后展示真实卡片。实际项目中，把调用放到结果渲染之后；如果图片会改变元素尺寸，还要等待图片加载完成。

两种模式与常用参数

模式	显示内容	选择依据
skeleton	点阵线框与真实界面揭示	结果卡片、面板；不确定时先选它
skeleton-texts	线框、agent 日志、motion CSS 面板与步骤行	有留白的产品演示、发布页

文字面板会根据页面空位决定是否出现。密集布局中，它可能只保留步骤行，也可能不显示文字；多张卡片建议用 skeleton，通过 delay 错开播放。

参数	默认值	使用要点
mode	"skeleton"	两种模式任选其一
duration	2400	绘制时长，单位 ms；官方建议保持在 1600～3600
delay	0	开始前的延迟；多元素可按每项约 260ms 错开
steps	四条英文步骤	文字模式的步骤行；中文页面应传入中文文案
done	"Ready"	揭示时显示的结束文案
title	根据元素推导	motion CSS 面板标题，未指定时读取 aria-label 或标题元素
maxParts	60	最多描绘的部件数，优先保留较大部件
keys	5	获得参考线与尺寸标签的重点元素数

在前面示例中替换 generate 的调用，就能试中文步骤行：

const run = generate(element, {
  mode: "skeleton-texts",
  steps: ["规划布局", "绘制结构", "编写样式", "添加动效"],
  done: "摘要卡片已就绪",
  title: "摘要卡片",
});

这些文案是展示用的步骤，不能当作后台任务的进度。steps 和 done 也不等于整个文字面板的翻译接口；若产品要求所有面板文字都为中文，需继续核对运行时的固定文案。

generate 返回 { finished, cancel, element }。finished 是揭示完成的 Promise；cancel() 会立即停止并显示元素。对同一元素再次调用 generate 会取消旧动画。可以给某个子元素添加 data-t-generate-skip，让它不参与线框绘制。

常见问题排查

为什么文字线框和真实文字对不上？

通常是测量时字体或图片还没加载完。先等待 document.fonts.ready，再等待会影响布局的图片，最后调用 generate。

为什么完全没有动画？

先确认 JS 和 CSS 都加载成功，再检查目标元素是否存在、是否有可见尺寸。display: none 的元素无法测量，标签页和折叠面板应在展开后触发。开启系统减少动效时，只看到短淡入是正常行为。

为什么元素出现两套入场效果？

检查目标元素上是否还有自己的 opacity、clip-path 或 filter 动画。运行期间让生成运行时负责这些属性，去掉冲突的入场过渡。

为什么文字面板没出现？

skeleton-texts 需要旁边或下方有留白。先用单卡片宽松布局验证，再决定产品里是否需要文字模式；空间不足时改用 skeleton。

为什么滚动时线框偏离卡片？

覆盖层挂在页面上，目标元素在滚动容器里移动时，两者可能分离。尽量在元素进入视野后播放一次，避免动画期间让目标持续滚动。

为什么服务端报 window 或 DOM 相关错误？

浏览器运行时只能在客户端调用。SSR 框架中把接入放到客户端生命周期；需要隔离服务端导入时，在 effect 或挂载钩子内动态导入，再等待字体与布局稳定。

进阶使用与官方参考

演示页可以使用属性式 API，让元素进入视野时播放一次。它适合展示已存在的内容；异步结果仍应在结果渲染后显式调用 generate。

<section data-t-generate="skeleton" data-t-generate-delay="200">
  <h2>你的结果已准备好</h2>
  <p>在这里放入已渲染完成的卡片内容。</p>
</section>
<script type="module">
  import { auto } from "./ui-generation.js";
  // 字体就绪后，注册进入视野时的播放逻辑
  await document.fonts.ready;
  auto();
</script>

接入 React、Vue 或 Svelte 时，除了在客户端且布局稳定后启动，还要在组件卸载时调用 run.cancel()。若等待字体期间组件可能卸载，也要在等待结束后检查组件是否仍存在，避免对已移除的元素启动动画。

保留运行时的 prefers-reduced-motion: reduce 分支：它跳过线框绘制，用约 200ms 淡入显示元素，finished 仍会完成。覆盖层已设置 aria-hidden 且不接收指针事件；不要把业务请求或结果可用性绑定到动画完成回调。

• 官方技能说明：命令、API、框架接入与使用边界。
• 线框模式说明：各阶段的效果细节。
• 文字模式说明：日志、CSS 面板与布局规则。
• 官方演示文件：下载运行时目录并通过 HTTP 预览两种模式。