mirror of
https://github.com/aculix/huashu-design.git
synced 2026-10-27 07:15:54 +00:00
launch huashu-design v1.0: 9 demos + marketing-first README
- 新增 9 个能力 demo（workflow + capability），每个 MP4 + GIF + 60fps - README 重写：营销 hook 开头 · 功能优先结构 · 自然嵌入 GIF - 修复 render-video.js Google Fonts networkidle 超时 - 修复 c1-ios-prototype 刘海/Home Indicator 背景色 - 补充 references/editable-pptx.md 和 scripts/export_deck_stage_pdf.mjs Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
alchainandClaude Opus 4.7 committed
1 parent
f3692aac10
commit
b127f8baa3
24 files changed
+8206
-281
No files matched your search
@@ -201,35 +201,164 @@
|
||||
|
||||
**反例**：底部画 `00:42 ──── PROJECT NAME`、画面右下角画"CH 03 / 06"章节计数、画面边缘画版本号"v0.3.1"——都是伪 chrome filler。
|
||||
|
||||
## 12. 录屏前置空白 —— 用 `window.__ready` 同步动画 t=0
|
||||
## 12. 录屏前置空白 + 录屏起点偏移 —— `__ready` × tick × lastTick 三联陷阱
|
||||
|
||||
**踩的坑**：60 秒动画导出 MP4，前 2-3 秒是空白页面。`ffmpeg --trim=0.3` 剪不掉。
|
||||
**踩的坑（A · 前置空白）**：60 秒动画导出 MP4，前 2-3 秒是空白页面。`ffmpeg --trim=0.3` 剪不掉。
|
||||
|
||||
**根因**：Playwright `recordVideo` 从 `newContext()` 那一刻就开始写 WebM。但此时 Babel Standalone 还在编译 inline JSX、React 还没 mount、`document.fonts.ready.then(root.render)` 还没触发。`page.goto(url, { waitUntil: 'networkidle' })` 只等网络空闲，检测不到 JS 执行阶段——所以 WebM 前 1.5-3s 是空白页。
|
||||
**踩的坑（B · 起点偏移，2026-04-20 真实事故）**：导出 24 秒视频，用户观感「视频 19 秒才开始播第一帧」。实际上动画从 t=5 开始录，录到 t=24 后 loop 回 t=0，再录 5 秒到 end——所以视频最后 5 秒才是动画真正的开头。
|
||||
|
||||
**根因**（两个坑共享一个根因）：
|
||||
|
||||
Playwright `recordVideo` 从 `newContext()` 那一刻就开始写 WebM，此时 Babel/React/字体加载共耗时 L 秒（2-6s）。录屏脚本等 `window.__ready = true` 作为「动画从这里开始」的锚点——它和动画 `time = 0` 必须严格 pair。有两种常见错法：
|
||||
|
||||
| 错法 | 症状 |
|
||||
|------|------|
|
||||
| `__ready` 在 `useEffect` 或同步 setup 阶段设（在 tick 第一帧之前） | 录屏脚本以为动画开始了，实际 WebM 还在录空白页 → **前置空白** |
|
||||
| tick 的 `lastTick = performance.now()` 在**脚本顶层**初始化 | 字体加载 L 秒被算进首帧 `dt`，`time` 瞬间跳到 L → 录屏全程滞后 L 秒 → **起点偏移** |
|
||||
|
||||
**✅ 正确的完整 starter tick 模板**（手写动画必须用这个骨架）：
|
||||
|
||||
```js
|
||||
// ━━━━━━ state ━━━━━━
|
||||
let time = 0;
|
||||
let playing = false; // ❗ 默认不播，等字体 ready 再启动
|
||||
let lastTick = null; // ❗ sentinel——tick 首帧时 dt 强制为 0（别用 performance.now()）
|
||||
const fired = new Set();
|
||||
|
||||
// ━━━━━━ tick ━━━━━━
|
||||
function tick(now) {
|
||||
if (lastTick === null) {
|
||||
lastTick = now;
|
||||
window.__ready = true; // ✅ pair：「录屏起点」与「动画 t=0」同一帧
|
||||
render(0); // 再渲一次确保 DOM 就绪（此时字体已 ready）
|
||||
requestAnimationFrame(tick);
|
||||
return;
|
||||
}
|
||||
const dt = (now - lastTick) / 1000; // 首帧之后 dt 才开始推进
|
||||
lastTick = now;
|
||||
|
||||
if (playing) {
|
||||
let t = time + dt;
|
||||
if (t >= DURATION) {
|
||||
t = window.__recording ? DURATION - 0.001 : 0; // 录制时不 loop，留 0.001s 保留末帧
|
||||
if (!window.__recording) fired.clear();
|
||||
}
|
||||
time = t;
|
||||
render(time);
|
||||
}
|
||||
requestAnimationFrame(tick);
|
||||
}
|
||||
|
||||
// ━━━━━━ boot ━━━━━━
|
||||
// 不要在顶层立即 rAF——等字体加载完才启动
|
||||
document.fonts.ready.then(() => {
|
||||
render(0); // 先把初始画面画出来（字体已就绪）
|
||||
playing = true;
|
||||
requestAnimationFrame(tick); // 首次 tick 会 pair __ready + t=0
|
||||
});
|
||||
|
||||
// ━━━━━━ seek 接口（供 render-video 防御性矫正用）━━━━━━
|
||||
window.__seek = (t) => { fired.clear(); time = t; lastTick = null; render(t); };
|
||||
```
|
||||
|
||||
**为什么这个模板对**：
|
||||
|
||||
| 环节 | 为什么必须这样 |
|
||||
|------|-------------|
|
||||
| `lastTick = null` + 首帧 `return` | 避免「脚本加载到 tick 首次执行」的 L 秒被算进动画时间 |
|
||||
| `playing = false` 默认 | 字体加载期间 `tick` 即使运行也不推进 time，避免渲染错位 |
|
||||
| `__ready` 在 tick 首帧设 | 录屏脚本此刻开始计时，对应的画面是动画真正的 t=0 |
|
||||
| `document.fonts.ready.then(...)` 里才启动 tick | 规避字体 fallback 宽度测量、避免首帧字体跳变 |
|
||||
| `window.__seek` 存在 | 让 `render-video.js` 可以主动矫正——第二道防线 |
|
||||
|
||||
**录屏脚本端的对应防御**：
|
||||
1. `addInitScript` 注入 `window.__recording = true`（先于 page goto）
|
||||
2. `waitForFunction(() => window.__ready === true)`，记录此刻偏移作为 ffmpeg trim
|
||||
3. **额外**：`__ready` 之后主动 `page.evaluate(() => window.__seek && window.__seek(0))`，把 HTML 可能的 time 偏差强制归零——这是第二道防线，对付不严格遵守 starter 模板的 HTML
|
||||
|
||||
**验证方法**：导出 MP4 后
|
||||
```bash
|
||||
ffmpeg -i video.mp4 -ss 0 -vframes 1 frame-0.png
|
||||
ffmpeg -i video.mp4 -ss $DURATION-0.1 -vframes 1 frame-end.png
|
||||
```
|
||||
首帧必须是动画 t=0 的初始状态（不是中段，不是黑），末帧必须是动画终态（不是第二轮 loop 的某个时刻）。
|
||||
|
||||
**参考实现**：`assets/animations.jsx` 的 Stage 组件、`scripts/render-video.js` 都已按此协议实现。手写 HTML 必须套 starter tick 模板——每一行都是防过具体 bug。
|
||||
|
||||
## 13. 录制时禁止 loop —— `window.__recording` 信号
|
||||
|
||||
**踩的坑**：动画 Stage 默认 `loop=true`（浏览器里方便看效果）。`render-video.js` 录完 duration 秒还多等 300ms 缓冲才停止，这 300ms 让 Stage 进入下一循环。ffmpeg `-t DURATION` 截取时，最后 0.5-1s 落入下一循环——视频结尾突然回到第一帧（Scene 1），观众以为视频出 bug。
|
||||
|
||||
**根因**：录制脚本和 HTML 之间没有"我在录制"的握手协议。HTML 不知道自己被录，依然按浏览器交互场景循环。
|
||||
|
||||
**规则**：
|
||||
|
||||
1. **动画代码**在 tick 第一帧发 `window.__ready = true`，和动画 t=0 同步：
|
||||
1. **录制脚本**：在 `addInitScript` 里注入 `window.__recording = true`（先于 page goto）：
|
||||
```js
|
||||
function tick(now) {
|
||||
if (last === null) {
|
||||
last = now;
|
||||
window.__ready = true; // 必须在这里，不是 useEffect
|
||||
}
|
||||
// ... 动画推进
|
||||
}
|
||||
await recordCtx.addInitScript(() => { window.__recording = true; });
|
||||
```
|
||||
为什么同步？如果 `__ready` 在 tick 之前设（如 `useEffect` 或 rAF 排队），触发时 WebM 光标还在空白页；如果在 tick 之后设（rAF 嵌套），则动画已经跑了几帧被 trim 掉。**pair 起来**才是对的。
|
||||
|
||||
2. **录屏脚本**`page.goto` 之后 `waitForFunction(() => window.__ready === true)`，记录此时相对 WebM 起点的秒数作为 ffmpeg trim 偏移。完全不靠猜。
|
||||
2. **Stage 组件**：识别这个信号，强制 loop=false：
|
||||
```js
|
||||
const effectiveLoop = (typeof window !== 'undefined' && window.__recording) ? false : loop;
|
||||
// ...
|
||||
if (next >= duration) return effectiveLoop ? 0 : duration - 0.001;
|
||||
// ↑ 留 0.001 防止 Sprite end=duration 被关掉
|
||||
```
|
||||
|
||||
3. **字体等待**放在 tick 启动条件里：`document.fonts.ready.then(() => rAF(tick))`。这样 tick 第一帧就是字体已就绪的画面——`__ready` 信号 = WebM 捕到的第一个"用户会看到"的动画帧。
|
||||
3. **结尾 Sprite 的 fadeOut**：录制场景下应设 `fadeOut={0}`，否则视频末尾会渐变到透明/暗色——用户期望停在清晰的最后一帧，不是淡出。手写 HTML 时建议结尾 Sprite 都用 `fadeOut={0}`。
|
||||
|
||||
**不这么做的代价**：固定 trim 靠猜。机器快慢、字体缓存状态、网速每次不同——某台机器上的 3s trim 换到另一台可能不够或截掉开头。动态测量从根本解决。
|
||||
**参考实现**：`assets/animations.jsx` 的 Stage / `scripts/render-video.js` 都已内置握手。手写 Stage 必须实现 `__recording` 检测——否则录制必踩这个坑。
|
||||
|
||||
**参考实现**：`assets/animations.jsx` 的 Stage 组件已内置。`scripts/render-video.js` 已内置 auto-trim 逻辑。非 animations.jsx 的手写 HTML，自行在 tick/渲染循环的第一帧设信号。
|
||||
**验证**：导出 MP4 后 `ffmpeg -ss 19.8 -i video.mp4 -frames:v 1 end.png`，检查倒数 0.2 秒是否还是预期最后一帧，没有突然切换到另一个 scene。
|
||||
|
||||
**验证方法**：导出后 `ffmpeg -i video.mp4 -ss 0 -vframes 1 frame-0.png`，检查第一帧是动画应有的初始状态（不是动画中段、不是黑屏）。
|
||||
## 14. 60fps 视频默认用帧复制 —— minterpolate 兼容性差
|
||||
|
||||
**踩的坑**：`convert-formats.sh` 用 `minterpolate=fps=60:mi_mode=mci...` 生成的 60fps MP4，在 macOS QuickTime / Safari 部分版本下无法打开（一片黑或直接拒打）。VLC / Chrome 能打开。
|
||||
|
||||
**根因**：minterpolate 输出的 H.264 elementary stream 包含某些播放器解析有问题的 SEI / SPS 字段。
|
||||
|
||||
**规则**：
|
||||
|
||||
- 默认 60fps 用简单 `fps=60` filter（帧复制），兼容性广（QuickTime/Safari/Chrome/VLC 都能开）
|
||||
- 高质量插帧用 `--minterpolate` flag 显式启用——但**必须本地测过**目标播放器再交付
|
||||
- 60fps 标签价值是**上传平台的算法识别**（Bilibili / YouTube 上 60fps 标记会优先推流），实际感知流畅度对 CSS 动画来说提升微弱
|
||||
- 加 `-profile:v high -level 4.0` 提升 H.264 通用兼容性
|
||||
|
||||
**`convert-formats.sh` 已默认改成兼容模式**。如果你需要插帧高质量，加 `--minterpolate` flag：
|
||||
```bash
|
||||
bash convert-formats.sh input.mp4 --minterpolate
|
||||
```
|
||||
|
||||
## 15. `file://` + 外部 `.jsx` 的 CORS 陷阱 —— 单文件交付必须内联引擎
|
||||
|
||||
**踩的坑**：动画 HTML 里用 `<script type="text/babel" src="animations.jsx"></script>` 外部加载引擎。本机双击打开（`file://` 协议）→ Babel Standalone 走 XHR 拉 `.jsx` → Chrome 报 `Cross origin requests are only supported for protocol schemes: http, https, chrome, chrome-extension...` → 整页黑屏，不报 `pageerror` 只报 console error，很容易当"动画没触发"误诊。
|
||||
|
||||
启 HTTP server 也未必救得了——本机有全局代理时 `localhost` 也会走代理，返回 502 / 连接失败。
|
||||
|
||||
**规则**：
|
||||
|
||||
- **单文件交付（双击打开即用的 HTML）** → `animations.jsx` 必须**内联**到 `<script type="text/babel">...</script>` 标签内，不要用 `src="animations.jsx"`
|
||||
- **多文件项目（起 HTTP server 演示）** → 可以外部加载，但交付时明确写清 `python3 -m http.server 8000` 命令
|
||||
- 判断标准：交付给用户的是"HTML 文件"还是"带 server 的项目目录"？前者用内联
|
||||
- Stage 组件 / animations.jsx 经常 200+ 行——贴进 HTML `<script>` 块完全可接受，别怕体积
|
||||
|
||||
**最小验证**：双击你生成的 HTML，**不要**通过任何 server 打开。如果 Stage 正常显示动画首帧，才算通过。
|
||||
|
||||
## 16. 跨 scene 反色上下文 —— 画面内元素不要硬编码颜色
|
||||
|
||||
**踩的坑**：做多场景动画时，`ChapterLabel` / `SceneNumber` / `Watermark` 等**跨 scene 都出现**的元素，在组件里写死 `color: '#1A1A1A'`（深色文字）。前 4 个 scene 浅底 OK，到第 5 个黑底 scene 时"05"和水印直接消失——不报错、不触发任何检查、关键信息隐形。
|
||||
|
||||
**规则**：
|
||||
|
||||
- **跨多 scene 复用的画面内元素**（chapter 标签 / scene 编号 / 时间码 / 水印 / 版权条）**禁止硬编码颜色值**
|
||||
- 改用三种方式之一：
|
||||
1. **`currentColor` 继承**：元素只写 `color: currentColor`，父 scene 容器设 `color: 计算值`
|
||||
2. **invert prop**：组件接受 `<ChapterLabel invert />` 手动切换深浅
|
||||
3. **基于底色自动计算**：`color: contrast-color(var(--scene-bg))`（CSS 4 新 API，或 JS 判断）
|
||||
- 交付前用 Playwright 抽**每个 scene 的代表帧**，人眼过一遍"跨 scene 元素"是否都可见
|
||||
|
||||
这条坑的隐蔽性在于——**没有 bug 报警**。只有人眼或 OCR 能发现。
|
||||
|
||||
## 快速自查清单（开工前 5 秒）
|
||||
|
||||
@@ -242,4 +371,10 @@
|
||||
- [ ] 第 0 帧是完整初始状态，不是空白？
|
||||
- [ ] 画面内没有「伪 chrome」装饰（进度条/时间码/底部署名条与 Stage scrubber 撞车）？
|
||||
- [ ] 动画 tick 第一帧同步设 `window.__ready = true`？（用 animations.jsx 自带；手写 HTML 自己加）
|
||||
- [ ] 导出后抽第 0 帧验证是动画初始状态？
|
||||
- [ ] Stage 检测 `window.__recording` 强制 loop=false？（手写 HTML 必加）
|
||||
- [ ] 结尾 Sprite 的 `fadeOut` 设为 0（视频末尾停清晰帧）？
|
||||
- [ ] 60fps MP4 默认用帧复制模式（兼容性），高质量插帧才加 `--minterpolate`？
|
||||
- [ ] 导出后抽第 0 帧 + 末帧验证是动画初始/最终状态？
|
||||
- [ ] 涉及具体品牌（Stripe/Anthropic/Lovart/...）：走完了「品牌资产协议」（SKILL.md §1.a 五步）？有没有写 `brand-spec.md`？
|
||||
- [ ] 单文件交付的 HTML：`animations.jsx` 是内联的，不是 `src="..."`？（file:// 下 external .jsx 会 CORS 黑屏）
|
||||
- [ ] 跨 scene 出现的元素（chapter 标签/水印/scene 编号）没有硬编码颜色？在每个 scene 底色下都可见？
|
||||
@@ -0,0 +1,243 @@
|
||||
# 可编辑 PPTX 导出：HTML 硬约束 + 尺寸决策 + 常见错误
|
||||
|
||||
本文档讲的是**用 `scripts/html2pptx.js` + `pptxgenjs` 把 HTML 逐元素翻译成真·可编辑 PowerPoint 文本框**的路径。和 `export_deck_pptx.mjs --mode image`（截图铺底、文字变图片、不可编辑）是两回事。
|
||||
|
||||
> **核心前提**：要走这条路，HTML 必须从第一行就按下面 4 条约束写。**不是写完再转**——事后补救会触发 2-3 小时返工（2026-04-20 期权私董会项目实测踩坑）。
|
||||
|
||||
---
|
||||
|
||||
## 画布尺寸：用 960×540pt（LAYOUT_WIDE）
|
||||
|
||||
PPTX 单位是 **inch**（物理尺寸），不是 px。决策原则：body 的 computedStyle 尺寸要**匹配 presentation layout 的 inch 尺寸**（±0.1"，由 `html2pptx.js` 的 `validateDimensions` 强制检查）。
|
||||
|
||||
### 3 个候选尺寸对比
|
||||
|
||||
| HTML body | 物理尺寸 | 对应 PPT layout | 何时选 |
|
||||
|---|---|---|---|
|
||||
| **`960pt × 540pt`** | **13.333″ × 7.5″** | **pptxgenjs `LAYOUT_WIDE`** | ✅ **默认推荐**（现代 PowerPoint 16:9 标配） |
|
||||
| `720pt × 405pt` | 10″ × 5.625″ | 自定义 | 仅当用户指定「老版 PowerPoint Widescreen」模板时 |
|
||||
| `1920px × 1080px` | 20″ × 11.25″ | 自定义 | ❌ 非标尺寸，投影后字体显得异常小 |
|
||||
|
||||
**别把 HTML 尺寸当分辨率想。** PPTX 是矢量文档，body 尺寸决定的是**物理尺寸**不是清晰度。超大 body（20″×11.25″）不会让文字更清晰——只会让字号 pt 相对画布变小，投影/打印时反而更难看。
|
||||
|
||||
### body 写法三选一（等价）
|
||||
|
||||
```css
|
||||
body { width: 960pt; height: 540pt; } /* 最清晰，推荐 */
|
||||
body { width: 1280px; height: 720px; } /* 等价，px 习惯 */
|
||||
body { width: 13.333in; height: 7.5in; } /* 等价，英寸直觉 */
|
||||
```
|
||||
|
||||
配套的 pptxgenjs 代码：
|
||||
|
||||
```js
|
||||
const pptx = new pptxgen();
|
||||
pptx.layout = 'LAYOUT_WIDE'; // 13.333 × 7.5 inch, 无需自定义
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4 条硬约束（违反会直接报错）
|
||||
|
||||
`html2pptx.js` 把 HTML 的 DOM 逐元素翻译成 PowerPoint 对象。PowerPoint 的格式约束投射到 HTML 上 = 下面 4 条规则。
|
||||
|
||||
### 规则 1：DIV 里不能直接写文字 — 必须用 `<p>` 或 `<h1>`-`<h6>` 包裹
|
||||
|
||||
```html
|
||||
<!-- ❌ 错误：文字直接在 div 里 -->
|
||||
<div class="title">Q3营收增长23%</div>
|
||||
|
||||
<!-- ✅ 正确：文字在 <p> 或 <h1>-<h6> 里 -->
|
||||
<div class="title"><h1>Q3营收增长23%</h1></div>
|
||||
<div class="body"><p>新用户是主要驱动力</p></div>
|
||||
```
|
||||
|
||||
**为什么**：PowerPoint 文本必须存在 text frame 里，text frame 对应 HTML 的段落级元素（p/h*/li）。裸 `<div>` 在 PPTX 里没有对应的文本容器。
|
||||
|
||||
**也不能用 `<span>` 承载主文字**——span 是行内元素，没法独立对齐成文本框。span 只能**夹在 p/h\* 里**做局部样式（加粗、换色）。
|
||||
|
||||
### 规则 2：不支持 CSS 渐变 — 只能用纯色
|
||||
|
||||
```css
|
||||
/* ❌ 错误 */
|
||||
background: linear-gradient(to right, #FF6B6B, #4ECDC4);
|
||||
|
||||
/* ✅ 正确：纯色 */
|
||||
background: #FF6B6B;
|
||||
|
||||
/* ✅ 如果必须多色条纹，用 flex 子元素各自纯色 */
|
||||
.stripe-bar { display: flex; }
|
||||
.stripe-bar div { flex: 1; }
|
||||
.red { background: #FF6B6B; }
|
||||
.teal { background: #4ECDC4; }
|
||||
```
|
||||
|
||||
**为什么**：PowerPoint 的 shape fill 只支持 solid/gradient-fill 两种，但 pptxgenjs 的 `fill: { color: ... }` 只映射 solid。渐变走 PowerPoint 原生 gradient 需要另写结构，目前工具链不支持。
|
||||
|
||||
### 规则 3：背景/边框/阴影只能在 DIV 上，不能在文字标签上
|
||||
|
||||
```html
|
||||
<!-- ❌ 错误：<p> 有背景色 -->
|
||||
<p style="background: #FFD700; border-radius: 4px;">重点内容</p>
|
||||
|
||||
<!-- ✅ 正确：外层 div 承载背景/边框，<p> 只负责文字 -->
|
||||
<div style="background: #FFD700; border-radius: 4px; padding: 8pt 12pt;">
|
||||
<p>重点内容</p>
|
||||
</div>
|
||||
```
|
||||
|
||||
**为什么**：PowerPoint 里 shape（方块/圆角矩形）和 text frame 是两个对象。HTML 的 `<p>` 只翻译成 text frame，背景/边框/阴影属于 shape——必须在**包裹 text 的 div** 上写。
|
||||
|
||||
### 规则 4：DIV 不能用 `background-image` — 用 `<img>` 标签
|
||||
|
||||
```html
|
||||
<!-- ❌ 错误 -->
|
||||
<div style="background-image: url('chart.png')"></div>
|
||||
|
||||
<!-- ✅ 正确 -->
|
||||
<img src="chart.png" style="position: absolute; left: 50%; top: 20%; width: 300pt; height: 200pt;" />
|
||||
```
|
||||
|
||||
**为什么**：`html2pptx.js` 只从 `<img>` 元素提取图片路径，不解析 CSS 的 `background-image` URL。
|
||||
|
||||
---
|
||||
|
||||
## Path A HTML 模板骨架
|
||||
|
||||
每张 slide 一个独立 HTML 文件，彼此作用域隔离（避开单文件 deck 的 CSS 污染）。
|
||||
|
||||
```html
|
||||
<!DOCTYPE html>
|
||||
<html lang="zh-CN">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<style>
|
||||
* { margin: 0; padding: 0; box-sizing: border-box; }
|
||||
body {
|
||||
width: 960pt; height: 540pt; /* ⚠️ 匹配 LAYOUT_WIDE */
|
||||
font-family: system-ui, -apple-system, "PingFang SC", sans-serif;
|
||||
background: #FEFEF9; /* 纯色，不能渐变 */
|
||||
overflow: hidden;
|
||||
}
|
||||
/* DIV 负责布局/背景/边框 */
|
||||
.card {
|
||||
position: absolute;
|
||||
background: #1A4A8A; /* 背景在 DIV 上 */
|
||||
border-radius: 4pt;
|
||||
padding: 12pt 16pt;
|
||||
}
|
||||
/* 文字标签只负责字体样式，不加背景/边框 */
|
||||
.card h2 { font-size: 24pt; color: #FFFFFF; font-weight: 700; }
|
||||
.card p { font-size: 14pt; color: rgba(255,255,255,0.85); }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
|
||||
<!-- 标题区：外层 div 定位，内层文字标签 -->
|
||||
<div style="position: absolute; top: 40pt; left: 60pt; right: 60pt;">
|
||||
<h1 style="font-size: 36pt; color: #1A1A1A; font-weight: 700;">标题用断言句，不是主题词</h1>
|
||||
<p style="font-size: 16pt; color: #555555; margin-top: 10pt;">副标题补充说明</p>
|
||||
</div>
|
||||
|
||||
<!-- 内容卡片：div 负责背景，h2/p 负责文字 -->
|
||||
<div class="card" style="top: 130pt; left: 60pt; width: 240pt; height: 160pt;">
|
||||
<h2>要点一</h2>
|
||||
<p>简短说明文字</p>
|
||||
</div>
|
||||
|
||||
<!-- 列表：使用 ul/li，不用手动 • 符号 -->
|
||||
<div style="position: absolute; top: 320pt; left: 60pt; width: 540pt;">
|
||||
<ul style="font-size: 16pt; color: #1A1A1A; padding-left: 24pt; list-style: disc;">
|
||||
<li>第一条要点</li>
|
||||
<li>第二条要点</li>
|
||||
<li>第三条要点</li>
|
||||
</ul>
|
||||
</div>
|
||||
|
||||
<!-- 插图：用 <img> 标签，不用 background-image -->
|
||||
<img src="illustration.png" style="position: absolute; right: 60pt; top: 110pt; width: 320pt; height: 240pt;" />
|
||||
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 常见错误速查
|
||||
|
||||
| 错误信息 | 原因 | 修复方法 |
|
||||
|---------|------|---------|
|
||||
| `DIV element contains unwrapped text "XXX"` | div 里有裸文字 | 把文字包进 `<p>` 或 `<h1>`-`<h6>` |
|
||||
| `CSS gradients are not supported` | 用了 linear/radial-gradient | 改为纯色，或用 flex 子元素分段 |
|
||||
| `Text element <p> has background` | `<p>` 标签加了背景色 | 外套 `<div>` 承载背景，`<p>` 只写文字 |
|
||||
| `Background images on DIV elements are not supported` | div 用了 background-image | 改为 `<img>` 标签 |
|
||||
| `HTML content overflows body by Xpt vertically` | 内容超出 540pt | 减少内容或缩小字号，或 `overflow: hidden` 截断 |
|
||||
| `HTML dimensions don't match presentation layout` | body 尺寸和 pres layout 对不上 | body 用 `960pt × 540pt` 配 `LAYOUT_WIDE`；或 defineLayout 自定义尺寸 |
|
||||
| `Text box "XXX" ends too close to bottom edge` | 大字号 `<p>` 距离 body 底边 < 0.5 inch | 往上挪，留足下边距；PPT 底部本身就会被遮住一部分 |
|
||||
|
||||
---
|
||||
|
||||
## 基本工作流（3 步出 PPTX）
|
||||
|
||||
### Step 1：按约束写每页独立 HTML
|
||||
|
||||
```
|
||||
我的Deck/
|
||||
├── slides/
|
||||
│ ├── 01-cover.html # 每个文件都是完整 960×540pt HTML
|
||||
│ ├── 02-agenda.html
|
||||
│ └── ...
|
||||
└── illustration/ # 所有 <img> 引用的图片
|
||||
├── chart1.png
|
||||
└── ...
|
||||
```
|
||||
|
||||
### Step 2：写 build.js 调用 `html2pptx.js`
|
||||
|
||||
```js
|
||||
const pptxgen = require('pptxgenjs');
|
||||
const html2pptx = require('../scripts/html2pptx.js'); // 本 skill 脚本
|
||||
|
||||
(async () => {
|
||||
const pres = new pptxgen();
|
||||
pres.layout = 'LAYOUT_WIDE'; // 13.333 × 7.5 inch，匹配 HTML 的 960×540pt
|
||||
|
||||
const slides = ['01-cover.html', '02-agenda.html', '03-content.html'];
|
||||
for (const file of slides) {
|
||||
await html2pptx(`./slides/${file}`, pres);
|
||||
}
|
||||
|
||||
await pres.writeFile({ fileName: 'deck.pptx' });
|
||||
})();
|
||||
```
|
||||
|
||||
### Step 3：打开检查
|
||||
|
||||
- PowerPoint/Keynote 打开导出 PPTX
|
||||
- 双击任意文字应能直接编辑（如果是图片说明第 1 条违反了）
|
||||
- 验证 overflow：每页应该在 body 范围内，没有被截
|
||||
|
||||
---
|
||||
|
||||
## 这条路径 vs 其他选项（什么时候选什么）
|
||||
|
||||
| 需求 | 选什么 |
|
||||
|------|------|
|
||||
| 同事会改 PPTX 里的文字 / 发给非技术人员继续编辑 | **本文路径**（editable，需从头按 4 条约束写 HTML） |
|
||||
| 只是演讲用 / 发存档，不再改 | `export_deck_pdf.mjs`（多文件）或 `export_deck_stage_pdf.mjs`（单文件 deck-stage），出矢量 PDF |
|
||||
| 视觉自由度优先（动画、web component、CSS 渐变、复杂 SVG），接受不可编辑 | `export_deck_pptx.mjs --mode image`（图片铺底 PPTX） |
|
||||
|
||||
**绝不要在视觉自由写好的 HTML 上硬跑 html2pptx**——实测视觉驱动的 HTML pass 率 < 30%，剩下的逐页改造比重写还慢。
|
||||
|
||||
---
|
||||
|
||||
## 为什么 4 条约束不是 Bug 而是物理约束
|
||||
|
||||
这 4 条不是 `html2pptx.js` 作者偷懒——它们是 **PowerPoint 文件格式（OOXML）本身的约束**投射到 HTML 上的结果：
|
||||
|
||||
- PPTX 里文字必须在 text frame（`<a:txBody>`），对应段落级 HTML 元素
|
||||
- PPTX 的 shape 和 text frame 是两个对象，无法在同一 element 上同时画背景和写文字
|
||||
- PPTX 的 shape fill 对 gradient 支持有限（仅某些 preset gradients，不支持 CSS 任意角度渐变）
|
||||
- PPTX 的 picture 对象必须引用真实图片文件，不是 CSS 属性
|
||||
|
||||
理解这点后，**不要期待工具变聪明** —— 是 HTML 写法要适配 PPTX 格式，不是反过来。
|
||||
+212
-33
@@ -1,8 +1,68 @@
|
||||
# Slide Decks：HTML幻灯片制作规范
|
||||
|
||||
做幻灯片是设计工作的高频场景。这份文档说明怎么做好HTML幻灯片。
|
||||
做幻灯片是设计工作的高频场景。这份文档说明怎么做好HTML幻灯片——从架构选型、单页设计，到 PDF/PPTX 导出的完整路径。
|
||||
|
||||
**和huashu-slides skill的区别**：huashu-slides focus on「AI演示文稿全流程」（含PPT导出）；本文档focus on「用HTML本身作为呈现媒介」的设计方法论。两者可以配合使用——用这里的方法做高质量的HTML deck，再用huashu-slides导出成PPTX。
|
||||
**本 skill 的能力覆盖**：
|
||||
- HTML 播放/PDF 导出 → 本文档 + `scripts/export_deck_pdf.mjs` / `scripts/export_deck_stage_pdf.mjs`
|
||||
- 可编辑 PPTX 导出 → `references/editable-pptx.md` + `scripts/html2pptx.js` + `scripts/export_deck_pptx.mjs --mode editable`
|
||||
- 图片铺底 PPTX（不可编辑但视觉保真）→ `scripts/export_deck_pptx.mjs --mode image`
|
||||
|
||||
---
|
||||
|
||||
## 🛑 开工前先确认交付格式（最硬的 checkpoint）
|
||||
|
||||
**这个决策比「单文件还是多文件」更先。** 2026-04-20 期权私董会项目实测：**不在动手前确认交付格式 = 2-3 小时返工。**
|
||||
|
||||
### 决策树
|
||||
|
||||
```
|
||||
│ 问：最终要交付什么？
|
||||
├── 只要浏览器全屏演讲 / 本地 HTML → 视觉最自由，随便做
|
||||
├── 要 PDF（打印 / 发群 / 存档） → 视觉最自由，任何架构都能导出
|
||||
└── 要可编辑 PPTX（同事会改文字） → 🛑 从第一行 HTML 开始就按 `references/editable-pptx.md` 的 4 条硬约束写
|
||||
```
|
||||
|
||||
### 为什么「要 PPTX 就得从头走 Path A」
|
||||
|
||||
PPTX 可编辑的前提是 `html2pptx.js` 能把 DOM 逐元素翻译为 PowerPoint 对象。它需要 **4 条硬约束**：
|
||||
|
||||
1. body 固定 720pt × 405pt（不是 1920×1080px）
|
||||
2. 所有文字包在 `<p>`/`<h1>`-`<h6>` 里（禁止 div 直接放文字，禁止用 `<span>` 承载主文字）
|
||||
3. `<p>`/`<h*>` 自身不能有 background/border/shadow（放外层 div）
|
||||
4. `<div>` 不能用 `background-image`（用 `<img>` 标签）
|
||||
5. 不用 CSS gradient、不用 web component、不用复杂 SVG 装饰
|
||||
|
||||
**本 skill 默认的 HTML 视觉自由度高**——大量 span、嵌套 flex、复杂 SVG、web component（如 `<deck-stage>`）、CSS 渐变——**几乎没有一条能天然过 html2pptx 的约束**（实测视觉驱动的 HTML 直接上 html2pptx，pass 率 < 30%）。
|
||||
|
||||
### 两条真实路径的代价对比（2026-04-20 真实踩坑）
|
||||
|
||||
| 路径 | 做法 | 结果 | 代价 |
|
||||
|------|------|------|------|
|
||||
| ❌ **先自由写 HTML，事后补救 PPTX** | 单文件 deck-stage + 大量 SVG/span 装饰 | 要可编辑 PPTX 只剩两条路：<br>A. 手写 pptxgenjs 几百行 hardcode 坐标<br>B. 重写 17 页 HTML 成 Path A 格式 | 2-3 小时返工，且手写版**维护成本永续**（HTML 改一个字，PPTX 要再人肉同步） |
|
||||
| ✅ **从第一步按 Path A 约束写** | 每页独立 HTML + 4 条硬约束 + 720×405pt | 一条命令导出 100% 可编辑 PPTX，同时也能浏览器全屏演讲（Path A HTML 就是浏览器可播放的标准 HTML） | 写 HTML 时多花 5 分钟想「文字怎么包进 `<p>`」，零返工 |
|
||||
|
||||
### 开工话术（抄走即用）
|
||||
|
||||
> 动手之前先确认交付格式：
|
||||
> - **浏览器演讲 / PDF** → 我按设计自由度最大的方式做（可以用动画、web component、复杂 SVG、CSS 渐变）
|
||||
> - **需要可编辑 PPTX**（同事会改文字） → 我必须从一开始就按 `references/editable-pptx.md` 的 4 条硬约束写 HTML。视觉能力会少一些（无渐变、无 web component、无复杂 SVG），但导出就是一条命令的事
|
||||
>
|
||||
> 你选哪条？
|
||||
|
||||
### 混合交付怎么办
|
||||
|
||||
用户说「我要 HTML 演讲 **和** 可编辑 PPTX」——**这不是混合**，是 PPTX 需求覆盖 HTML 需求。按 Path A 写出来的 HTML 本身就能浏览器全屏演讲（加个 `deck_index.html` 拼接器就行）。**没有额外代价。**
|
||||
|
||||
用户说「我要 PPTX **和** 动画 / web component」——**这是真矛盾**。告诉用户：要可编辑 PPTX 就得牺牲这些视觉能力。让他做取舍，不要偷偷做手写 pptxgenjs 方案（会变成永续维护债）。
|
||||
|
||||
### 事后才知道要 PPTX 怎么办（紧急补救）
|
||||
|
||||
极个别情况：HTML 已经写好了才发现要 PPTX。此时两个选项都不完美：
|
||||
|
||||
1. **图片铺底 PPTX**（`scripts/export_deck_pptx.mjs` image 模式）——视觉 100% 保真但文字不可编辑。适合「演讲用 PPT 播放、不改内容」场景
|
||||
2. **手写 pptxgenjs 重建**（为每页手写 addText/addShape + 图形 PNG 嵌入）——文字可编辑，但位置、字体、对齐都要手调，维护成本高。**只有用户明确接受「HTML 源要改就得重新手调 PPTX」才走这条**
|
||||
|
||||
永远优先把选择告诉用户，让他决定。**永远不要第一反应就开始手写 pptxgenjs**——那是最后的兜底手段。
|
||||
|
||||
---
|
||||
|
||||
@@ -142,49 +202,113 @@ Playwright 截图也是直接 `goto(file://.../slides/05-personas.html)`，不
|
||||
### 基本用法
|
||||
|
||||
1. 从 `assets/deck_stage.js` 读取内容，嵌入 HTML 的 `<script>`（或 `<script src="deck_stage.js">`）
|
||||
2. 在 body 里用 `<deck-stage>` 包 slide：
|
||||
2. 在 body 里用 `<deck-stage>` 包 slide
|
||||
3. 🛑 **script 标签必须放在 `</deck-stage>` 之后**（见下方硬约束）
|
||||
|
||||
```html
|
||||
<deck-stage>
|
||||
<section>
|
||||
<h1>Slide 1</h1>
|
||||
</section>
|
||||
<section>
|
||||
<h1>Slide 2</h1>
|
||||
</section>
|
||||
</deck-stage>
|
||||
<body>
|
||||
|
||||
<deck-stage>
|
||||
<section>
|
||||
<h1>Slide 1</h1>
|
||||
</section>
|
||||
<section>
|
||||
<h1>Slide 2</h1>
|
||||
</section>
|
||||
</deck-stage>
|
||||
|
||||
<!-- ✅ 正确：script 在 deck-stage 之后 -->
|
||||
<script src="deck_stage.js"></script>
|
||||
|
||||
</body>
|
||||
```
|
||||
|
||||
### 🛑 Script 位置硬约束（2026-04-20 真实踩坑）
|
||||
|
||||
**不能把 `<script src="deck_stage.js">` 放在 `<head>` 里。** 即使它在 `<head>` 里能定义 `customElements`，parser 在解析到 `<deck-stage>` 开始标签时就会触发 `connectedCallback`——此时子 `<section>` 还没被 parse，`_collectSlides()` 拿到空数组，counter 显示 `1 / 0`，所有页同时叠加渲染。
|
||||
|
||||
**三条合规写法**（任选其一）：
|
||||
|
||||
```html
|
||||
<!-- ✅ 最推荐：script 在 </deck-stage> 之后 -->
|
||||
</deck-stage>
|
||||
<script src="deck_stage.js"></script>
|
||||
|
||||
<!-- ✅ 也可：script 在 head 但加 defer -->
|
||||
<head><script src="deck_stage.js" defer></script></head>
|
||||
|
||||
<!-- ✅ 也可：module 脚本天然 defer -->
|
||||
<head><script src="deck_stage.js" type="module"></script></head>
|
||||
```
|
||||
|
||||
`deck_stage.js` 本身已内置 `DOMContentLoaded` 延迟收集防御，即使 script 放 head 也不会彻底炸掉——但 `defer` 或放 body 底部仍然是更干净的做法，避免依赖防御分支。
|
||||
|
||||
### ⚠️ 单文件架构的 CSS 陷阱（务必阅读）
|
||||
|
||||
单文件架构最常见的坑——**`display` 属性被单页样式偷走**。
|
||||
|
||||
如果你给某张 slide 的样式写了 `display: flex/grid`：
|
||||
常见错误姿势 1（直接写 display: flex 到 section）：
|
||||
|
||||
```css
|
||||
.emotion-slide { display: grid; } /* 特异性: 10 */
|
||||
```
|
||||
|
||||
它会压过 deck 级的「隐藏非 active 页」规则：
|
||||
|
||||
```css
|
||||
deck-stage > section { display: none; } /* 特异性: 2 */
|
||||
```
|
||||
|
||||
结果所有 slide 同时渲染叠加。
|
||||
|
||||
**修复模式**（写 deck 时必做）：
|
||||
|
||||
```css
|
||||
/* ✅ 用 :not(.active) + !important 锁死「非激活即隐藏」 */
|
||||
deck-stage > section:not(.active) {
|
||||
display: none !important;
|
||||
/* ❌ 外部 CSS 特异性 2，覆盖了 shadow DOM 的 ::slotted(section){display:none}（也是 2）*/
|
||||
deck-stage > section {
|
||||
display: flex; /* 所有页会同时叠加渲染！ */
|
||||
flex-direction: column;
|
||||
padding: 80px;
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
特异性+权重双保险，单页 layout class 的 `display: grid/flex` 就不会影响可见性。
|
||||
常见错误姿势 2（section 有特异性更高的 class）：
|
||||
|
||||
另一个替代方案：**把单页的 flex/grid 写到内部 wrapper div 上**，section 本身只管 `display: block/none`。
|
||||
```css
|
||||
.emotion-slide { display: grid; } /* 特异性: 10，更糟 */
|
||||
```
|
||||
|
||||
两种都会让 **所有 slide 同时叠加渲染**——counter 可能显示 `1 / 10` 假装正常，但视觉上第一页盖着第二页盖着第三页。
|
||||
|
||||
### ✅ Starter CSS（开工直接 copy，不踩坑）
|
||||
|
||||
**section 自身**只管「可见/不可见」；**layout（flex/grid 等）写到 `.active` 上**：
|
||||
|
||||
```css
|
||||
/* section 只定义非 display 的通用样式 */
|
||||
deck-stage > section {
|
||||
background: var(--paper);
|
||||
padding: 80px 120px;
|
||||
overflow: hidden;
|
||||
position: relative;
|
||||
/* ⚠️ 不要在这里写 display! */
|
||||
}
|
||||
|
||||
/* 锁死「非激活即隐藏」——特异性+权重双保险 */
|
||||
deck-stage > section:not(.active) {
|
||||
display: none !important;
|
||||
}
|
||||
|
||||
/* 激活页才写需要的 display + layout */
|
||||
deck-stage > section.active {
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
justify-content: center;
|
||||
}
|
||||
|
||||
/* 打印模式：所有页都要显示，覆盖 :not(.active) */
|
||||
@media print {
|
||||
deck-stage > section { display: flex !important; }
|
||||
deck-stage > section:not(.active) { display: flex !important; }
|
||||
}
|
||||
```
|
||||
|
||||
替代方案：**把单页的 flex/grid 写到内部 wrapper `<div>` 上**，section 本身永远只是 `display: block/none` 的切换器。这是最干净的做法：
|
||||
|
||||
```html
|
||||
<deck-stage>
|
||||
<section>
|
||||
<div class="slide-content flex-layout">...</div>
|
||||
</section>
|
||||
</deck-stage>
|
||||
```
|
||||
|
||||
### 自定义尺寸
|
||||
|
||||
@@ -316,7 +440,7 @@ Deck 需要 **intentional variety**：
|
||||
|
||||
HTML 优先是第一公民。但用户经常需要 PPTX/PDF 交付。提供两个通用脚本，**任何多文件 deck 都能用**，位于 `scripts/` 下：
|
||||
|
||||
### `export_deck_pdf.mjs` — 导出矢量 PDF（推荐）
|
||||
### `export_deck_pdf.mjs` — 导出矢量 PDF（多文件架构）
|
||||
|
||||
```bash
|
||||
node scripts/export_deck_pdf.mjs --slides <slides-dir> --out deck.pdf
|
||||
@@ -332,6 +456,61 @@ node scripts/export_deck_pdf.mjs --slides <slides-dir> --out deck.pdf
|
||||
|
||||
**限制**：PDF 不能再编辑文字——要改回到 HTML 改。
|
||||
|
||||
### `export_deck_stage_pdf.mjs` — 单文件 deck-stage 架构专用 ⚠️
|
||||
|
||||
**什么时候用**：deck 是单 HTML 文件 + `<deck-stage>` web component 包裹 N 个 `<section>`（即路径 B 架构）。此时 `export_deck_pdf.mjs` 那套「每个 HTML 一次 `page.pdf()`」走不通，需要走这个专用脚本。
|
||||
|
||||
```bash
|
||||
node scripts/export_deck_stage_pdf.mjs --html deck.html --out deck.pdf
|
||||
```
|
||||
|
||||
**为什么不能复用 export_deck_pdf.mjs**（2026-04-20 真实踩坑记录）：
|
||||
|
||||
1. **Shadow DOM 赢过 `!important`**：deck-stage 的 shadow CSS 里有 `::slotted(section) { display: none }`（只 active 的那张 `display: block`）。即使在 light DOM 用 `@media print { deck-stage > section { display: block !important } }` 也压不住——`page.pdf()` 触发 print 媒体后 Chromium 最终渲染只有 active 那一张，结果**整个 PDF 只有 1 页**（当前 active slide 的重复）。
|
||||
|
||||
2. **循环 goto 每页还是只出 1 页**：直觉解法「对每个 `#slide-N` navigate 一次再 `page.pdf({pageRanges:'1'})`」也失败——因为 print CSS 在 shadow DOM 之外也有 `deck-stage > section { display: block }` 规则被 override 后，最终渲染永远是 section 列表的第一个（不是你 navigate 到的那一页）。结果 17 次循环得到 17 张 P01 封面。
|
||||
|
||||
3. **absolute 子元素跑到下一页**：即使成功让所有 section 渲染出来，section 本身若 `position: static`，其 absolute 定位的 `cover-footer`/`slide-footer` 会相对 initial containing block 定位——当 section 被 print 强制为 1080px 高度，absolute footer 可能被推到下一页（表现为 PDF 比 section 数量多 1 页，多出来的那页只含 footer 孤儿）。
|
||||
|
||||
**修复策略**（脚本已实现）：
|
||||
|
||||
```js
|
||||
// 打开 HTML 后，用 page.evaluate 把 section 从 deck-stage slot 中提出来，
|
||||
// 直接挂到 body 下一个普通 div 里，并内联 style 确保 position:relative + 固定尺寸
|
||||
await page.evaluate(() => {
|
||||
const stage = document.querySelector('deck-stage');
|
||||
const sections = Array.from(stage.querySelectorAll(':scope > section'));
|
||||
document.head.appendChild(Object.assign(document.createElement('style'), {
|
||||
textContent: `
|
||||
@page { size: 1920px 1080px; margin: 0; }
|
||||
html, body { margin: 0 !important; padding: 0 !important; }
|
||||
deck-stage { display: none !important; }
|
||||
`,
|
||||
}));
|
||||
const container = document.createElement('div');
|
||||
sections.forEach(s => {
|
||||
s.style.cssText = 'width:1920px!important;height:1080px!important;display:block!important;position:relative!important;overflow:hidden!important;page-break-after:always!important;break-after:page!important;background:#F7F4EF;margin:0!important;padding:0!important;';
|
||||
container.appendChild(s);
|
||||
});
|
||||
// 最后一页禁分页，避免尾部空白页
|
||||
sections[sections.length - 1].style.pageBreakAfter = 'auto';
|
||||
sections[sections.length - 1].style.breakAfter = 'auto';
|
||||
document.body.appendChild(container);
|
||||
});
|
||||
|
||||
await page.pdf({ width: '1920px', height: '1080px', printBackground: true, preferCSSPageSize: true });
|
||||
```
|
||||
|
||||
**为什么这能 work**：
|
||||
- 把 section 从 shadow DOM slot 拔到 light DOM 的普通 div——彻底绕过 `::slotted(section) { display: none }` 规则
|
||||
- 内联 `position: relative` 让 absolute 子元素相对 section 定位，不会溢出
|
||||
- `page-break-after: always` 让浏览器 print 时每 section 独立一页
|
||||
- `:last-child` 不分页避免尾部空白页
|
||||
|
||||
**用 `mdls -name kMDItemNumberOfPages` 验证时注意**：macOS 的 Spotlight metadata 有缓存，PDF 重写后要跑 `mdimport file.pdf` 强制刷新，否则显示旧的页数。用 `pdfinfo` 或 `pdftoppm` 数文件数才是真数。
|
||||
|
||||
---
|
||||
|
||||
### `export_deck_pptx.mjs` — 导出 PPTX（两种模式）
|
||||
|
||||
```bash
|
||||
@@ -393,7 +572,7 @@ node scripts/export_deck_pptx.mjs --slides <dir> --out deck.pptx --mode editable
|
||||
|
||||
## 导出为可编辑 PPTX 的深度路径（仅长期项目）
|
||||
|
||||
如果你的 deck 会长期维护、反复修改、团队协作——建议**一开始就按 html2pptx 约束写 HTML**，让 `--mode editable` 稳定通过。详见 `huashu-slides` skill 的 `references/prompt-templates.md` 第 2 节（4 条硬性约束）。
|
||||
如果你的 deck 会长期维护、反复修改、团队协作——建议**一开始就按 html2pptx 约束写 HTML**，让 `--mode editable` 稳定通过。详见 `references/editable-pptx.md`（4 条硬约束 + HTML 模板 + 常见错误速查）。
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -21,7 +21,7 @@ open -a "Google Chrome" "/path/to/your/design.html"
|
||||
HTML文件里最常见的问题是JS报错导致白屏。用Playwright跑一遍：
|
||||
|
||||
```bash
|
||||
python "$SKILL/scripts/verify.py" path/to/design.html
|
||||
python ~/.claude/skills/claude-design/scripts/verify.py path/to/design.html
|
||||
```
|
||||
|
||||
这个脚本会：
|
||||
@@ -120,7 +120,13 @@ open screenshot.png
|
||||
|
||||
### 上传图床分享链接
|
||||
|
||||
如果需要给远程协作者看（比如 Slack/飞书/微信），让用户用自己的图床工具或 MCP 上传。任何返回永久链接的图床都行（ImgBB / Cloudflare R2 / 七牛 / 自建等），粘贴到任何地方。
|
||||
如果需要给远程协作者看（比如 Slack/飞书/微信），让用户用自己的图床工具或 MCP 上传：
|
||||
|
||||
```bash
|
||||
python ~/Documents/写作/tools/upload_image.py screenshot.png
|
||||
```
|
||||
|
||||
返回ImgBB的永久链接，可以粘贴到任何地方。
|
||||
|
||||
## 验证出错时
|
||||
|
||||
|
||||
@@ -86,13 +86,22 @@ bash add-music.sh product-promo.mp4 --mood=ad --out=promo-final.mp4
|
||||
从已有 MP4 生成 60fps 版本和 GIF。
|
||||
|
||||
```bash
|
||||
bash /path/to/claude-design/scripts/convert-formats.sh <input.mp4> [gif_width]
|
||||
bash /path/to/claude-design/scripts/convert-formats.sh <input.mp4> [gif_width] [--minterpolate]
|
||||
```
|
||||
|
||||
输出（与输入同目录）：
|
||||
- `<name>-60fps.mp4` — minterpolate 插帧到 60fps
|
||||
- `<name>-60fps.mp4` — 默认用 `fps=60` 帧复制（兼容性广）；加 `--minterpolate` 启用高质量插帧
|
||||
- `<name>.gif` — palette 优化的 GIF（默认 960 宽，可改）
|
||||
|
||||
**60fps 模式选择**：
|
||||
|
||||
| 模式 | 命令 | 兼容性 | 使用场景 |
|
||||
|---|---|---|---|
|
||||
| 帧复制（默认）| `convert-formats.sh in.mp4` | QuickTime/Safari/Chrome/VLC 全通 | 通用交付、上传平台、社交媒体 |
|
||||
| minterpolate 插帧 | `convert-formats.sh in.mp4 --minterpolate` | macOS QuickTime/Safari 可能拒打 | B站等需要真插帧的展示场景，**交付前必须本地测**目标播放器 |
|
||||
|
||||
为什么默认改成帧复制？minterpolate 输出的 H.264 elementary stream 有 known compat bug——之前默认 minterpolate 时多次踩到「macOS QuickTime 打不开」的问题。详见 `animation-pitfalls.md` §14。
|
||||
|
||||
`gif_width` 参数：
|
||||
- 960（默认）—— 社交平台通用
|
||||
- 1280 —— 更清晰但文件更大
|
||||
@@ -164,6 +173,9 @@ GIF 只能 256 色。一次 pass 的 GIF 会把全动画色彩压到 256 色通
|
||||
- [ ] 动画最后一帧是稳定的收尾状态（不是半截）
|
||||
- [ ] 字体/图片/emoji 全部正常渲染（参考 `animation-pitfalls.md`）
|
||||
- [ ] Duration 参数与 HTML 里的实际动画时长匹配
|
||||
- [ ] HTML 中 Stage 检测 `window.__recording` 强制 loop=false（手写 Stage 必查；用 `assets/animations.jsx` 自带）
|
||||
- [ ] 结尾 Sprite 的 `fadeOut={0}`（视频末帧不淡出）
|
||||
- [ ] 含「Created by Huashu-Design」水印（仅动画场景必加；第三方品牌作品加「非官方出品 · 」前缀。详见 SKILL.md §「Skill 推广水印」）
|
||||
|
||||
## 交付时附带的说明
|
||||
|
||||
|
||||
Reference in new issue
Block a user