یک دکمه در صفحه اصلی درست دیده می‌شود، اما در حالت غیرفعال عنوان آن کم‌خوانا است و متن بلند فارسی از قاب بیرون می‌زند. بررسی فقط حالت عادی، این تفاوت‌ها را پنهان می‌کند. Storybook محیطی برای نمایش مؤلفه در حالت‌های مشخص فراهم می‌کند تا تیم بتواند درباره قرارداد آن حرف بزند. وجود story به‌تنهایی به معنی آزمون بصری اجراشده یا مناسب بودن رفتار در کل محصول نیست.
برای استفاده مفید، ابتدا حالت‌های واقعی مؤلفه را فهرست کنید: عادی، در انتظار، غیرفعال، خطا و متن طولانی. هرکدام باید از نیاز محصول بیاید. صدها story با تفاوت‌های جزئی و بی‌هدف می‌تواند مرور را دشوار کند. یک مجموعه محدود و روشن که مرزهای رفتار را نشان دهد، از نمایش تزئینی همه ترکیب‌های ممکن قابل استفاده‌تر است.
Story یک موقعیت مشخص است
مستندات Args نحوه معرفی ورودی‌های story را توضیح می‌دهد. هر story می‌تواند ترکیب معینی از props و زمینه را ارائه کند. این ترکیب باید نام قابل فهم داشته باشد. «Disabled» حالت مشخصی است؛ نامی مانند «نسخه دوم» بدون توضیح بعداً کمک کمی می‌کند. ورودی ثابت باعث می‌شود اعضای تیم همان موقعیت را ببینند و تفاوت را با زمینه معلوم بررسی کنند.
Story فقط screenshot نیست. می‌توان با مؤلفه تعامل کرد، ورودی‌ها را تغییر داد و رفتار را در زمینه تعریف‌شده دید. با این حال، صفحه کامل محصول ممکن است داده، route و providerهای دیگری داشته باشد. استقلال توسعه به معنی حذف مسئولیت بررسی ترکیب نیست. حالت‌هایی را که به زمینه وابسته‌اند به صورت صریح معرفی کنید تا استفاده‌کننده مؤلفه دامنه نمایش را با رفتار نهایی اشتباه نگیرد.
نصب را با پروژه هدف هماهنگ کنید
راهنمای نصب Storybook اکنون فرمان npm create storybook@latest را برای راه‌اندازی معرفی می‌کند. پیش‌نیازها و انتخاب‌های نصب به نسخه و framework مربوط‌اند؛ عبارت «تقریباً همه چیز خودکار» تضمین درستی تنظیم‌های هر پروژه نیست. در مخزن موجود، تغییر package، script و پیکربندی باید با ابزار فعلی مرور شود. مثال قدیمی init را بدون توجه به نسخه به عنوان تنها روش جاری معرفی نکنید.
برای نمونه مستقل، Node.js 24 و npm سازگار را در نظر بگیرید. با npm create vite@latest story-demo -- --template react یک پروژه React بسازید، وارد پوشه آن شوید و npm install را اجرا کنید. سپس npm create storybook@latest را در ریشه همین پروژه اجرا و تنظیم React با Vite را انتخاب کنید. setup تولیدشده باید شامل مسیر فایل‌های stories در src باشد و lockfile نگهداری شود.
نمونه کامل سه فایل
سه فایل زیر را به نام ActionButton.jsx، action-button.css و ActionButton.stories.jsx در پوشه src/stories ذخیره کنید. فایل CSS در مؤلفه import می‌شود، بنابراین وابستگی ظاهری معرفی‌نشده ندارد. تصویر، فونت یا API خارجی لازم نیست. مؤلفه یک button واقعی با label، disabled و onClick است. نمونه عملیات شبکه‌ای یا انتظار async را پیاده نمی‌کند و درباره آن‌ها ادعای آزمون ندارد.
import React from 'react';
import './action-button.css';
export function ActionButton({ label = 'ادامه', disabled = false, onClick }) {
return <button className="action-button" type="button" disabled={disabled} onClick={onClick}>{label}</button>;
}
کلاس action-button در markup همان مؤلفه وجود دارد و selectorهای CSS به همان عنصر مربوط‌اند. متن فارسی می‌تواند چندخطی شود و ارتفاع ثابت ندارد. focus-visible و disabled ظاهر جدا دارند، چون محل تعامل و امکان تعامل دو معنی متفاوت‌اند. رنگ وضعیت تنها راه فهم نام عمل نیست؛ label متن واقعی دکمه را فراهم می‌کند. این قواعد برای نمونه آموزشی‌اند و باید در سیستم طراحی واقعی با tokenهای پروژه هماهنگ شوند.
.action-button{box-sizing:border-box;max-width:100%;font-family:Tahoma,Arial,sans-serif;font-size:1rem;line-height:1.8;padding:.75rem 1.1rem;background:#173f78;color:#fff;border:2px solid #173f78;border-radius:.4rem;cursor:pointer;overflow-wrap:anywhere}
.action-button:focus-visible{outline:3px solid #946000;outline-offset:4px}
.action-button:disabled{background:#e4e8ee;border-color:#768398;color:#35445a;cursor:not-allowed}
در فایل stories، سه موقعیت عادی، غیرفعال و عنوان طولانی معرفی شده‌اند. fn از storybook/test یک تابع مشاهده‌پذیر برای callback می‌سازد، مطابق راهنمای Actions. این تابع در نمونه اثر کسب‌وکار ندارد. مشاهده فراخوانی آن می‌گوید callback صدا زده شده، نه اینکه یک سفارش یا ذخیره واقعی موفق بوده است. از این مرز برای جلوگیری از برداشت نامناسب استفاده کنید.
import { fn } from 'storybook/test';
import { ActionButton } from './ActionButton';
export default { title: 'Educational/ActionButton', component: ActionButton, args: { label: 'ادامه', disabled: false, onClick: fn() } };
export const Default = {};
export const Disabled = { args: { disabled: true, label: 'فعلاً در دسترس نیست' } };
export const LongLabel = { args: { label: 'ادامه و مرور اطلاعات واردشده پیش از تأیید نهایی' } };
با npm run storybook از همان پروژه، محیط نمایش راه‌اندازی می‌شود و نشانی محلی آن در خروجی ابزار دیده می‌شود. برای خروجی ثابت از script ساختی که installer معرفی کرده استفاده کنید. این راهنما فایل‌ها و روش اجرا را ارائه می‌کند؛ وجود کد نمونه به معنی ثبت نتیجه یک اجرای آزمون نیست. اگر story پیدا نمی‌شود، مسیر glob پیکربندی و نام فایل را با ساختار واقعی مقایسه کنید.
Controls و مستندات قرارداد
Controls می‌تواند تغییر label یا disabled را آسان کند، ولی دامنه معتبر props باید معلوم باشد. اگر یک مقدار فقط در ترکیب خاصی مجاز است، ابزار تغییر آزاد آن الزاماً رفتار محصول را نمایندگی نمی‌کند. توضیح ورودی‌ها، مقدار پیش‌فرض و محدودیت‌ها را کنار مؤلفه نگه دارید. مستندات خودکار می‌توانند از metadata کمک بگیرند، اما دلیل انتخاب و موارد منع استفاده را از ذهن تیم استخراج نمی‌کنند.
برای مؤلفه حساس، نمونه نامناسب را هم توضیح دهید. دکمه حذف با عنوان عمومی «باشه» ممکن است از نظر فنی معتبر باشد ولی قرارداد تجربه را نقض کند. Storybook محل خوبی برای توافق درباره نام، اندازه و حالت‌هاست. راهنمای Dialog نمونه‌ای از قراردادی است که focus و نتیجه هر دکمه اهمیت دارند و نمایش یک قاب به‌تنهایی آن را کامل نمی‌کند.
تست بصری با دیدن story فرق دارد
راهنمای Visual Testing جریان ثبت و مقایسه تصویر و انتخاب مرجع را شرح می‌دهد. برای مقایسه معنادار، viewport، فونت، داده و حالت باید قابل تکرار باشند. تغییر تصویر می‌تواند اصلاح مطلوب یا regression باشد؛ ابزار تصمیم محصول را به‌تنهایی نمی‌گیرد. هر تفاوت باید با انتظار و دلیل تغییر مرور شود و مرجع تازه بی‌خبر پذیرفته نشود.
اگر سرویس بیرونی برای snapshot استفاده می‌کنید، داده‌ای که ارسال می‌شود و سطح دسترسی پروژه باید روشن باشد. مؤلفه دارای اطلاعات واقعی حساب را بی‌دلیل در نمونه عمومی قرار ندهید. برای محتوای آموزشی از داده ساختگی با برچسب مناسب استفاده کنید. هزینه و قرارداد سرویس هم مستقل از خود Storybook است. نصب محیط توسعه به معنی فعال شدن همه مسیرهای آزمون و انتشار نیست.
آزمون تعامل سؤال جدا دارد
یک آزمون تعامل می‌تواند مسیر تایپ، انتخاب و نتیجه قابل مشاهده را بررسی کند. Play function برای نمایش بعضی جریان‌ها مفید است، اما باید حالت آغاز و وابستگی‌ها معلوم باشند. اگر callback فقط Mock است، نتیجه سرور بررسی نشده است. درباره query و رفتار مؤلفه، راهنمای Testing Library نمونه کامل دارد. نام آزمون باید همان دامنه محدود را بیان کند.
خطا و انتظار را با Mock معتبر و داده متناسب نشان دهید. یک وضعیت loading که هیچ‌وقت تمام نمی‌شود می‌تواند story جدا برای ظاهر باشد؛ نباید به عنوان جریان کامل دریافت معرفی شود. اگر چند مؤلفه با هم کار می‌کنند، نمونه ترکیبی ممکن است لازم باشد. تکرار تمام جریان محصول در هر story هم می‌تواند هزینه نگهداری بسازد. مرز میان مؤلفه و مسیر کامل را آگاهانه انتخاب کنید.
Provider و زمینه را صریح کنید
Theme، ترجمه، route و داده ممکن است به decorator یا wrapper نیاز داشته باشند. نام و رفتار آن‌ها باید در تنظیمات پیدا شود. اگر مؤلفه بدون provider شکست می‌خورد، این پیش‌نیاز بخشی از API آن است. decorator سراسری برای همه داستان‌ها ممکن است وابستگی نامرتبط تحمیل کند. فقط زمینه لازم را فراهم کنید و برای حالت‌های متفاوت، ورودی روشن و قابل تکرار نگه دارید.
فونت و جهت فارسی نیز باید به‌صورت واقعی تعریف شوند. نمونه این مقاله فونت system fallback دارد و asset ناشناخته وارد نمی‌کند. در پروژه واقعی، مسیر فونت و سیاست بارگذاری باید با محیط نمایش و محصول سازگار باشند. راهنمای کارت درباره متن بلند و اطلاعات لازم توضیح دارد. محتوای کوتاه نمونه می‌تواند مشکلات واقعی زبان و چیدمان را پنهان کند.
نگهداری مجموعه داستان‌ها
وقتی prop یا رفتار تغییر می‌کند، storyهای مربوط باید همراه همان change اصلاح شوند. مجموعه‌ای که فقط ظاهر قدیمی را نگه داشته، مستندات گمراه‌کننده می‌سازد. برای هر حالت مسئول و هدف مشخص کنید و داستان تکراری بی‌نیاز را کنار بگذارید. در مرور تغییر، علت اختلاف ظاهر و رفتار را توضیح دهید. نام یک ابزار ضروری بودن آن برای هر تیم را ثابت نمی‌کند؛ هزینه نگهداری باید با استفاده واقعی تناسب داشته باشد.
Storybook زمانی مفید است که حالت‌های قابل بحث و قابل تکرار فراهم کند. تیم باید بداند چه چیزی فقط نمایش است، چه چیزی با تعامل بررسی می‌شود و کدام نتیجه به محیط محصول وابسته است. فایل‌های کامل، props روشن و داده محدود کمک می‌کنند همین مرز حفظ شود. مستندات مناسب علاوه بر شکل مؤلفه، شیوه استفاده و شرایط شکست یا منع استفاده از آن را نیز توضیح می‌دهند.
هنوز دیدگاهی ثبت نشده
اولین نفری باشید که نظر می‌دهد!