التقط لقطات شاشة لموقع الويب من خلال استدعاء واجهة برمجة التطبيقات (API) مرة واحدة

أنت بحاجة إلى لقطة شاشة لصفحة ويب. ربما تقوم بإنشاء معاينات رابط لتطبيق الدردشة. ربما تقوم بإجراء اختبارات الانحدار البصري في CI. ربما تقوم بإنشاء تقارير PDF التي تتضمن لقطة حية للوحة القيادة. الجواب الواضح هو محرك الدمى أو الكاتب المسرحي الخادم الخاص بك. المشكلة الواضحة: يستهلك برنامج Chromium الثنائي بدون رأس ما يتراوح بين 200 إلى 500 ميجابايت من الذاكرة، يستغرق التشغيل البارد من 3 إلى 8 ثوانٍ، ويحتاج إلى تبعيات على مستوى نظام التشغيل، ويحول صورة Docker الخاصة بك في قطعة أثرية 1 غيغابايت. كل ذلك لالتقاط لقطات شاشة لموقع الويب برمجيًا.

هناك طريق أبسط. أرسل عنوان URL إلى واجهة برمجة تطبيقات لقطة الشاشة، واسترجع صورة. لا يوجد متصفح ثنائي على الخادم الخاص بك، ولا توجد زيادات في الذاكرة، ولا يوجد عدم تطابق في إصدار Chromium عبر البيئات.

التقط لقطة شاشة لموقع الويب بطلب POST واحد

أرسل عنوان URL إلى /v1/screenshot/capture نقطة النهاية واستعادة لقطة الشاشة مثل PNG أو JPEG أو WebP. تقوم واجهة برمجة التطبيقات (API) بتشغيل مثيل Chromium كاملاً على شبكة Cloudflare الطرفية، لذلك يتم عرض جميع خطوط JavaScript وCSS وخطوط الويب بشكل صحيح.

curl -X POST https://api.botoi.com/v1/screenshot/capture \\
  -H "Content-Type: application/json" \\
  -d '{
    "url": "https://github.com",
    "width": 1280,
    "height": 800,
    "format": "png"
  }'

إجابة:

{
  "success": true,
  "data": {
    "url": "https://api.botoi.com/screenshots/a1b2c3d4.png",
    "format": "png",
    "width": 1280,
    "height": 800,
    "fullPage": false,
    "size_bytes": 184320
  }
}

يمنحك الرد عنوان URL مباشرًا للصورة الملتقطة بالإضافة إلى التنسيق والأبعاد وحجم الملف. يمكنك تنزيل عنوان URL هذا أو تخزينه مؤقتًا أو تقديمه مباشرةً في تطبيقك. لا مطلوب فك تشفير Base64 أو معالجة الملفات.

التحكم في إطار العرض والتنسيق والتوقيت

تلتقط لقطة الشاشة الافتراضية إطار عرض مقاس 1280 × 800 بتنسيق PNG. وهذا يغطي معظم الاستخدام الحالات، ولكنك ستحتاج غالبًا إلى مزيد من التحكم. فيما يلي المعلمات التي يمكنك تعيينها:

• العرض / الارتفاع: أبعاد إطار العرض بالبكسل. استخدم 1440x900 لسطح المكتب، 390x844 لجهاز iPhone 14، أو 768x1024 لجهاز iPad.
• شكل: الإخراج كما png (بدون خسارة، أكبر)، jpeg (ضائع، أصغر)، أو webp (أفضل ضغط لاستخدام الويب).
• صفحة كاملة: اضبط على true لالتقاط الصفحة القابلة للتمرير بأكملها، ليس فقط ما يناسب إطار العرض. تقوم واجهة برمجة التطبيقات (API) بالتمرير عبر الصفحة وتخيط النتيجة في صورة واحدة طويلة.
• تأخير: ميلي ثانية للانتظار بعد تحميل الصفحة قبل الالتقاط. اضبط هذا على 2000-3000 للمنتجعات الصحية التي تجلب البيانات عند التحميل والعرض من جانب العميل. بدونها، سوف لقطة شاشة لأداة التحميل الدوارة.

فيما يلي طلب يلتقط لقطة شاشة WebP لصفحة كاملة لـ SPA التي يتم عرضها بواسطة JavaScript مع تأخير 3 ثواني:

curl -X POST https://api.botoi.com/v1/screenshot/capture \\
  -H "Content-Type: application/json" \\
  -d '{
    "url": "https://your-spa.vercel.app",
    "width": 1440,
    "height": 900,
    "format": "webp",
    "fullPage": true,
    "delay": 3000
  }'

إنشاء معاينات الارتباط لتطبيقك

تعد معاينات الارتباط أحد الأسباب الأكثر شيوعًا لالتقاط لقطات شاشة لصفحة الويب برمجيا. عندما يقوم مستخدم بلصق عنوان URL في تطبيق الدردشة أو نظام إدارة المحتوى أو إدارة المشروع الأداة، تريد إظهار صورة مصغرة. تغطي صور الرسم البياني المفتوحة بعض الروابط، ولكن العديد من الصفحات لا تقم بتعيينها، وتلك التي تستخدم غالبًا صور العلامة التجارية العامة بدلاً من الصفحة الفعلية المحتوى.

يعرض خادم Node.js هذا ملف /preview نقطة النهاية التي تلتقط وذاكرة التخزين المؤقت الصور المصغرة بحجم 1200 × 630 (الحجم القياسي لصورة الرسم البياني المفتوح):

import express from "express";

const app = express();
app.use(express.json());

const screenshotCache = new Map();

async function captureScreenshot(url) {
  // Return cached version if available
  if (screenshotCache.has(url)) {
    return screenshotCache.get(url);
  }

  const res = await fetch("https://api.botoi.com/v1/screenshot/capture", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      url,
      width: 1200,
      height: 630,
      format: "webp",
    }),
  });

  const { data } = await res.json();
  screenshotCache.set(url, data.url);
  return data.url;
}

app.get("/preview", async (req, res) => {
  const { url } = req.query;

  if (!url) {
    return res.status(400).json({ error: "url parameter required" });
  }

  const thumbnailUrl = await captureScreenshot(url);
  res.json({
    original_url: url,
    thumbnail: thumbnailUrl,
    dimensions: "1200x630",
  });
});

app.listen(3000);

يتصل /preview?url=https://stripe.com/docs وستستعيد صورة WebP المصغرة عنوان URL يعرض محتوى الصفحة الفعلي. تمنع ذاكرة التخزين المؤقت في الذاكرة عمليات الالتقاط المكررة لـ نفس عنوان URL. في الإنتاج، قم بتبديل ذلك Map لـ Redis أو ذاكرة التخزين المؤقت CDN مع ملف TTL من 24 إلى 48 ساعة حتى تظل المعاينات متجددة.

اختبار الانحدار البصري في CI

يلتقط اختبار الانحدار المرئي كسرًا في التخطيط تفتقده اختبارات الوحدة. تغيير CSS ذلك لا يزال من الممكن أن يؤدي اجتياز جميع الاختبارات إلى دفع عنوان صفحة التسعير الخاصة بك إلى خارج الشاشة. التقليدية يحتاج النهج إلى كاتب مسرحي ومتصفح مقطوع الرأس يعمل في مشغل CI الخاص بك. وهذا يضيف 2-3 دقائق إلى خط الأنابيب الخاص بك ويستخدم 500+ ميغابايت من القرص.

يلتقط سير عمل GitHub Actions لقطات شاشة للصفحات الرئيسية من كل من الإنتاج و معاينة العلاقات العامة الخاصة بك، ثم يُخرج جدول مقارنة في ملخص العلاقات العامة:

name: Visual regression check

on:
  pull_request:
    branches: [main]

jobs:
  screenshot-diff:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Capture baseline screenshots
        run: |
          PAGES=("/" "/pricing" "/docs" "/blog")
          BASE_URL="https://your-app.com"
          mkdir -p screenshots/baseline

          for PAGE in "\${PAGES[@]}"; do
            FILENAME=\$(echo "\$PAGE" | tr '/' '-' | sed 's/^-//')
            [ -z "\$FILENAME" ] && FILENAME="home"

            curl -s -X POST https://api.botoi.com/v1/screenshot/capture \\
              -H "Content-Type: application/json" \\
              -H "Authorization: Bearer \${{ secrets.BOTOI_API_KEY }}" \\
              -d "{
                \\"url\\": \\"\$BASE_URL\$PAGE\\",
                \\"width\\": 1280,
                \\"height\\": 800,
                \\"format\\": \\"png\\",
                \\"fullPage\\": true
              }" | jq -r '.data.url' > "screenshots/baseline/\$FILENAME.url"

            echo "Captured baseline: \$PAGE"
          done

      - name: Capture PR preview screenshots
        run: |
          PAGES=("/" "/pricing" "/docs" "/blog")
          PREVIEW_URL="\${{ github.event.pull_request.head.repo.html_url }}"
          mkdir -p screenshots/preview

          for PAGE in "\${PAGES[@]}"; do
            FILENAME=\$(echo "\$PAGE" | tr '/' '-' | sed 's/^-//')
            [ -z "\$FILENAME" ] && FILENAME="home"

            curl -s -X POST https://api.botoi.com/v1/screenshot/capture \\
              -H "Content-Type: application/json" \\
              -H "Authorization: Bearer \${{ secrets.BOTOI_API_KEY }}" \\
              -d "{
                \\"url\\": \\"\$PREVIEW_URL\$PAGE\\",
                \\"width\\": 1280,
                \\"height\\": 800,
                \\"format\\": \\"png\\",
                \\"fullPage\\": true
              }" | jq -r '.data.url' > "screenshots/preview/\$FILENAME.url"

            echo "Captured preview: \$PAGE"
          done

      - name: Compare screenshots
        run: |
          echo "## Visual regression report" >> \$GITHUB_STEP_SUMMARY
          echo "" >> \$GITHUB_STEP_SUMMARY

          for BASELINE in screenshots/baseline/*.url; do
            NAME=\$(basename "\$BASELINE" .url)
            BASELINE_URL=\$(cat "\$BASELINE")
            PREVIEW_URL=\$(cat "screenshots/preview/\$NAME.url")
            echo "| \$NAME | [baseline](\$BASELINE_URL) | [preview](\$PREVIEW_URL) |" >> \$GITHUB_STEP_SUMMARY
          done

يلتقط سير العمل أربع صفحات من موقع الإنتاج الخاص بك وعنوان URL لمعاينة العلاقات العامة. يتم تسجيل عناوين URL الخاصة بلقطات الشاشة في ملخص خطوات GitHub كجدول مقارنة حتى يتمكن المراجعون من تسجيلها يمكن التحقق بصريا من كل صفحة. لا توجد ثنائيات للمتصفح في CI، ولا يوجد إعداد Playwright، ولا يوجد Docker التخزين المؤقت للطبقة.

للحصول على اختلاف تلقائي على مستوى البكسل، قم بتوصيل عناوين URL الخاصة بلقطة الشاشة إلى أداة مقارنة مثل pixelmatch أو resemblejs وفشل سير العمل إذا كان الفرق يتجاوز عتبة.

المقارنة: لقطة شاشة API مقابل محرك الدمى المستضاف ذاتيًا

يمنحك تشغيل المتصفح بدون رأس التحكم الكامل، ولكن هذا التحكم يأتي معه التكلفة التشغيلية. وإليك كيفية تكديس النهجين:

Feature                  | Screenshot API             | Self-hosted Puppeteer
─────────────────────────|────────────────────────────|──────────────────────────
Setup time               | 0 min (one HTTP call)      | 30-60 min (Docker, deps)
Browser binary           | Managed by API             | You maintain Chromium
Memory usage             | 0 MB on your server        | 200-500 MB per instance
Cold start               | None (edge network)        | 3-8 sec (browser launch)
Scaling                  | Handled automatically      | Manual (container pool)
Maintenance              | None                       | OS patches, Chrome updates
Cost (low volume)        | Free (5 req/min)           | Server cost + your time
Cost (high volume)       | API plan (~\$20/mo)         | \$50-200/mo (server + ops)
Full-page capture        | Built-in parameter         | Custom scroll logic
Format options           | PNG, JPEG, WebP            | Depends on your code
JavaScript rendering     | Built-in delay param       | Custom waitForSelector

تفوز واجهة برمجة التطبيقات (API) بسرعة الإعداد والصيانة. محرك الدمى المستضاف ذاتيًا يفوز عندما تحتاج إليه التحكم الدقيق في المتصفح (اعتراض طلبات الشبكة، وإدخال ملفات تعريف الارتباط لـ صفحات مصادق عليها، أو تشغيل JavaScript مخصص قبل الالتقاط). بالنسبة لمعظم لقطات الشاشة حالات الاستخدام؛ معاينات الروابط، والاختبار المرئي، والصور المصغرة للتقارير، والبطاقات الاجتماعية؛ واجهة برمجة التطبيقات يغطي النهج ما تحتاجه دون تحمل البنية التحتية.

النقاط الرئيسية

- One POST request captures any public URL as PNG, JPEG, or WebP
- Viewport width, height, full-page mode, and JS delay are all configurable
- No Puppeteer, Chromium, or headless browser setup on your side
- Free tier: 5 screenshots per minute, no API key needed
- Use cases: link previews, visual regression testing, PDF reports, social cards
- The API runs Chromium on the edge, so JS-heavy SPAs render correctly

الطبقة المجانية بمعدل 5 طلبات في الدقيقة تعمل على التطوير والنماذج الأولية وتقليل حركة المرور معاينات الارتباط. بالنسبة لخطوط أنابيب CI وتطبيقات الإنتاج التي تحتاج إلى إنتاجية أعلى، قم بإضافة مفتاح API في Authorization: Bearer header. تحقق من مستندات API للحصول على مرجع المعلمة الكامل ومخطط الاستجابة.