فیلد عدد — Number
فیلد Number در Form Builder GraphBPMS برای دریافت و ذخیره مقدار عددی استفاده می‌شود. طراح فرم می‌تواند نوع ذخیره، مقدار اولیه، حدود مجاز، گام تغییر، فرمت نمایش و نوع فیلد (Mode) را تعیین کند. همین فیلد می‌تواند به‌صورت اسلایدر یا Rating نمایش داده شود و در صورت نیاز با یک ستون از جدول دیگر ارتباط Foreign Key داشته باشد.
در این آموزش
کنترل مقدار، نوع و دامنه ورودی
تنظیمات اصلی ورودی عددی در تب تنظیمات اختصاصی قرار دارند. این گزینه‌ها مقدار اولیه، ساختار ذخیره، محدوده قابل قبول و شیوه نمایش یا تغییر مقدار را کنترل می‌کنند.
- مقدار پیش‌فرض: مقداری است که به‌صورت اولیه در کنترل قرار می‌گیرد.
- نوع: دامنه و ساختار ذخیره را میان Int، Byte، Decimal، Long، Float، Tiny و Small تعیین می‌کند.
- بازه حداقل: حداقل مقدار مجاز را تعیین می‌کند. اگر کاربر مقدار کمتری وارد کند، خطای اعتبارسنجی نمایش داده می‌شود.
- بازه حداکثر: حداکثر مقدار مجاز را تعیین می‌کند. اگر کاربر مقدار بیشتری وارد کند، خطای اعتبارسنجی نمایش داده می‌شود.
- گام: مشخص می‌کند هنگام استفاده از دکمه‌های افزایش/کاهش (Spin Buttons)، کلیدهای جهت‌دار بالا/پایین یا چرخ ماوس، مقدار کنترل چه اندازه تغییر کند. مقدار پیش‌فرض این گزینه 1 است.
- فراخوانی رخداد بعد از تغییر مقدار (onChangeValue): زمانی که مقدار فیلد تغییر کند، فیلدها و رویدادهای انتخاب‌شده در این بخش دوباره اجرا می‌شوند.
- نوع فیلد (Mode): کنترل را در حالت متن، عدد یا شماره تلفن نمایش می‌دهد.
نمونه تنظیمات: در نمای موجود، نوع روی Int و نوع فیلد (Mode) روی متن (پیش‌فرض) قرار دارد.
قالب‌بندی نمایش عدد با Format
فرمت مشخص می‌کند مقدار عددی چگونه به کاربر نمایش داده شود و نحوه ورود مقدار را نیز متناسب با الگوی انتخاب‌شده کنترل می‌کند. برای Custom Formatهای عددی، علامت‌های زیر کاربرد اصلی را دارند:
| علامت | کاربرد |
|---|---|
| 0 | رقم اجباری؛ اگر رقم وجود نداشته باشد، صفر نمایش می‌دهد. |
| # | رقم اختیاری. |
| , | جداکننده گروه ارقام / هزارگان. |
| . | جداکننده بخش اعشاری. |
| % | نمایش درصد و ضرب مقدار در 100. |
| ; | تعریف الگوی جداگانه برای مقدار مثبت و منفی. |
| '...' | نمایش علامت یا متن خاص به‌صورت Literal در موارد لازم. |
در کنار Custom Format، چند Format آماده برای کاربردهای عددی رایج قابل استفاده‌اند:
| Format | کاربرد | مثال کوتاه |
|---|---|---|
| fixedPoint | نمایش عدد با قالب عددی ثابت. | برای مقداری مانند 12.5 که باید به‌صورت عدد قالب‌بندی‌شده نمایش داده شود. |
| decimal | نمایش مقدار به‌صورت عدد ده‌دهی. | برای مقادیر معمول عددی دارای بخش صحیح یا اعشاری. |
| percent | نمایش مقدار به‌صورت درصد. | مقدار 0.15 به‌صورت درصدی نمایش داده می‌شود. |
| currency | نمایش مقدار پولی. | برای مبلغی مانند 14500.55؛ نماد و جداکننده‌های واقعی می‌توانند به محیط وابسته باشند. |
این Setting مجموعه‌ای از نام‌های Format را می‌پذیرد، از جمله billions، currency، day، decimal، exponential، fixedPoint، largeNumber، longDate، longTime، millions، millisecond، month، monthAndDay، monthAndYear، percent، quarter، quarterAndYear، shortDate، shortTime، thousands، trillions، year، dayOfWeek، hour، longDateLongTime، minute، second و shortDateShortTime.
برای فیلد Number، تمرکز عملی روی قالب‌بندی عددی است. نام‌های Date/Time مانند day، month، year، shortDate، longDate، shortTime و موارد مشابه در فهرست عمومی Format قرار دارند؛ وجود آن‌ها به‌تنهایی مبنای تعیین رفتارشان روی مقدار Number نیست.
همچنین گزینه‌های largeNumber، thousands، millions، billions و trillions در فهرست Format دیده می‌شوند، اما نباید بدون بررسی Build مقصد به‌عنوان قالب آماده و قطعی فیلد Number در نظر گرفته شوند.
[وابسته به نسخه/استقرار] رفتار Formatهای Large Number و Custom Formatها در Build مقصد باید در صورت اختلاف نسخه یا Deployment بررسی شود.
مثال‌های کاربردی فرمت عدد
جدول زیر الگوهای رایج را با مقدار نمونه و نتیجه نمایشی نشان می‌دهد:
| کاربرد | مقدار نمونه | Format | نتیجه نمایشی | توضیح |
|---|---|---|---|---|
| جداکننده هزارگان | 1234567 | #,##0 | 1,234,567 | برای مبلغ، تعداد، جمع کل و اعداد بزرگ با جداکننده گروه ارقام. |
| هزارگان با دو رقم اعشار ثابت | 1234567.5 | #,##0.00 | 1,234,567.50 | همیشه دو رقم اعشار نمایش داده می‌شود. |
| هزارگان با اعشار اختیاری | 1234567.5 | #,##0.## | 1,234,567.5 | حداکثر دو رقم اعشار نمایش داده می‌شود و صفرهای غیرضروری نمایش داده نمی‌شوند. |
| حداکثر سه رقم اعشار | 123456.789 | #,##0.### | 123,456.789 | مناسب اندازه‌گیری، وزن، نرخ یا داده‌هایی که ممکن است تا سه رقم اعشار داشته باشند. |
| دو رقم اعشار ثابت بدون هزارگان | 12.5 | #0.00 | 12.50 | دو رقم اعشار را ثابت نگه می‌دارد. |
| اعشار اختیاری بدون هزارگان | 12.5 12 |
#0.## | 12.5 12 |
حداکثر دو رقم اعشار نمایش داده می‌شود؛ برای مقدار صحیح، اعشار غیرضروری اضافه نمی‌شود. |
| درصد ساده | 0.15 | #0% | 15% | مقدار در 100 ضرب می‌شود و علامت درصد نمایش داده می‌شود. |
| درصد با حداکثر دو رقم اعشار | 0.01234 | #0.##% | 1.23% | درصد با حداکثر دو رقم اعشار نمایش داده می‌شود. |
| نمایش علامت درصد بدون تبدیل مقدار | 0.01234 | #0.##'%' | 0.01% | % فقط به‌صورت علامت نمایشی استفاده می‌شود و مقدار در 100 ضرب نمی‌شود. |
| مبلغ با علامت Currency | 14500.55 | $ #,##0.## | $ 14,500.55 | نمونه‌ای از Pattern پولی؛ واحد پول واقعی محیط می‌تواند متفاوت باشد. |
| مبلغ با واحد ریال | 1250000 | #,##0 ریال | 1,250,000 ریال | یک Custom Format کاربردی برای افزودن واحد ریال به نمایش مقدار. |
| مبلغ با واحد تومان | 1250000 | #,##0 تومان | 1,250,000 تومان | فقط نحوه نمایش را تغییر می‌دهد و تبدیل عددی ریال به تومان انجام نمی‌دهد. |
| وزن | 3.14 | #0.## kg | 3.14 kg | نمایش مقدار همراه با واحد وزن. |
| فاصله | 1250 | #,##0 km | 1,250 km | نمایش مقدار همراه با واحد فاصله و جداکننده گروه ارقام. |
| تعداد با واحد متنی | 2500 | #,##0 نفر | 2,500 نفر | نشان می‌دهد متن ثابت را می‌توان به انتهای Format اضافه کرد. |
| عدد منفی با پرانتز | مقدار مثبت: 1234 مقدار منفی: -1234 |
#,##0;(#,##0) | مثبت: 1,234 منفی: (1,234) |
بخش قبل از ; الگوی مقدار مثبت و بخش بعد از آن الگوی مقدار منفی است. |
| نمایش حسابداری با اعشار | -2314.12 | #,##0.00;(#,##0.00) | (2,314.12) | برای نمایش مالی یا حسابداری که عدد منفی با پرانتز مشخص می‌شود. |
توجه — درصد: % مقدار را در 100 ضرب می‌کند. اگر فقط نمایش علامت درصد بدون تبدیل مقدار لازم است، % باید به‌صورت Literal استفاده شود.
نکته — ریال و تومان: افزودن کلمه «ریال» یا «تومان» به Format فقط نحوه نمایش مقدار را تغییر می‌دهد و هیچ تبدیل عددی بین ریال و تومان انجام نمی‌دهد.
نکته — Locale: علامت واقعی جداکننده هزارگان و اعشار می‌تواند با Locale محیط متفاوت باشد؛ الگوی Format نقش جداکننده گروه و اعشار را مشخص می‌کند.
نمایش فیلد به‌صورت اسلایدر
با فعال‌کردن نمایش اسلایدری، فیلد عدد به‌صورت اسلایدری یا بازه‌ای نمایش داده می‌شود و گزینه‌های مرتبط با بازه و مقدار اولیه در دسترس قرار می‌گیرند.
- بازه حداقل: مقدار حداقل اسلایدر را تنظیم می‌کند.
- بازه حداکثر: مقدار حداکثر اسلایدر را تنظیم می‌کند.
- مقدار پیش‌فرض: مقدار اولیه فیلد اسلایدری را تعیین می‌کند.
- اسلایدر درصدی: با فعال‌شدن این گزینه، اسلایدر به‌صورت درصدی نمایش داده می‌شود.
نمونه تنظیمات: حداقل 0، حداکثر 100 و مقدار پیش‌فرض 0 تنظیم شده و اسلایدر درصدی غیرفعال است.
نمایش مقدار به‌صورت Rating
با فعال‌کردن نمایش بصورت Rating، نحوه نمایش فیلد عددی به حالت Rating تغییر می‌کند.
- تعداد: تعداد آیکون‌های نمایشی Rating را تعیین می‌کند. مقدار پیش‌فرض 5 است.
- اندازه: اندازه آیکون‌های نمایشی را تعیین می‌کند. مقدار پیش‌فرض 30 است؛ یعنی اندازه آیکون‌ها 30px خواهد بود.
تنظیم مستقل هر آیکون Rating
برای هر آیکون نمایشی یک بخش بازشونده (Accordion) جدا در اختیار کاربر قرار می‌گیرد تا وضعیت فعال، غیرفعال و مقدار همان گزینه مستقل تنظیم شود:
- آیکون حالت فعال: آیکونی که هنگام فعال‌بودن آن گزینه نمایش داده می‌شود.
- رنگ حالت فعال: رنگ آیکون در حالت فعال را تعیین می‌کند.
- آیکون حالت غیرفعال: آیکونی که هنگام غیرفعال‌بودن آن گزینه نمایش داده می‌شود.
- رنگ حالت غیرفعال: رنگ آیکون در حالت غیرفعال را تعیین می‌کند.
- مقدار: وقتی آن گزینه فعال شود، مقدار تعیین‌شده برای آن در فیلد عددی قرار می‌گیرد.
نمونه تنظیمات: Rating با تعداد 5 و اندازه 30 تنظیم شده است. برای گزینه اول، آیکون حالت فعال fa fa-star، رنگ حالت فعال rgba(247, 201, 62, 1)، آیکون حالت غیرفعال fa fa-light fa-star، رنگ حالت غیرفعال rgba(207, 207, 207, 1) و مقدار 1 ثبت شده است.
ایجاد ارتباط با جدول دیگر
بخش ارتباط با یک جدول دیگر (Foreign Key) برای ایجاد ارتباط میان فیلد عددی و یک ستون از جدول دیگر استفاده می‌شود. با فعال‌کردن گزینه فعال، دو فیلد برای تعریف این ارتباط نمایش داده می‌شود:
- انتخاب جدول: جدول موردنظر را از دیتابیس انتخاب می‌کند.
- کلید خارجی: یک ستون از جدول انتخاب‌شده را تعیین می‌کند.
پس از تکمیل این دو مورد، در دیتابیس یک کلید خارجی میان این فیلد عددی و ستون انتخاب‌شده از جدول تعیین‌شده برقرار می‌شود.