رفتن به محتوای اصلی
نیکاوب
محصول دانلودی برای توسعه‌دهنده‌ها

پکیج اعداد و مبالغ فارسی برای React و جاوااسکریپت

هر سایت فارسی دیر یا زود به همین چند مسئله می‌خورد: ارقامی که کاربر با کیبورد فارسی می‌نویسد، قیمتی که باید «۱٬۲۵۰٬۰۰۰ تومان» نمایش داده شود و به API عدد ۱۲۵۰۰۰۰ برسد، و فیلد مبلغی که موقع تایپ جداکننده بگذارد و نشانگر را گم نکند. این پکیج همه را یک بار و درست حل کرده است.

  • بدون هیچ وابستگی
  • TypeScript کامل
  • React، Next.js و جاوااسکریپت خالص
  • هسته کامل ۴ کیلوبایت فشرده
  • ۱۷۰ تست خودکار
  • ESM و CommonJS

پرداخت یک‌باره از درگاه بانکی، دانلود فوری بعد از پرداخت.

تومان
formatToman(value)
۱٬۲۵۰٬۰۰۰ تومان
formatRial(tomanToRial(value))
۱۲٬۵۰۰٬۰۰۰ ریال
onValueChange → value
1250000
detail.text
'1250000'
چرا

سه ایرادی که هر سایت فارسی دارد

ارقام فارسی از کیبورد

کاربر موبایلش را با کیبورد فارسی می‌نویسد: «۰۹۱۲…». هیچ اعتبارسنجی‌ای که با \d نوشته شده آن را قبول نمی‌کند و فرم بی‌دلیل خطا می‌دهد.

منفی که جابه‌جا می‌شود

در متن راست‌به‌چپ، علامت منفی به سمت راست عدد می‌پرد و «منفی ۱۲۵ هزار» شبیه عددی مثبت با یک خط تیره اضافه می‌شود. نمونه‌اش را پایین همین بخش ببینید.

قیمت‌های ناهمخوان

یک صفحه «1,200,000»، صفحه دیگر «۱٬۲۰۰٬۰۰۰ تومان» و فرم پرداخت «۱۲۰۰۰۰۰۰ ریال». هر بار یک تابع کوچک تازه، هر بار با یک ایراد تازه.

با خط تیره معمولی: علامت سمت راست عدد می‌افتد

موجودی حساب: -۱۲۵٬۰۰۰ تومان

درست، با formatToman(-125000)

موجودی حساب: ‎−۱۲۵٬۰۰۰ تومان

دمو زنده

فیلد عدد و مبلغ برای React

همان کامپوننتی که دانلود می‌کنید. گزینه‌ها را عوض کنید و کد لازم را پایین فیلد ببینید.

حالت
ارقام
اعشار
عدد منفی
حداقل و حداکثر
پیشوند و پسوند

پیش‌فرض‌ها به حالت بستگی دارند: تومان و ریال عدد صحیح و بدون منفی‌اند و واحدشان کنار عدد می‌آید.

تومان
value
null
detail.text
''
detail.formatted
''
<PersianNumberInput
  mode="toman"
  onValueChange={(value, { text }) => setPrice(value)}
/>

این‌ها را امتحان کنید

  • وسط عدد رقم تایپ کنید؛ نشانگر همان‌جا می‌ماند.
  • درست بعد از جداکننده Backspace بزنید؛ رقم قبلی پاک می‌شود.
  • «۱٬۲۵۰٬۰۰۰ تومان» یا «1.250.000» را کپی و Paste کنید.
  • با ↑ و ↓ عدد را کم و زیاد کنید؛ با Shift ده‌تا‌ده‌تا.
  • حالت «عدد» را بزنید و علامت منفی را هر جای عدد تایپ کنید.
  • بازه را روی «۰ تا ۱۰۰» بگذارید، ۵۰۰ بنویسید و از فیلد بیرون بیایید.
توابع

قالب‌بندی و خواندن عدد، هر جا که کد اجرا شود

مرورگر، Node، Server Component یا Edge. هر تابع جدا import می‌شود و بقیه از باندل حذف می‌شوند.

تبدیل ارقام

toPersianDigits(text)
سفارش ۴۸۲۱ — موبایل ۰۹۱۲۳۴۵۶۷۸۹ — ۴۵۶
toEnglishDigits(text)
سفارش 4821 — موبایل 09123456789 — 456

خواندن عدد از متن

parsePersianNumber(text)
1250000
normalizeNumber(text)
'1250000'

قالب‌بندی عدد

اعشار
formatPersianNumber(n)
۱٬۲۳۴٬۵۶۷٫۸۹۱
formatNumber(n)
1,234,567.891

تومان و ریال

ریال
formatRial(rial)
۱۲٬۵۰۰٬۰۰۰ ریال
formatToman(rialToToman(rial))
۱٬۲۵۰٬۰۰۰ تومان
formatToman(t, { digits: 'en' })
1,250,000 تومان

درصد

ورودی
formatPercent(n, { ratio: true })
۷٫۵٪
… { digits: 'en' }
7.5%

همه توابع عدد، رشته با هر نوع رقم، و bigint می‌گیرند و برای مقدار خالی یا نامعتبر متن جایگزین برمی‌گردانند، نه «NaN».

گرد کردن روی رقم‌های اعشاری انجام می‌شود، نه اعداد اعشاری جاوااسکریپت؛ برای همین ۷٪ همان ۷٪ است، نه ۷٫۰۰۰۰۰۰۰۰۰۰۰۰۰۰۱٪.

استفاده

نصب و چند خط کد

نصب
# the .tgz from the download, copied into your project
npm install ./vendor/nikaweb-persian-number-toolkit-1.0.0.tgz
توابع (TypeScript)
import {
  toPersianDigits, toEnglishDigits,
  formatToman, formatRial, formatPercent,
  parsePersianNumber, rialToToman,
} from '@nikaweb/persian-number-toolkit'

toPersianDigits('123456')              // '۱۲۳۴۵۶'
toEnglishDigits('۰۹۱۲۳۴۵۶۷۸۹')         // '09123456789'
formatToman(1250000)                   // '۱٬۲۵۰٬۰۰۰ تومان'
formatToman(rialToToman(12500000))     // '۱٬۲۵۰٬۰۰۰ تومان'
formatPercent(0.075, { ratio: true })  // '۷٫۵٪'
parsePersianNumber('۱٬۲۵۰٬۰۰۰ تومان')  // 1250000
جاوااسکریپت خالص، بدون ابزار ساخت
<input id="price">
<input type="hidden" name="price" id="price-value">

<script src="/js/persian-number-toolkit.global.js"></script>
<script>
  const { bindNumberInput, formatToman } = PersianNumber

  bindNumberInput(document.getElementById('price'), {
    mode: 'toman',
    mirror: document.getElementById('price-value'),
    onValueChange: (value) => console.log(formatToman(value)),
  })
</script>
React
'use client'
import { useState } from 'react'
import { PersianNumberInput } from '@nikaweb/persian-number-toolkit/react'

export function PriceField() {
  const [price, setPrice] = useState<number | null>(null)
  return (
    <PersianNumberInput
      mode="toman"
      value={price}
      onValueChange={setPrice}
      max={500_000_000}
    />
  )
}
Next.js با Server Action
// app/checkout/page.tsx — a Server Component, no 'use client'
import { PersianNumberInput } from '@nikaweb/persian-number-toolkit/react'
import { parsePersianNumber } from '@nikaweb/persian-number-toolkit'

async function pay(formData: FormData) {
  'use server'
  const amount = parsePersianNumber(String(formData.get('amount'))) // 750000
}

export default function Checkout() {
  return (
    <form action={pay}>
      <PersianNumberInput name="amount" mode="toman" min={10_000} />
      <button>پرداخت</button>
    </form>
  )
}
داخل فایل

چه چیزی دانلود می‌کنید

کد منبع کامل TypeScript
همه ماژول‌ها، قابل تغییر، با توضیح کنار کد.
۱۷۰ تست
تست واحد و تست کامپوننت با تایپ و Paste واقعی، و اسکریپتی که خروجی ساخته‌شده را مثل یک مصرف‌کننده امتحان می‌کند.
نسخه آماده نصب
فایل tgz برای npm، pnpm و yarn، به‌علاوه ESM، CommonJS، تایپ‌ها و نسخه تگ script.
مستندات
README و مرجع کامل API به انگلیسی، با همه گزینه‌ها و رفتارهای مرزی.
مثال‌ها
Node، TypeScript، React، Next.js (Server Component و Server Action) و HTML خالص.
استایل پیش‌فرض
یک فایل CSS کوچک با متغیرهای قابل تنظیم؛ اختیاری.
پرسش‌ها

قبل از خرید

بلافاصله بعد از تأیید پرداخت، در همان صفحه دکمه دانلود نمایش داده می‌شود. لینک تا ۷ روز کار می‌کند؛ فایل را همان موقع دانلود کنید و نگه دارید.

در هر تعداد پروژه برای خودتان یا مشتری‌هایتان، تجاری یا غیرتجاری. فروش دوباره پکیج یا انتشار عمومی کد منبعش، مثلاً در npm یا یک مخزن عمومی، مجاز نیست. متن کامل مجوز داخل فایل است.

توابع قالب‌بندی و خواندن عدد به هیچ فریم‌ورکی وابسته نیستند و همه‌جا اجرا می‌شوند. برای فیلد ورودی، تابع bindNumberInput روی هر input معمولی کار می‌کند و نسخه تگ script هم برای سایت‌های بدون ابزار ساخت هست.

بله. توابع قالب‌بندی در Server Component اجرا می‌شوند و کامپوننت ورودی از قبل «use client» دارد. با ویژگی name، مقدار خام عدد مستقیم به Server Action می‌رسد.

بله، کامل و همراه با تست‌ها و تنظیمات ساخت. می‌توانید تغییرش دهید و دوباره بسازید.

README و مرجع API به انگلیسی نوشته شده‌اند، مثل بیشتر پکیج‌های npm. مثال‌ها متن فارسی دارند و همین صفحه هم همه قابلیت‌ها را به فارسی نشان می‌دهد.

یک بار بخرید، در همه پروژه‌ها استفاده کنید

۲۳۹٬۰۰۰ تومان، پرداخت یک‌باره، دانلود فوری · نسخه ۱.۰.۰

خرید و دانلود