كيف تنشئون لقطات شاشة للمنتج تلقائيًا من أجل التوثيق

بقلم Fraser Hardy

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

نقلتم زرًا واحدًا. والآن تعرض 14 مقالة مساعدة التصميم القديم، وعلى أحدهم أن يسجّل الدخول ويجد حساب العرض التجريبي الصحيح ويغيّر حجم النافذة ويعيد التقاط كل صورة. لا أحد يريد هذه المهمة، فلا تُنجز، وتبدأ الوثائق بالكذب بصمت.

الحل هو التوقف عن التقاط لقطات شاشة المنتج يدويًا. لإنشاء لقطات شاشة للمنتج تلقائيًا، اكتبوا نصًا برمجيًا يسجّل الدخول إلى حساب تجريبي مهيأ ببيانات جاهزة، ويزور كل صفحة في متصفح بلا واجهة (headless) بحجم ثابت، ويلتقط عناصر محددة (لا الشاشة كلها) بدقة مضاعفة 2x، ويُخفي كل ما يتغير بين مرة وأخرى، ويحفظ كل صورة تحت اسم ملف ثابت. ثم شغّلوا هذا النص في CI كلما تغيرت الواجهة. وPlaywright ينجز كل ذلك في نحو 60 سطرًا.

وفيما يلي النص الذي سنستخدمه فعلًا، والتفاصيل التي تجعل المخرجات متسقة، والأجزاء التي ما زالت تحتاج إلى إنسان.

لماذا تتقادم لقطات شاشة المنتج اليدوية

تفشل اللقطات المصنوعة يدويًا لأسباب مملة:

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

ما تحتاجون إليه قبل كتابة أي شيفرة

ثلاثة أمور تجعل لقطات شاشة التوثيق الآلية تعمل. وإذا تخطيتم أيًّا منها حصلتم على مخرجات غير مستقرة وقبيحة.

1. حساب تجريبي مهيأ ببيانات جاهزة

يحتاج نصكم البرمجي إلى تسجيل الدخول إلى حساب يبدو دائمًا بالشكل نفسه: اسم الشركة نفسه، والمشاريع الاثنا عشر نفسها، وزملاء وهميون بأسماء معقولة. اكتبوا نصًا لتهيئة البيانات (scripts/seed-demo.ts أو ما يناسب منصتكم) يمسح هذا الحساب ويعيد إنشاءه. الواقعية مهمة. فلوحة تحكم مليئة بعبارات “Test Project 1” و”asdf” تبدو معطلة في مقالة مساعدة.

2. محددات ثابتة للعناصر التي تلتقطونها

ستلتقطون لقطات لعناصر، فتحتاجون إلى طريقة موثوقة للعثور عليها. فئات CSS من Tailwind أو CSS-in-JS تتغير باستمرار. أضيفوا بدلًا منها خاصية مخصصة:

<section data-docs="billing-summary">...</section>

هي لا تكلف شيئًا، وتصمد أمام إعادة الهيكلة، وتقول لكل مهندس “هذا العنصر يظهر في الوثائق، فكّر قبل أن تحذفه.”

3. قائمة لقطات

قائمة بسيطة بكل صورة تستخدمها وثائقكم: أي صفحة، وأي عنصر، وما يجب إخفاؤه، واسم ملف المخرجات. احتفظوا بها في الشيفرة، بجانب النص البرمجي. وهذه القائمة هي أيضًا إجابتكم لاحقًا عن “أي اللقطات تعرض صفحة الفوترة؟“

نص Playwright يلتقط لقطات الشاشة ويعمل فعلًا

Playwright هو أفضل أداة لهذا اليوم. فهو يقود Chromium أو Firefox أو WebKit حقيقيًا، ويستطيع التقاط لقطة لعنصر واحد، وفيه خيارات مدمجة للإخفاء وتجميد الحركات.

أولًا، سجّلوا الدخول مرة واحدة واحفظوا الجلسة ليبدأ كل تشغيل للقطات وأنتم مسجلون الدخول:

// scripts/docs-login.mjs
import { chromium } from 'playwright';

const BASE_URL = process.env.BASE_URL ?? 'http://localhost:3000';

const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto(`${BASE_URL}/login`);
await page.getByLabel('Email').fill(process.env.DEMO_EMAIL);
await page.getByLabel('Password').fill(process.env.DEMO_PASSWORD);
await page.getByRole('button', { name: 'Sign in' }).click();
await page.waitForURL('**/dashboard');
await page.context().storageState({ path: '.auth/demo.json' });
await browser.close();

ثم نص اللقطات نفسه:

// scripts/docs-screenshots.mjs
import { chromium } from 'playwright';
import { mkdir } from 'node:fs/promises';

const BASE_URL = process.env.BASE_URL ?? 'http://localhost:3000';
const OUT_DIR = 'docs/images';

const shots = [
  {
    name: 'dashboard-overview',
    path: '/dashboard',
    element: '[data-docs="overview-panel"]',
    mask: ['[data-docs="last-synced"]', '[data-docs="avatar"]'],
  },
  {
    name: 'billing-summary',
    path: '/settings/billing',
    element: '[data-docs="billing-summary"]',
  },
  {
    name: 'invite-teammate-dialog',
    path: '/settings/team',
    element: '[role="dialog"]',
    before: (page) => page.getByRole('button', { name: 'Invite teammate' }).click(),
  },
];

const browser = await chromium.launch();
const context = await browser.newContext({
  storageState: '.auth/demo.json',
  viewport: { width: 1280, height: 800 },
  deviceScaleFactor: 2,
  colorScheme: 'light',
  locale: 'en-US',
  timezoneId: 'America/New_York',
  reducedMotion: 'reduce',
});
const page = await context.newPage();

// Every "Updated 3 minutes ago" and date picker now shows the same moment.
await page.clock.setFixedTime(new Date('2026-03-02T10:00:00'));

await mkdir(OUT_DIR, { recursive: true });

for (const shot of shots) {
  await page.goto(BASE_URL + shot.path);
  if (shot.before) await shot.before(page);

  const target = page.locator(shot.element);
  await target.waitFor({ state: 'visible' });

  await target.screenshot({
    path: `${OUT_DIR}/${shot.name}.png`,
    animations: 'disabled',
    caret: 'hide',
    mask: (shot.mask ?? []).map((selector) => page.locator(selector)),
    maskColor: '#e3d4ff',
    // Hide things that should never appear in docs.
    style: '#chat-widget, .cookie-banner, .dev-toolbar { display: none !important; }',
  });

  console.log(`saved ${shot.name}.png`);
}

await browser.close();

شغّلوه بالأمر node scripts/docs-login.mjs && node scripts/docs-screenshots.mjs على تطبيقكم المحلي أو على نسخة تجريبية (staging) مهيأة بالحساب التجريبي. وستحصلون على مجلد من صور PNG واضحة بأسماء مطابقة تمامًا لقائمة اللقطات.

المراحل الأربع لمسار أتمتة لقطات الشاشة: تهيئة البيانات التجريبية، وتحديد قائمة اللقطات، وتشغيلها في CI عند الدمج أو ليليًا، وظهور الصور المتغيرة كفروقات قابلة للمراجعة في الوثائق

الإعدادات التي تجعل لقطات الشاشة متسقة

معظم القيمة في حفنة من الخيارات. وهذا سبب وجود كل منها.

إطار عرض ثابت (viewport). الحجم 1280x800 يعني أن التخطيط ينكسر عند النقاط نفسها في كل مرة. اختاروا حجمًا واحدًا والتزموا به في كل صورة حتى لا يبدو مركز مساعدتكم كملصق مجمّع.

deviceScaleFactor: 2. يعرض هذا بكثافة شاشات ريتينا، فيصبح عنصر بعرض 600 بكسل صورة بعرض 1200 بكسل. وتبدو حادة على الحواسيب المحمولة والهواتف الحديثة، ويمكنكم عرضها بنصف الحجم في المقالة. وتكبر الملفات؛ مرّروها عبر أداة تحسين مثل oxipng أو حوّلوها إلى WebP إن كان ذلك يهمكم.

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

إخفاء المحتوى الديناميكي. كل ما يختلف بين تشغيلين دون تغيير في الشيفرة هو ضجيج: الطوابع الزمنية النسبية، والعدادات الحية، و”3 أشخاص متصلون”، وألوان الصور الرمزية العشوائية، ونصيحة اليوم المتغيرة. يرسم الخيار mask في Playwright مربعًا مصمتًا فوق تلك العناصر. وفضّلوا إصلاح البيانات من المصدر (أسماء مهيأة سلفًا، وساعة مجمدة) وأخفوا فقط ما لا تتحكمون فيه.

ساعة ولغة ومنطقة زمنية مجمدة. يثبّت page.clock.setFixedTime قيمة Date.now()، فتقول عبارة “مستحق خلال يومين” الشيء نفسه إلى الأبد. وتمنع اللغة والمنطقة الزمنية مشغّل CI في منطقة أخرى من عرض 02/03/2026 بدل 3/2/2026.

الحركات معطلة والمؤشر مخفي. قد يظهر تلاشٍ غير مكتمل أو مؤشر وامض في تشغيل ولا يظهر في التالي.

مقارنة قبل وبعد: لقطة خام فيها طابع زمني حي وعنوان بريد حقيقي وصورة رمزية عشوائية، بجانب اللقطة نفسها وقد أُخفيت تلك المناطق واستُبدل البريد ببيانات تجريبية

إعادة تشغيل اللقطات في CI

النص الذي عليكم أن تتذكروا تشغيله أفضل قليلًا فقط من فعل ذلك يدويًا. ضعوه في CI.

أبسط صيغة: عند كل دمج في main (أو ليليًا إذا كانت مجموعة اختباراتكم بطيئة)، شغّلوا التطبيق، وهيئوا الحساب التجريبي، وشغّلوا النص، وافتحوا طلب سحب إذا تغيرت أي صورة. يعرض Git فروقات الصور جنبًا إلى جنب على GitHub، فيستطيع المراجع أن يلقي نظرة على “billing-summary.png changed” ويتأكد أنه تغيير مقصود.

# .github/workflows/docs-screenshots.yml
name: Docs screenshots
on:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  capture:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci
      - run: npx playwright install --with-deps chromium
      - run: npm run seed:demo
      - run: npm run start &
      - run: npx wait-on http://localhost:3000
      - run: node scripts/docs-login.mjs && node scripts/docs-screenshots.mjs
        env:
          DEMO_EMAIL: ${{ secrets.DOCS_DEMO_EMAIL }}
          DEMO_PASSWORD: ${{ secrets.DOCS_DEMO_PASSWORD }}
      - uses: peter-evans/create-pull-request@v6
        with:
          branch: docs/screenshots
          title: "Update docs screenshots"
          add-paths: docs/images

وتحذير صريح واحد: تُعرض الخطوط بشكل مختلف قليلًا على macOS وLinux. فإذا جاءت بعض اللقطات من حاسوبكم المحمول وبعضها من CI، فسيُظهر كل تشغيل صورًا “متغيرة” لم تتغير فعلًا. ولّدوها في مكان واحد فقط (CI، أو صورة Docker الرسمية لـ Playwright محليًا) فتبقى الفروقات هادئة.

أين تقصر لقطات الشاشة المبرمجة

هذا النهج ممتاز، ويظل مع ذلك عملًا. كونوا واقعيين بشأنه:

وثمة خيارات أخرى. لدى Cypress الأمر cy.screenshot() ويعمل جيدًا إذا كان فريقكم يعيش في Cypress أصلًا. أما Puppeteer فأدنى مستوى ويركز على Chromium. وshot-scraper غلاف أوامر مفيد حول Playwright إذا فضلتم الاحتفاظ بملف YAML بدل نص برمجي. وللقطات التسويقية لمرة واحدة، فأداة يدوية مثل CleanShot X بحجم نافذة ثابت لا بأس بها بصراحة. ويؤتي المسار المبرمج ثماره حين تكون لديكم أكثر من بضع عشرات من الصور التي ينبغي أن تبقى حديثة.

أتمتة لقطات الشاشة دون كتابة النص البرمجي

هذا هو الجزء من المهمة الذي بنينا Ellie Docs ليرفعه عن عاتقكم. تربطون مستودع GitHub، وتقرأ Ellie الشيفرة لتحدد ميزاتكم والشاشات الموجهة للمستخدم. ثم تشغّل تطبيقكم في بيئة معزولة (sandbox)، وتسجّل الدخول كمستخدم اختبار، وتلتقط لقطات شاشة حقيقية للمنتج بعد تسجيل الدخول، وتضعها مباشرة في مقالات المساعدة التي تصوغها.

محرر مقالات Ellie Docs يعرض مقالة منشورة للبدء وفيها لقطة شاشة ملتقطة تلقائيًا لشاشة استقبال التطبيق، مع لوحة Screenshots تسرد الصورة الملتقطة

ولأن كل مقالة مرتبطة بالميزات التي تصفها، فإن طلب سحب مدموجًا يغيّر إحدى هذه الميزات يُبلَّغ عنه مقابل المقالات الصحيحة، وتراجعون التحديث المقترح قبل أن يُنشر أي شيء. فلا تصونون قائمة لقطات ولا ملف محددات.

مقالة مركز مساعدة منشورة فيها لقطة شاشة مدمجة لشاشة ربط صندوق الوارد في المنتج

وإذا كنتم تستمتعون بامتلاك نص Playwright، فاحتفظوا به. إنه إعداد جيد. وإذا فضلتم أن تُعالج اللقطات والمقالات المحيطة بها والصيانة عنكم، فهذا ما تفعله Ellie. وكتابة الكلمات حول هذه الصور حرفة قائمة بذاتها أيضًا؛ راجعوا كيف تكتبون مقالات مركز المساعدة التي يستخدمها الناس فعلًا.

أسئلة شائعة

ما الدقة المناسبة للقطات شاشة التوثيق؟ التقطوا بدقة 2x (deviceScaleFactor: 2) من إطار عرض ثابت بعرض نحو 1280 بكسل، ثم اعرضوها بنصف الحجم. فتحصلون على صور حادة على شاشات ريتينا دون تخطيطات ضخمة.

هل ألتقط الصفحة كلها أم جزءًا واحدًا؟ عادةً جزءًا واحدًا. اقتصّوا على العنصر الذي تتناوله الخطوة، مع قليل من السياق المحيط ليجده القارئ. واستخدموا لقطات الصفحة الكاملة بقلة، لمواضع “هذا هو التخطيط العام”.

كيف أبقي بيانات العملاء الحقيقية خارج لقطات الشاشة؟ لا تلتقطوا أبدًا من حسابات الإنتاج. استخدموا حسابًا تجريبيًا مهيأ بأسماء وهمية وعناوين بريد من نطاق example.com، وأخفوا ما لا تستطيعون تهيئته، مثل أدوات الأطراف الثالثة.

كم مرة ينبغي أن تُشغَّل اللقطات الآلية؟ عند كل دمج في main إن كان التشغيل سريعًا، وليليًا إن لم يكن. والمقصود ألا يضطر أحد إلى التذكر.

إذا أردتم أن يُنجز لكم هذا، فـجرّبوا Ellie Docs مجانًا. اربطوا مستودعًا وستحصلون على مركز مساعدة بلقطات شاشة حقيقية لتطبيقكم، دون حاجة إلى بطاقة.