SixStringBny/showcase-capture

Showcase capture

当用户需要网页项目的截图、GIF或WebM导览时使用此技能。该工具使用 Playwright 运行本地或线上站点，遵循声明式场景，并生成 README 和画廊。

输出内容

• screens/*.png
• README.md（包含截图和字幕）
• index.html 画廊
• showcase.json 清单
• 可选的 *.gif
• 可选的 *.webm

安装

从技能目录：

node scripts/install.mjs

从 npm 包：

npx showcase-capture install

或手动安装：

npm install
npm run build
npx playwright install chromium

检查环境：

npx showcase-capture doctor

工作流程

1. 检查项目。

   • 框架和开发命令。
   • 静态站点的构建输出目录。
   • 路由和关键页面。
   • 认证流程和测试用户。
   • 重置机制（通常是 localStorage 或 cookies）。
   • 最能解释产品的 5 到 8 个页面。
   • 一个用于 GIF 和 WebM 的端到端流程。

2. 编写 showcase.config.yaml。

   • 使用静态、命令或在线 URL 服务器。
   • 优先使用角色（role）和可访问名称（accessible name），而非 CSS 选择器。
   • 添加 reset 块，以确保每个场景从已知状态开始。
   • 使用 mask 遮盖邮箱、令牌、姓名和支付信息。
   • GIF 流程保持简短：20 到 40 秒。

3. 校验场景。这会检查场景和 GIF 流程。

npx showcase-capture check

4. 捕获。

npx showcase-capture capture

5. 审查输出。

   • 打开 README.md 和 index.html。
   • 检查 GIF 和 WebM。
   • 修复缺失的选择器、裁剪不当或时间问题。
   • 迭代时使用 --only <scene> 重新运行。

6. 提交配置和生成的输出。

配置示例

name: LaunchPad
baseUrl: http://localhost:5173
outDir: docs/showcase

server:
  mode: command
  command: npm run dev
  url: http://localhost:5173

reset:
  localStorage:
    - launchpad.demo.v2

context:
  locale: en-ZA
  timezoneId: Africa/Johannesburg
  fixedTime: "2026-11-09T09:00:00+02:00"
  reducedMotion: reduce

viewports:
  desktop: { width: 1440, height: 900 }
  mobile: { width: 390, height: 844 }

scenes:
  - name: desktop
    viewport: desktop
    steps:
      - goto: /
      - waitFor: h1
      - screenshot: 01-home

      - goto: /login
      - waitFor: form
      - click:
          role: button
          name: Continue as test user
      - waitForUrl: "#/app/dashboard"
      - screenshot: 06-dashboard

  - name: mobile
    viewport: mobile
    steps:
      - goto: /login
      - waitFor: form
      - click:
          role: button
          name: Continue as test user
      - waitForUrl: "#/app/dashboard"
      - screenshot: 21-mobile-dashboard

gif:
  viewport: { width: 1024, height: 640 }
  size: { width: 960, height: 600 }
  fps: 8
  steps:
    - goto: /
    - caption: [1, Discover, "Learn, match and book in one place"]
    - wait: 600
    - scroll: 660
    - goto: /learn
    - caption: [1, "Explore six practical modules", "Built around real freelance questions"]

video:
  enabled: true
  size: { width: 1280, height: 720 }

服务器模式

静态站点：

server:
  mode: static
  dir: dist
  spa: true

开发服务器：

server:
  mode: command
  command: npm run dev
  url: http://localhost:5173

线上 URL：

server:
  mode: none
baseUrl: https://example.com

在提供静态文件之前可选的构建步骤：

build: npm run build

覆盖层

GIF 覆盖层是可选的。用于匹配项目品牌或将字幕移开重要内容。

overlay:
  background: "rgba(8, 20, 38, 0.93)"
  accent: "#5367e8"
  font: "Inter, system-ui, sans-serif"
  offsetX: 24
  offsetY: 24

设置 overlay.enabled: false 可不带字幕或光标录制 GIF。

步骤参考

• goto: /path
• waitFor: h1 或 waitFor: { role: heading, name: Dashboard }
• click: ".selector" 或 click: { role: button, name: Continue }
• fill: { selector: "#email", value: "[email protected]" }
• press: Enter
• hover: ".card"
• waitForUrl: "#/app/dashboard" 或 waitForUrl: { pattern: "/app/", flags: "i" }
• wait: 500
• scroll: 600 或 scroll: { selector: ".footer" }
• screenshot: 01-home
• screenshot: { name: 01-home, fullPage: true }
• viewport: mobile
• caption: [1, "Title", "Subtitle"]（仅适用于 GIF 流程）
• reset: true
• eval: "localStorage.setItem('key', 'value')"
• run: function（仅适用于 TypeScript 或 JavaScript 配置）

TypeScript 配置

当场景需要自定义逻辑时，使用 TypeScript 配置：

import { defineShowcase } from 'showcase-capture'

export default defineShowcase({
  name: 'My project',
  outDir: 'docs/showcase',
  server: { mode: 'static', dir: 'dist' },
  scenes: [
    {
      name: 'desktop',
      steps: [
        { goto: '/' },
        {
          run: async ({ page }) => {
            await page.evaluate(() => localStorage.setItem('theme', 'light'))
          },
        },
        { waitFor: 'h1' },
        { screenshot: '01-home' },
      ],
    },
  ],
})

隐私

• 不要捕获管理界面、密钥、令牌或支付信息。
• 使用 mask 遮盖邮箱、姓名和账户数据。
• 使用虚构数据的测试账户。
• 发布前检查 GIF 和 WebM。
• 该工具不会上传任何内容。

故障排除

• Could not launch Chromium：运行 npx playwright install chromium 或设置 CHROME_PATH。
• Server did not respond：检查命令、端口和 URL。如果开发服务器已经在运行，使用 reuseExisting: true。
• waitFor 超时：优先使用 getByRole 选择器，检查页面标题，或添加 wait。
• GIF 太长：缩短步骤，降低 fps，或减小视口。
• WebM 缺失：检查 video.enabled 是否为 true 并且存在 gif 流程。
• 截图尺寸错误：在场景或配置中设置视口。