راهنمای مقدماتی Numeral.Js — به زبان ساده

کتابخانه Numeral.Js به قالب‌بندی اعداد در جاوا اسکریپت کمک می‌کند. به وسیله این کتابخانه می‌توان مقادیر پولی را به شیوه‌ای خاص نمایش داد، اعداد بزرگ را خلاصه یا تبدیل کرد و یا اعداد را به عنوان بخش مهمی از وب قالب‌بندی نمود. در این راهنما به بررسی مقدماتی کتابخانه Numeral.Js می‌پردازیم.

کتابخانه Numeral.Js نه تنها امکان استفاده از فهرست بلندی از روش‌های قالب‌بندی و Locale-های داخلی خود را فراهم ساخته است، بلکه می‌توان قالب‌بندی‌های سفارشی نیز ایجاد کرد و Locale-های دیگری که ممکن است در این کتابخانه نباشند را به آن اضافه نمود. توضیحات خود را با روش ارجاع دادن به این کتابخانه آغاز می‌کنیم.

جاوا اسکریپت خالص

در زمانی که از کد جاوا اسکریپت خالص استفاده می‌کنید باید در زیر تگ Script در فایل HTML کد زیر را اضافه کنید:

<script src="numeral.min.js"></script>

به طور جایگزین می‌توان از یک CDN نیز به آن ارجاع داد.

فیلم آموزش جاوا اسکریپت JavaScript در فرادرس

کلیک کنید

کد مربوطه را در زیر آورده‌ایم.

<script src="//cdnjs.cloudflare.com/ajax/libs/numeral.js/2.0.6/numeral.min.js"></script>

کتابخانه‌های React/Vue

با اجرای دستور زیر:

npm install numeral

و سپس ایمپورت کردن پکیج numeral در هر کامپوننت، می‌توان از این کتابخانه در ری‌اکت یا ویو استفاده کرد:

npm install numeral
import numeral from 'numeral';

اکنون که به کتابخانه Numeral.Js ارجاع دادیم، می‌توانیم شروع به استفاده از آن بکنیم.

ایجاد یک Numeral

برای ایجاد یک وهله از Numeral.Js کافی است از دستور زیر استفاده کنید:

numeral(YOUR_NUMBER)

بدین ترتیب یک شیء numeral ایجاد می‌شود. اگر عدد داخل پرانتز (YOUR_NUMBER) ‌برابر با 1 باشد، ‌شیء numeral به صورت زیر درمی‌آید:

Numeral {_input: 1, _value: 1}

در این حالت Input به آرگومان numeral ارسال می‌شود که در این مورد 1 است و value نیز نتیجه ایجاد یک numeral برای آن عدد است. با استفاده از تابع value می‌توان به این عدد دسترسی یافت.

var newNum = numeral(1)
// 1 can also be passed as a string ('1').
newNum.value()
// 1

در این زمان، هنوز هیچ قالب‌بندی اعمال نشده است و از این رو 1 به صورت یک عدد معمولی نمایش می‌یابد. بنابراین اگر از 1.1 استفاده کنیم، ‌عدد 1.1 دیده می‌شود و همین طور در مورد همه اعداد دیگر. با استفاده از یک تابع Numeral به نام format می‌توانیم یک قالب‌بندی خاص را اعمال کنیم.

Format-ها

کتابخانه Numeral.js دارای قالب‌بندی‌های داخلی برای اعداد، پول‌ها، ‌بایت‌ها، ‌درصدها، زمان‌ها و هزینه‌ها است. این قالب‌ها به صورت آرگومان‌های رشته‌ای هستند که می‌توانند روی یک numeral اعمال شوند. شیوه استفاده از این قالب‌ها به صورت زیر است:

var newNum = numeral(1).format(SOME_FORMAT)

SOME_FORMAT می‌تواند چیزی شبیه به '+0.0' باشد. اگر این قالب‌بندی را روی 1 اعمال کنیم، newNum به صورت 0.1+ درمی‌آید. این قالب‌بندی یک علامت بعلاوه به ابتدای عدد اضافه کرده و یک 0. به انتهای آن می‌افزاید. اگر بخواهیم 1 به صورت درصد نمایش یابد، می‌توانیم از آرگومان '0%' به عنوان قالب استفاده کنیم. بدین ترتیب عدد به صورت 100% درمی‌آید. اگر بخواهیم مقدار 1% نمایش پیدا کند، باید 0.01 را به عنوان آرگومان برای numeral ارسال کنیم. برای مشاهده فهرست کامل این قالب‌ها می‌توانید به بخش formats در صفحه Numeral (+)‌ مراجعه کنید.

اکنون که با شیوه ایجاد یک وهله از numeral با ارائه عدد و قالب مربوطه آشنا شدیم، نوبت آن رسیده که یک کاربرد مهم دیگر این کتابخانه یعنی locales را بررسی کنیم.

Locales

قابلیت locales یکی از بخش‌های محبوب کتابخانه Numeral.js محسوب می‌شود. به این ترتیب می‌توانید اعداد را بر مبنای یک locale خاص که ارائه 0می‌شود، قالب‌بندی کنید. این قابلیت در مواردی که بخواهید یک ارز را مشخص سازید، بسیار به کار می‌آید.

نکته: برای استفاده از local-های داخلی باید از دستور زیر در کامپوننتی که از numeral بهره می‌گیرد، استفاده کنید:

import locales from "numeral.locales"

در غیر این صورت امکان دسترسی به locale-ها وجود نخواهد داشت. برای این که یک locale را روی یک وهله numeral تنظیم کنید باید از دستور زیر کمک بگیرید:

numeral.locale(LOCALE_CODE)

بدین ترتیب LOCALE_CODE به صورت یک locale برای وهله numeral انتساب می‌یابد. برای دیدن فهرست کامل locale-های پشتیبانی شده که از سوی Numeral ارائه می‌شود، به این ریپوی گیت‌هاب (+) مراجعه کنید.

با این که کتابخانه Numeral.js از فهرست نسبتاً جامعی از locale-ها پشتیبانی می‌کند، اما ممکن است در مواردی بخواهید از یک locale مانند United Arab Emirates بهره بگیرید که ارائه نشده است. در این موارد باید locale موردنظرتان را با استفاده از تابع register این کتابخانه ثبت کنید.

به این منظور کافی است کد locale و نماد ارز آن را بدانید. برای مشاهده فهرست کامل locale-های سراسر دنیا به این صفحه (+) ‌مراجعه کنید. کد ar به Arabic اشاره می‌کند و ae اختصاص به Arab Emirates دارد. کد زیر را در کامپوننتی که می‌خواهید در آن از لوکال UAE استفاده کنید، قرار دهید:

1numeral.register("locale", "ar-ae", {
2   delimiters: {
3      thousands: " ",
4      decimal: ","
5   },
6   abbreviations: {
7      thousand: "k",
8      million: "m",
9      billion: "b",
10      trillion: "t"
11   },
12   currency: {
13      symbol: "د.إ" //The currency for UAE is called the Dirham
14   }
15});

شیء locale شامل delimiters است که برای قالب‌بندی اعداد استفاده می‌شود. دو جداکننده شامل thousands یعنی نماد مورد استفاده برای جداسازی هزارگان و decimal یعنی نماد مورد استفاده برای جداسازی مقادیر اعشاری هستند. در مورد دلار ایالات متحده این جداکننده به صورت زیر است:

1delimiters: {
2      thousands: ",",
3      decimal: "."
4}

نکات کلیدی abbreviations در مورد اختصارسازی این است که تنها در صورتی استفاده می‌شود که کاربر اعداد را به صورت حروفی قالب‌بندی کند یعنی 1000 به صورت 1k نوشته شود. در نهایت خصوصیت currency به شیئی اشاره دارد که یک خصوصیت برای نماد پول دارد. در ادامه مثالی از ثبت locale مربوط به ایالات متحده (US) را می‌بینید:

1numeral.register("locale", "en", {
2   delimiters: {
3      thousands: ",",
4      decimal: "."
5   },
6   abbreviations: {
7      thousand: "k",
8      million: "m",
9      billion: "b",
10      trillion: "t"
11   },
12   currency: {
13      symbol: "$"
14   }
15});

خصوصیت دیگری که می‌توانید در تابع register مربوط به local قرار دهید، ordinal نام دارد. خصوصیت ordinal به تابعی اشاره می‌کند که یک توضیح برای ترتیب و موقعیت عدد از قبیل st, nd, rd, th به ترتیب برای اول، دوم، سوم، ‌چهارم و غیره تعیین می‌کند. در ادامه مثالی از یک خصوصیت ordinal می‌بینید.

1ordinal: function (number) {
2   var b = number % 10;            
3   return (~~ (number % 100 / 10) === 1) 
4     ? 'th' : (b === 1) 
5     ? 'st' : (b === 2) 
6     ? 'nd' : (b === 3) 
7     ? 'rd' : 'th';        
8}

با این که تابع register برای ثبت یک locale استفاده می‌شود، اما می‌توان از آن برای ثبت یک قالب سفارشی نیز استفاده کرد. کارهای بسیار زیاد دیگری وجود دارند که می‌توان با استفاده از کتابخانه Numeral.js انجام داد، ‌اما امیدواریم این مقدار موجب شده باشد تا شما دست کم با امکانات مقدماتی این کتابخانه آشنا شوید.

اگر این مطلب برای شما مفید بوده است، آموزش‌های زیر نیز به شما پیشنهاد می‌شوند:

• مجموعه آموزش‌‌های جاوا اسکریپت
• مجموعه آموزش‌های برنامه‌‌نویسی
• آموزش جاوا اسکریپت (JavaScript)
• آموزش جاوا اسکریپت — مجموعه مقالات جامع وبلاگ فرادرس
• ساخت انتخابگر تاریخ در جاوا اسکریپت — از صفر تا صد

==