SixStringBny/showcase-capture

Showcase 擷取功能

當有人需要網頁專案的螢幕截圖、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 遮罩電子郵件、Token、姓名與付款詳細資料。
   • 讓 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' },
      ],
    },
  ],
})

隱私保護

• 請勿擷取管理後台畫面、機密資訊、Token 或付款詳細資料。
• 使用 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 流程存在。
• 螢幕截圖尺寸錯誤：在場景或設定檔中設定顯示區域（viewport）。