مبلغ

فیلد مبلغ با جداکنندهٔ هزارگان فارسی، واحد پول و نمایش مبلغ به حروف.

import { PriceInput } from "@kashi-ui/react";

نمونه

مبلغ به حروف زیر فیلد نمایش داده می‌شود تا کاربر مطمئن شود صفرها را درست وارد کرده است؛ اشتباهی رایج و پرهزینه در پرداخت‌ها.

مبلغ پرداخت

تومان

یک میلیون و دویست و پنجاه هزار تومان

مقدار عددی: 1,250,000

<PriceInput
label="مبلغ پرداخت"
name="amount"
max={500_000_000}
onValueChange={(amount) => console.log(amount)}
/>

رفتار

قالب‌بندی: جداکنندهٔ هزارگان فارسی (٬) هنگام تایپ اضافه می‌شود و مکان‌نما سر جایش می‌ماند.
به حروف: «یک میلیون و دویست و پنجاه هزار تومان». با showWords={false} خاموش می‌شود.
واحد: پیش‌فرض «تومان»؛ با unit="ریال" یا هر متن دیگری عوض می‌شود.
مقدار: عدد (number) یا null برای فیلد خالی. صفرهای ابتدایی حذف می‌شوند. تا ۱۵ رقم.
محدوده: با min و max، پس از خروج از فیلد پیام خطا نمایش داده می‌شود.

ویژگی‌ها

نام	نوع	پیش‌فرض	توضیح
`value`	`number \| null`	—	مقدار کنترل‌شده
`defaultValue`	`number \| null`	—	مقدار اولیه
`onValueChange`	`(value: number \| null) => void`	—	با هر تغییر
`unit`	`ReactNode`	`"تومان"`	واحد پول کنار فیلد
`showWords`	`boolean`	`true`	نمایش مبلغ به حروف در متن راهنما
`min / max`	`number`	—	محدودهٔ مجاز
`rangeMessage`	`(min?, max?) => ReactNode`	`خودکار`	پیام خطای محدوده
`digits`	`"fa" \| "latin"`	`"fa"`	خط ارقام نمایشی
`name`	`string`	—	نام فیلد مخفی فرم با مقدار عددی خام

بدون React

import { numberToWords, formatNumber } from "@kashi-ui/persian";

numberToWords(1250000); // "یک میلیون و دویست و پنجاه هزار"
formatNumber(1250000);  // "۱٬۲۵۰٬۰۰۰"

دسترس‌پذیری

مبلغ به حروف در متن راهنما است و با aria-describedby به فیلد متصل است؛ صفحه‌خوان پس از نام فیلد آن را می‌خواند.
واحد پول کنار فیلد نمایش داده می‌شود؛ آن را در برچسب هم تکرار کنید اگر برای فهم فیلد ضروری است.