Frontend Academy · درس

Storybook: القصص وعناصر التحكم والتوثيق

اكتب قصصًا لكل حالة من حالات المكوّن، واستخدم Controls لتعديل props تفاعليًا، وأنشئ صفحات Docs من JSDoc وargTypes

Storybook: القصص وعناصر التحكم والتوثيق درس مجاني في Frontend Academy على CoddyKit. هذا هو الدرس 1 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في Frontend Academy، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة Frontend Academy 4 دروس في المجموع.

ما هو Storybook؟

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

لماذا نستخدم Storybook؟

1) طوّر المكوّنات بمعزل عن التطبيق دون إعداد سياق للتطبيق. 2) راجع جميع الحالات بصرياً (التحميل، والخطأ، والفراغ). 3) يمكن للمصممين ومديري المنتجات استعراض الكتالوج. 4) ينشئ التوثيق. 5) يؤتمت اختبار التراجع البصري.

تثبيت Storybook

استخدم أداة التهيئة الرسمية — فهي تكتشف إطار العمل الذي تستخدمه وتُعدّ كل شيء.

npx storybook@latest init

# Adds:
#  .storybook/        config
#  src/stories/       example stories
#  scripts: 'storybook' and 'build-storybook'

npm run storybook   # opens http://localhost:6006

كتابة قصة (CSF 3.0)

تنسيق قصص المكوّنات 3: التصدير الافتراضي = البيانات الوصفية، والتصديرات المسماة = القصص.

// Button.stories.tsx
import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './Button';

const meta: Meta<typeof Button> = {
  title: 'Atoms/Button',
  component: Button,
  tags: ['autodocs']
};
export default meta;

type Story = StoryObj<typeof Button>;

export const Primary: Story = {
  args: { label: 'Save', variant: 'primary' }
};

export const Disabled: Story = {
  args: { label: 'Save', variant: 'primary', disabled: true }
};

قصص متعددة لكل مكوّن

اكتب قصة لكل حالة مهمة: الافتراضية، والتحويم، والتحميل، والخطأ، والفراغ، والممتلئة. يمكن للمراجعين التنقّل بينها ورؤية كل تنويع في لمحة.

export const Loading: Story = { args: { state: 'loading' } };
export const Error: Story    = { args: { state: 'error', message: 'Network failed' } };
export const Empty: Story    = { args: { items: [] } };
export const Populated: Story = { args: { items: mockItems } };

عناصر التحكّم (جدول Args)

يحوّل ملحق Controls في Storybook كائن args إلى عناصر تحكّم تفاعلية في نموذج. عدّل قيم الخصائص مباشرة في الواجهة لاختبار الحالات الطرفية.

const meta: Meta<typeof Button> = {
  component: Button,
  argTypes: {
    variant: {
      control: 'select',
      options: ['primary', 'secondary', 'danger']
    },
    onClick: { action: 'clicked' }
  }
};

ملحق Actions

استخدم action() لتسجيل استدعاءات معالجات الأحداث في لوحة Actions. وهذا مفيد لاختبار دوال الاستدعاء دون إعداد حالة حقيقية.

argTypes: {
  onClick: { action: 'clicked' },
  onChange: { action: 'changed' }
}

Autodocs — توثيق مُنشأ تلقائياً

أضف tags: ['autodocs'] إلى البيانات الوصفية؛ عندها ينشئ Storybook صفحة Docs تحتوي على جدول خصائص المكوّن وأوصافها وأمثلة قابلة للعرض.

MDX للتوثيق المتقدم

اكتب توثيق المكوّنات باستخدام MDX — وهو Markdown مع JSX مضمّن. اخلط الشرح النصي بأمثلة حيّة للمكوّنات.

{/* Button.mdx */}
import { Meta, Story, Canvas } from '@storybook/blocks';
import * as ButtonStories from './Button.stories';

<Meta of={ButtonStories} />

# Button

The primary action element.

## Variants
<Canvas of={ButtonStories.Primary} />
<Canvas of={ButtonStories.Secondary} />

Decorators — تغليف القصص بالسياق

غلّف القصص بموفّرات (Theme وRouter وRedux) باستخدام decorators.

export const decorators = [
  (Story) => (
    <ThemeProvider theme={lightTheme}>
      <Story />
    </ThemeProvider>
  )
];

اختبار التراجع البصري

يأخذ Chromatic (من فريق Storybook) لقطة شاشة لكل قصة عند كل commit، ثم يقارنها بالخط الأساسي. وبذلك يكتشف التراجعات البصرية تلقائياً.

نشر Storybook

ينشئ npm run build-storybook موقعاً ثابتاً في storybook-static/. انشره على Netlify أو Vercel أو GitHub Pages، ليحصل غير المطوّرين على كتالوج قابل لتصفّح المكوّنات.

اختبار سريع

ماذا يفعل إضافة tags: ['autodocs'] إلى البيانات الوصفية لقصة مكوّن في Storybook؟

مراجعة: Storybook

ورشة عمل معزولة لمكوّنات واجهة المستخدم. في CSF 3.0: التصدير الافتراضي = البيانات الوصفية، والتصديرات المسماة = القصص. استخدم argTypes لعناصر Controls، وaction() لتسجيل دوال الاستدعاء، وtags: ['autodocs'] لإنشاء التوثيق تلقائياً، وMDX للشرح الغني مع JSX. تحقن Decorators الموفّرات. استخدم Chromatic للتراجع البصري، وBuild-storybook للاستضافة الثابتة.

الأسئلة الشائعة

هل درس «Storybook: القصص وعناصر التحكم والتوثيق» مجاني؟

نعم — نص درس «Storybook: القصص وعناصر التحكم والتوثيق» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة Frontend Academy، انتقل إلى CoddyKit PRO. تتضمن دورة Frontend Academy 4 دروس في المجموع.

ماذا ستتعلم في «Storybook: القصص وعناصر التحكم والتوثيق»؟

اكتب قصصًا لكل حالة من حالات المكوّن، واستخدم Controls لتعديل props تفاعليًا، وأنشئ صفحات Docs من JSDoc وargTypes تتمرن على Frontend Academy مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.

هل أحتاج إلى خبرة سابقة لأبدأ Frontend Academy؟

لا تُشترط خبرة سابقة. Frontend Academy على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 1 من أصل 4.

كم من الوقت يستغرق درس «Storybook: القصص وعناصر التحكم والتوثيق»؟

معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.

هل يمكنني كتابة وتشغيل أكواد في درس Frontend Academy هذا؟

نعم. كل درس في Frontend Academy يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.

جميع الدروس في هذه الدورة

← العودة إلى Frontend Academy